認可リクエスト

GET /api/oidc/v1/authorize は、PocketSign Link v2 の認証認可フローの入口です。 未ログインであればログインへ、追加確認が必要であれば再認証へ、権限確認が必要であれば同意画面へ遷移し、最終的にサービスに認可コードまたはエラーを返します。

:::info この章と標準仕様の関係 標準仕様としては、OAuth 2.0 Authorization Framework、OpenID Connect Core 1.0、PKCE (RFC 7636)、Pushed Authorization Requests (RFC 9126) に対応する内容です。 PocketSign Link v2 固有の点:

• /auth/reauth や /auth/consent への画面遷移
• Registry と既存グラントを使った同意スキップ判定 :::

認可リクエストの基本形

GET /api/oidc/v1/authorize

主なクエリパラメータは以下の通りです。

パラメータ	必須	説明
client_id	はい	OIDC クライアント ID
redirect_uri	はい	コールバック先 URI。事前登録済みの URI と完全一致する必要があります
response_type	はい	code 固定です
scope	はい	要求するスコープ群。openid を含めると ID トークンが発行されます。offline_access を含めるとリフレッシュトークンが発行されます。
state	条件付き	サービス 側のリクエストとコールバックを対応付ける値です
code_challenge	条件付き	PKCE のチャレンジ値です
code_challenge_method	条件付き	S256 のみサポートします
nonce	いいえ	ID トークンの nonce に反映されます
prompt	いいえ	none, login, consent を指定できます
max_age	いいえ	最終認証から許容する最大経過秒数です
acr_values	いいえ	要求する認証強度を優先順に指定します
authorization_details	いいえ	構造化された権限要求を指定します
grant_management_action	いいえ	create, replace, merge を指定できます
request_uri	いいえ	PAR で発行した request_uri を指定します

バリデーション上の注意

• redirect_uri は必須で、事前登録済み URI との完全一致が必要です
• response_type は code のみサポートします
• prompt=none は他の prompt と併用できません
• state または PKCE のどちらか一方は必須です
• PKCE を使う場合、code_challenge_method は S256 のみです
• max_age は 0 以上の整数でなければなりません
• request_uri を使う場合、client_id の一致検証と有効期限検証が行われます

認可リクエストの分岐

未ログインの場合

• prompt=none の場合は、ログイン画面を出さずに login_required を返します
• それ以外の場合はログイン導線へリダイレクトします

ログイン済みだが再認証が必要な場合

次のいずれかに当てはまると再認証が必要です。

• prompt=login が指定された
• max_age を超過した
• 現在のセッションの ACR が要求 ACR を満たさない

その状態で:

• prompt=none なら interaction_required を返します
• 利用可能な再認証手段がなければ unmet_authentication_requirements を返します
• 再認証可能なら再認証導線へ遷移します

再認証不要で同意判定に進める場合

要求されたスコープと authorization_details を、既にユーザーが許可している権限と比較し、

• 既に要求権限を満たしている場合は、同意画面をスキップできます
• prompt=consent が指定されている場合は、スキップ可能でも同意画面を表示します
• prompt=none かつ同意が必要な場合は consent_required を返します

シーケンス

Pushed Authorization Requests

POST /api/oidc/v1/par を使うと、認可リクエストのパラメータ一式を事前に登録し、request_uri を発行できます。

使いどころ

• authorization_details が大きく、クエリ文字列が長くなりやすい場合
• 認可リクエストの内容をブラウザで改変されにくくしたい場合
• サービス 側で認可リクエストをサーバー間通信として確定させたい場合

リクエスト

POST /api/oidc/v1/par では、authorize に渡すのと同じパラメータをフォームで送信します。 このエンドポイントではクライアント認証が必要です。client_secret_basic、client_secret_post、private_key_jwt のいずれかで認証します。 詳細は トークン を参照してください。

レスポンス

フィールド	説明
request_uri	認可リクエストの request_uri パラメータで指定する値
expires_in	request_uri の有効期間(秒)

request_uri 利用時の認可リクエスト

PAR を使う場合の認可リクエストは、原則として次の 2 つだけを送ります。

• client_id
• request_uri

request_uri は使い捨てで、消費後は再利用できません。

主なエラー

エラー	主な発生条件
invalid_request	必須パラメータ不足、不正な prompt、不正な max_age など
invalid_request_uri	request_uri が見つからない、期限切れ、client_id が一致しない
unsupported_response_type	response_type=code 以外が指定された
invalid_scope	不正なスコープが要求された
login_required	prompt=none で未ログインだった
interaction_required	prompt=none で再認証が必要だった
consent_required	prompt=none で同意が必要だった
unmet_authentication_requirements	要求 ACR を満たす再認証手段がない
access_denied	ユーザーが同意を拒否した