リソース権限要求

PocketSign Link v2 の認可では、単に openid を要求するだけでなく、どのリソースにどの操作を許可してほしいのかを明示できます。 このページでは、scope、authorization_details、claims、grant_management_action の関係を整理します。 authorization_details のフィールドごとの意味や、同意画面・すでに許可された権限との関係を詳しく見たい場合は authorization_details と同意モデル を参照してください。

標準スコープ

スコープ	意味
openid	ID トークンの発行を要求します
offline_access	リフレッシュトークンの発行を要求します
profile	name, gender, birthdate に対応する読み取り権限をまとめて要求します
email	email, email_verified に対応する読み取り権限を要求します
address	address に対応する読み取り権限を要求します
phone	phone_number, phone_number_verified に対応する読み取り権限を要求します
personal_info	基本 4 情報に対応する読み取り権限をまとめて要求します

profile や email は、単なる表示用ラベルではなく、対応するリソースアクセス要求として扱われます。

リソース権限要求スコープ

個別のリソース権限をスコープ形式で要求することもできます。

urn:klon:resource_access.<action>:<resource-id-or-alias>

アクション

現在の実装では次のアクションを解釈します。

• read
• write
• invoke

例:

openid offline_access urn:klon:resource_access.read:klon/email

リソース権限要求スコープは、authorization_details と同等のリソースアクセス要求として扱われます。 スコープ形式で要求した権限は、required=true かつ prefill=true として解釈されます。

authorization_details

PocketSign Link v2 は RFC 9396 の考え方に沿って、構造化された認可要求を受け付けます。 現在サポートしている type は urn:klon:resource_access のみです。

[
  {
    "type": "urn:klon:resource_access",
    "identifiers": ["klon/email", "my_org/favorite-food"],
    "actions": ["read"],
    "required": true,
    "prefill": true
  }
]

フィールド

フィールドの詳細は authorization_details のフィールドリファレンスを参照してください。

補足

• 不正な type や空の identifiers / actions はエラーになります
• 同じ意味の要求は重複しない 1 つの要求として扱われます
• scope と authorization_details を併用した場合、要求は和集合で扱われます

claims

現在の実装では、claims パラメータのうち id_token.acr のみサポートされます。

{
  "id_token": {
    "acr": {
      "essential": true,
      "values": ["urn:klon:acr:high"]
    }
  }
}

claims.id_token.acr に必須要求がある場合、acr_values よりも優先されます。

grant_management_action

KLON は 1 ユーザー × 1 クライアントに対して、現在有効な権限集合を 1 つのグラントとして管理します。 grant_management_action により、既存グラントをどう扱うかを指定できます。

各アクションの動作は grant_management_action を参照してください。

トークンへの影響

grant 更新操作が既存トークンへ与える影響は トークンの仕様とライフサイクル を参照してください。

同意画面との関係

• create で既存グラントがなく、または要求を満たさない場合は同意が必要です
• replace は常に同意が必要です
• merge は差分があるときだけ同意が必要です
• prompt=consent を付けると、再利用可能でも同意画面を表示します