リダイレクト版リファレンス

処理フロー

1. IdP が FIDO 登録または認証を開始します。登録時は、事前に IdP 側で既存認証または本人確認を行ってください。認証時は、IdP 側で事前認証を行わない構成も可能です。その場合、authnCtx は空文字列（"authnCtx":""）として id_token(A) に設定してください。
2. IdP は state を生成・保持したうえで、id_token(A)、src、pur、state を HTML form 等により POST して PKaaS へ遷移させます。登録時は、既存認証または本人確認の成功後に id_token(A) を発行してください。
3. PKaaS は id_token(A) を検証し、FIDO 登録または認証を実施します。
4. PKaaS は認証結果を含む HTML form を返します。ブラウザ上で auto-submit し、src で指定された戻り先へ id_token(B) と state を POST で返却します。
5. IdP は返却された state を保持値と照合し、照合成功時のみ id_token(B) を検証します。
6. 検証結果に応じて、IdP 側でログイン成立、登録完了、エラー処理等の後続処理を行います。

id_token について

リダイレクト版では、処理の前後で 2 種類の id_token を扱います。

• id_token(A): IdP から PKaaS へ処理開始のために送信するトークン
• id_token(B): PKaaS から IdP へ FIDO 登録または認証結果として返却するトークン

それぞれ役割が異なるため、実装時には混同しないよう注意してください。

id_token(A)

id_token(A) は、IdP が PKaaS に送信する、処理開始に必要なトークンです。

登録時には、IdP 側で既存認証または本人確認を完了したうえで、その認証方式を authnCtx に設定してください。

nonce を必ずクレームとして含めてください。

PKaaS はこのトークンを検証して、FIDO 登録または認証処理を開始します。

id_token(B)

id_token(B) は、PKaaS が FIDO 登録または認証の結果として IdP に返却するトークンです。

IdP はこのトークンを検証し、検証成功後に後続処理へ進みます。

JWT の形式

id_token(A)、id_token(B) はいずれも JWT 形式の文字列です。

JWT は以下の 3 つの要素を . で連結した形式です。

• Header
• Payload
• Signature

生成の流れは以下の通りです。

1. Header を JSON で作成する
2. Payload を JSON で作成する
3. Header と Payload をそれぞれ Base64URL エンコードする
4. Base64URL(header) + "." + Base64URL(payload) に対して署名を行う
5. Base64URL(header) + "." + Base64URL(payload) + "." + Base64URL(signature) を JWT として扱う

クレーム

Payload の中身として、以下のクレームを扱います。

iss

トークン発行者を表します。

• id_token(A) では IdP
• id_token(B) では PKaaS

aud

トークンの想定受信者を表します。

• id_token(A) では PKaaS
• id_token(B) では IdP

sub

利用者を識別する値です。

sub には、IdP が利用者に対して一意かつ継続的に付与する識別子を設定してください。

メールアドレスなど、変更されうる値や個人情報を直接含む値は指定しないでください。例: user1234

iat

トークン発行時刻（UNIXTIME）です。未来の日時を示すなど時刻に整合性がない場合は検証に失敗します。

exp

トークン有効期限（UNIXTIME）です。exp を超えた id_token は検証に失敗します。

nonce

nonce は、ID Token が当該処理に対応して発行されたものであることを確認するための値です。

主に ID Token の再利用や差し替えを検知するために利用します。

nonce は必須です。

state は認証要求と返却の対応確認に使う値であり、nonce とは役割が異なります。

IdP 側で生成し、id_token(A) に必ず含めてください。

nonce は id_token(B) にも含まれます。IdP 側では、返却された id_token(B) の nonce が id_token(A) に含めた nonce と一致することを確認してください。

authnCtx

authnCtx は、IdP 側で利用者を確認する際に実施した認証方式を表す値です。

登録時は、事前に IdP 側で実施した認証方式を設定してください。

登録時の設定例: "password"

認証時（pur=auth）は、事前に IdP 側で認証を行わない構成も可能です。その場合は "authnCtx":"" としてください。

id_token(B) では、FIDO 認証に成功した場合は "fido" が設定されます。

実装上の注意

• id_token(A) と id_token(B) は向きと役割が異なります。
• iss と aud は送受信方向に応じて逆になります。
• state と nonce は用途が異なります。state は要求と返却の対応確認、nonce は ID Token の再利用や差し替え検知に用います。
• nonce は必須です。IdP 側で生成し、id_token(A) にクレームとして含めてください。
• nonce は id_token(B) にも含まれます。IdP 側では、返却された id_token(B) の nonce が id_token(A) に含めた nonce と一致することを確認してください。
• 登録時は、IdP 側で既存認証または本人確認が完了していることを前提に id_token(A) を発行してください。
• 受信側は署名、iss、aud、exp などを必ず検証してください。

リクエストパラメータ

PKaaS へ遷移する際は、以下のパラメータを HTML form 等により POST で送信してください。id_token(A) のパラメータ名は id_token とします。

レスポンスパラメータ

PKaaS は、認証結果を含む HTML form を返し、ブラウザ上で auto-submit することで、src で指定された戻り先へ POST で返却します。

返却される主な値は以下の通りです。

セキュリティ要件

リダイレクト版では、callback パスで通常の CSRF 保護をそのまま適用できない場合があるため、state による相関確認を必須とします。

state は以下の条件を満たすよう実装してください。

• 暗号学的に安全な乱数生成器を用いて生成すること
• 推測困難な値とすること
• 十分な長さを持たせること
• 認証要求ごとに新規発行すること
• IdP 側で短寿命 cookie 等に保持すること
• callback 受信時に保持値と完全一致することを確認すること
• 照合後は破棄すること

また、IdP 側では返却された id_token(B) について、少なくとも以下を検証してください。

• id_token の署名
• iss
• aud
• exp
• nonce

callback URL には、認証レスポンス専用のパスを使用してください。

src には、利用申請時に登録した利用ドメイン配下の HTTPS URL を指定してください。

PKaaS は、id_token(A) の iss に紐づく登録済み利用ドメインと src の host を照合し、登録済み利用ドメイン配下ではない URL が指定された場合はエラーとしてください。ここでの照合は、iss の文字列からドメインを推測するのではなく、PKaaS 側の登録情報に基づいて行います。

関連エンドポイントは HTTPS で提供してください。

登録時・認証時の扱い

FIDO 登録時は、IdP 側で既存認証または本人確認が完了していることを前提とします。

FIDO 登録時、FIDO 認証時のいずれでも state を付与し、返却時に照合してください。

state の照合に成功した場合のみ、id_token の検証および後続処理へ進んでください。

導入手順

1. 利用申請を行う
2. Client ID、利用ドメインを登録する
3. IdP 側で state の生成・保持・照合を実装する
4. IdP 側で id_token(A) の発行と id_token(B) の検証を実装する
5. PKaaS との疎通確認を行う