プレビュー版

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

トークンの仕様とライフサイクル

このページでは、PocketSign Link v2 のアクセストークン、refresh_token、ID トークンについて、形式、発行条件、保存の考え方、失効、再発行までをまとめます。 API パラメータそのものはトークンに譲り、このページでは「発行された後にどう扱われるか」を中心に説明します。

トークン種別ごとの一覧

種別	形式	発行条件	主な用途
アクセストークン	JWT	認可コード交換時、またはリフレッシュ時	`userinfo` や Resource Server API 呼び出し
リフレッシュトークン	不透明トークン	`offline_access` が付与されたとき	新しいアクセストークンの取得
ID トークン	署名付き JWT	`openid` が付与されたとき	サービスが認証結果を受け取る

アクセストークン

アクセストークンは、 JWT 形式で発行されます。サービスや Resource Server は、署名検証に加えて必要に応じて Token Introspection エンドポイントで有効性を確認できます。

アクセストークンの主なクレーム

アクセストークンのクレーム一覧はトークンを参照してください。

`merge` 時の注意

grant_management_action=merge では、既存アクセストークンは失効しません。ただし、そのトークンは追加前の権限集合しか持たないため、追加権限を使うには新しく発行されたアクセストークンを使う必要があります。

リフレッシュトークン

リフレッシュトークンは不透明トークンとして発行されます。

通常の更新動作

通常のブラウザ向けフローでは、リフレッシュ時に refresh token はローテーションされます。

受け取った refresh token を検証する
その refresh token を失効する
新しい access token を発行する
新しい refresh token を発行する

いつ無効になるか

自身の有効期限を過ぎたとき
自身がローテーションで消費されたとき
grant_management_action=replace または grant_management_action=merge の影響で失効したとき

`merge` 時の挙動

merge では既存アクセストークンは維持されますが、既存リフレッシュトークンは失効します。そのため、追加権限同意後に返ってきた新しい refresh token へ差し替える必要があります。

ID トークン

ID トークンは openid スコープが付与されたときに返る署名付き JWT です。サービスはこれを使って、認証結果と属性スナップショットを受け取ります。

主なクレーム

ID トークンのクレーム一覧およびスコープに応じて追加されるクレームはトークンを参照してください。

いつ発行されるか

アクセストークン取得成功時に、scope に openid を含んでいれば再発行されます

スナップショットとしての性質

PocketSign Link v2 では、認可コード交換時に ID トークンへ入れる属性を読み出し、そのスナップショットを保持します。リフレッシュ時に再発行される ID トークンは、この保持済みスナップショットを再利用します。

つまり、次のように考えると分かりやすいです。

認可直後の ID トークン: その時点の認証結果と属性
リフレッシュ後の ID トークン: 新しい iat / exp を持つが、属性は元のスナップショットを引き継ぐ
最新属性が必要な場合: userinfo を使う

`nonce`

初回の認可コード交換で発行される ID トークンには、認可リクエストで送った nonce が反映されます。サービスは ID トークンの nonce を照合してください。

失効の考え方

ID トークンはアクセストークンやリフレッシュトークンのように Token Introspection / Revoke エンドポイントで扱う前提のトークンではありません。サービス側では、署名、iss、aud、exp、nonce を検証し、必要に応じて新しい認可フローやリフレッシュで再取得します。

同意済み権限の更新が既存トークンへ与える影響

PocketSign Link v2 では、同意結果に応じて create、reuse、replace、merge のいずれかの操作が選ばれます。その結果、既存トークンへの影響は次のようになります。

操作	Access Token	Refresh Token
`create`	失効	失効
`create`(すでに権限が包含されていた場合)	失効なし	失効なし
`replace`	失効	失効
`merge`	失効なし	失効

revoke の影響

POST /api/oidc/v1/revoke では、指定したトークン単体だけでなく、紐づくアクセストークン、リフレッシュトークンのすべてを失効させます。

トークン種別ごとの一覧​

アクセストークン​

アクセストークンの主なクレーム​

merge 時の注意​

リフレッシュトークン​

通常の更新動作​

いつ無効になるか​

merge 時の挙動​

ID トークン​

主なクレーム​

いつ発行されるか​

スナップショットとしての性質​

nonce​

失効の考え方​

同意済み権限の更新が既存トークンへ与える影響​

revoke の影響​

関連ページ​