プレビュー版

PocketSign Link v2 は現在プレビュー版です。正式提供までに仕様が変更される可能性があります。

`authorization_details` と同意モデル

このページでは、PocketSign Link v2 で個別リソース権限を要求するときの authorization_details と、その要求が同意画面や既存グラントにどう影響するかを整理します。

`authorization_details` の役割

PocketSign Link v2 では、Registry リソースに対する権限要求を、構造化された authorization_details で表現できます。単なる scope より細かく、どのリソースにどの操作を要求するかを明示できます。

サポートする `type`

現時点でサポートする type は 1 つです。

`type`	意味
`urn:klon:resource_access`	Registry リソースへの権限要求

基本形

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

フィールドリファレンス

フィールド	必須	説明
`type`	はい	`urn:klon:resource_access` 固定
`identifiers`	はい	リソース定義 ID またはエイリアスの配列
`actions`	はい	要求する操作の配列
`required`	いいえ	拒否されたら認可フロー自体を継続できない要求
`prefill`	いいえ	値未登録時に、認可フロー内で入力を要求したい意図

`identifiers`

identifiers には、Registry に登録されているリソース定義の ID またはエイリアスを入れます。

例:

{
  "identifiers": ["my_org/account_profile", "klon/email"]
}

`actions`

現在の実装では、次を使います。

値	対応する意味
`read`	値の取得
`write`	値の更新
`invoke`	実行リソースの呼び出し

Registry API との対応

`actions`	実際の利用先のイメージ
`read`	`ReadResourceValue` / `ReadResourceValues`
`write`	`WriteResourceValue` / `DeleteResourceValue`
`invoke`	実行リソース利用時の権限判定

`required`

required=true は、その要求が満たされないと認可フローを継続できないことを意味します。

イメージ

required=true: この権限がないとサービス機能が成り立たない
required=false: なくても基本機能は成立する

同意画面との関係

ユーザーが required=true の要求を拒否すると、認可成功に進めません
optional な要求なら、サービス側で機能劣化を許容する設計ができます

`prefill`

prefill=true は、そのリソース値が未登録なら、認可フローの中で値入力や登録を促したい意図を表します。

向いている場面

初回同意時に最低限必要なプロフィール入力を終わらせたい
権限付与と同時に値の存在も満たしたい

注意点

prefill=true は値入力体験まで含む要求です
単に読み取りたいだけなら prefill=false のほうが分かりやすいことがあります

`scope` との関係

PocketSign Link v2 では、標準スコープや urn:klon:resource_access.* 形式のスコープ要求も使えます。ただし、個別リソース制御では authorization_details のほうが意図を表しやすいです。

`scope` との対応

リソース権限要求スコープは authorization_details と同等の権限要求として扱われる
scope と authorization_details を併用した場合、要求は和集合で扱われる

正規化の考え方

PocketSign Link v2 は同じ意味の要求を重複しない 1 つの要求として扱います。

実装側で意識するとよいこと

同じリソース・同じアクションを重複送信しない
スコープと authorization_details の二重指定をむやみに増やさない
同意画面に見せたい粒度を意識して設計する

同意モデル

KLON は、1 ユーザー × 1 クライアントに対して有効な同意記録を保存します。すでに同意した権限に対し、要求した権限をどう扱うかをgrant_management_action が決めます。

アクション	すでに同意した権限がない場合	すでに同意した権限がある場合
`create`	新規作成	要求を内包していれば再利用、足りなければユーザーに同意を求める
`replace`	新規作成	ユーザーに同意を求め、同意記録を要求した権限で置換する（以前の権限は保持されない）
`merge`	新規作成	すでに同意した権限との差分を追加

トークンへの影響

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

実装パターン

初回ログインで必須権限を取る

required=true
prefill=false
必要なら PAR と組み合わせる

初回ログインでは最小権限にする

初回は openid 中心
後から merge で追加要求

値登録まで同時に要求する

prefill=true
同意画面の体験設計を意識する

authorization_details の役割​

サポートする type​

基本形​

フィールドリファレンス​

identifiers​

actions​

Registry API との対応​

required​

イメージ​

同意画面との関係​

prefill​

向いている場面​

注意点​

scope との関係​

scope との対応​

正規化の考え方​

実装側で意識するとよいこと​

同意モデル​

トークンへの影響​

実装パターン​

初回ログインで必須権限を取る​

初回ログインでは最小権限にする​

値登録まで同時に要求する​

関連ページ​