後から追加のリソースへのアクセス権限を要求する

初回ログイン時には最小権限だけを取り、後から新機能を使うタイミングで追加権限だけを要求したい場合のフローです。 段階的な権限付与では、grant_management_action=merge が中心になります。

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

• 既存グラントに新しい権限だけを追加する
• 必要な差分があるときだけ同意画面を出す
• 追加権限を含む新しいアクセストークンとリフレッシュトークンを受け取る

フロー図

par で送るパラメータ

ここでは、既存のログイン連携に対して my_org/account_export の読み取り権限を追加する例を示します。

パラメータ	例	役割
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	cc91...	サービス側の対応付け
nonce	00ea...	ID トークン検証用
code_challenge	xxxxxxx	PKCE
code_challenge_method	S256	PKCE の方式
grant_management_action	merge	既存グラントに差分を追加
authorization_details	下記 JSON	新たに欲しい権限

[
  {
    "type": "urn:klon:resource_access",
    "identifiers": ["my_org/account_export"],
    "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=cc91..." \
  --data-urlencode "nonce=00ea..." \
  --data-urlencode "code_challenge=xxxxxxx" \
  --data-urlencode "code_challenge_method=S256" \
  --data-urlencode "grant_management_action=merge" \
  --data-urlencode 'authorization_details=[{"type":"urn:klon:resource_access","identifiers":["my_org/account_export"],"actions":["read"],"required":true,"prefill":false}]'

認可エンドポイントとトークンエンドポイント

ブラウザ遷移は通常の PAR 利用時と同じです。

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"

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

• grant_management_action=merge により、既存権限は維持したまま追加分だけを要求できる
• 追加権限を使うときは、今回取得した新しい access_token に切り替えて Registry API を呼ぶ
• 既存アクセストークンは残ることがありますが、新しい権限は含みません
• 既存リフレッシュトークンは無効化されるため、新しく返ったものへ置き換える

追加権限取得後に Registry を呼ぶ例

この例では my_org/account_export の 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 <NEW_ACCESS_TOKEN>" \
  -d '{
    "id_or_alias": "my_org/account_export"
  }'

必要なら、実際にどの権限が使えるようになったかを CheckPermissions で確認してから読み取りに進めます。

curl "https://registry.mock.klon.you/pocketsign.link.v2.RegistryUserService/CheckPermissions" \
  -H "Content-Type: application/json;charset=utf-8" \
  -H "Authorization: Bearer <NEW_ACCESS_TOKEN>" \
  -d '{
    "id_or_aliases": [
      "my_org/account_export"
    ]
  }'

旧トークンでは追加権限が含まれないため、merge 後の差分権限を使うリクエストには必ず新しい access_token を使います。

このフローが向く場面

• 初回登録では最小権限にとどめたい
• 新機能を使うタイミングでだけ追加同意を取りたい
• 同一クライアントの連携を保ったまま権限を段階的に拡張したい