ユーザーのリソースへのアクセス権限を要求する

サービスがログインだけでなく、ユーザーのリソースに対する読み取りや操作の権限もまとめて取得したい場合のフローです。 構造化された権限要求を送るため、この用途では PAR と authorization_details の組み合わせを基準にするのが分かりやすいです。

このフローで実現すること

• ログインと同時に、ユーザーリソースへの権限を要求する
• 同意画面で、どのリソースにどの操作を要求しているかを明示する
• トークンエンドポイントのレスポンスで最終的に付与された authorization_details を確認する

フロー図

PAR(Pushed Authorization Request)で送るパラメータ

以下の my_org/account_profile は、Registry に定義した自サービス用リソース ID の例です。

パラメータ	例	役割
client_id	7f3b41e2-a81c-4e35-b08d-2c7e60a4d073	OIDC クライアント ID
redirect_uri	https://rp.example.com/callback	コールバック先
response_type	code	Authorization Code Flow
scope	openid offline_access	ログインとリフレッシュトークン発行を要求
state	e341...	サービス側の対応付け
nonce	84c0...	ID トークン検証用
code_challenge	xxxxxxx	PKCE
code_challenge_method	S256	PKCE の方式
authorization_details	下記 JSON	要求するリソース権限

[
  {
    "type": "urn:klon:resource_access",
    "identifiers": ["my_org/account_profile"],
    "actions": ["read"],
    "required": true,
    "prefill": false
  }
]

curl -X POST "https://id.mock.klon.you/api/oidc/v1/par" \
  -u "7f3b41e2-a81c-4e35-b08d-2c7e60a4d073:client-secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=7f3b41e2-a81c-4e35-b08d-2c7e60a4d073" \
  --data-urlencode "redirect_uri=https://rp.example.com/callback" \
  --data-urlencode "response_type=code" \
  --data-urlencode "scope=openid offline_access" \
  --data-urlencode "state=e341..." \
  --data-urlencode "nonce=84c0..." \
  --data-urlencode "code_challenge=xxxxxxx" \
  --data-urlencode "code_challenge_method=S256" \
  --data-urlencode 'authorization_details=[{"type":"urn:klon:resource_access","identifiers":["my_org/account_profile"],"actions":["read"],"required":true,"prefill":false}]'

認可エンドポイントで送るパラメータ

PAR を使う場合、ブラウザ遷移では原則として次の 2 つだけを送ります。

パラメータ	例
client_id	7f3b41e2-a81c-4e35-b08d-2c7e60a4d073
request_uri	urn:ietf:params:oauth:request_uri:...

GET /api/oidc/v1/authorize
  ?client_id=7f3b41e2-a81c-4e35-b08d-2c7e60a4d073
  &request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A...

トークンエンドポイントで送るパラメータ

curl -X POST "https://id.mock.klon.you/api/oidc/v1/token" \
  -u "7f3b41e2-a81c-4e35-b08d-2c7e60a4d073:client-secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https://rp.example.com/callback" \
  -d "code_verifier=random-verifier"

サービス側で確認するポイント

• トークンエンドポイントのレスポンスの authorization_details で付与内容を確認する
• 実際の Registry API 呼び出しには新しく受け取ったアクセストークンを使う
• リソース ID は Registry に登録した識別子を使う

取得したトークンで Registry を呼ぶ例

上の例では my_org/account_profile の read 権限を要求しているため、認可後は UserService.ReadResourceValue でそのリソースを読み取れます。

curl "https://registry.mock.klon.you/pocketsign.link.v2.RegistryUserService/ReadResourceValue" \
  -H "Content-Type: application/json;charset=utf-8" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "id_or_alias": "my_org/account_profile"
  }'

レスポンスでは、result.value に実際のリソース値が入り、result.error で権限不足や未登録を判定できます。

{
  "result": {
    "id_or_alias": "my_org/account_profile",
    "subscription_id": "<SUBSCRIPTION_ID>",
    "value": {
      "json": {
        "display_name": "Taro Yamada",
        "plan": "premium"
      },
      "updated_at": "2026-03-17T00:00:00Z"
    },
    "error": "READ_RESOURCE_VALUE_ERROR_UNSPECIFIED"
  }
}

このフローが向く場面

• 初回ログインと同時に API 利用権限も取りたい
• 同意画面で要求権限を明示したい
• 後続の Registry API でアクセストークンを使いたい