使い方 — DPoP nonce フロー
DPoP とは何か、nonce とは何か
DPoP（"Demonstrating Proof of Possession", RFC 9449）は、アクセストークンをクライアントが保持する鍵に紐づける仕組みです。クライアントは API 呼び出しのたびに、その鍵で署名した新しい JWT を DPoP: ヘッダで提示し、「私はこのトークンを発行されたクライアントと同一です」と証明します。漏洩した DPoP-bound トークンは、鍵を持たない攻撃者にとって無価値です。
nonce は RFC 9449 §8 / §9 の任意の補強策です。サーバが nonce を要求する場合、クライアントはサーバから受け取った値を後続の proof に含めます。サーバが新しい値を渡すまでは、受理された nonce を再利用できます。したがって nonce はリクエストごとに新しくなる値ではなく、それだけで proof の再利用を検出するものでもありません。再利用の検出には proof の一意な jti とサーバ側の追跡を使い、nonce はサーバのチャレンジ前に作られた proof を使いにくくします。
このページで触れる仕様
- RFC 9449 — DPoP, §8（OP が供給する nonce）, §9（リソースサーバが供給する nonce）
- FAPI 2.0 Security Profile — nonce 許容
- FAPI 2.0 Message Signing — Message Signing 文書。本ライブラリは DPoP 有効時に nonce source の制約を追加
用語の補足
- DPoP proof — クライアントがリクエスト毎に署名する小さな JWT。「アクセストークンがバインドされた秘密鍵を、いまも自分が保持している」ことを示します。基本は 送信者制約 を参照。
- 事前計算 proof 攻撃 — クライアントの端末を一時的に侵害した攻撃者が、有効な proof をまとめて持ち出して後から再利用するシナリオです。主な再利用対策はサーバ側の
jtiチェックで、nonce を必須にするとサーバが受理値を供給する前に作られた proof も拒否できます。
短くまとめると、nonce フローは次の 2 種の攻撃を遮ります:
- 事前計算 proof — nonce が必須の場合、サーバが受理値を供給する前に作った proof は、その値を取得するまで受理されません。受理済み proof の再利用は
jtiの追跡で扱います。 - stage-and-fire — 古い nonce に対して作った proof は、OP がその値の受理をやめると失敗します。
フロー
use_dpop_nonce を通常のエラーとして扱うクライアントは再試行を繰り返しますが、ヘッダを読むクライアントは次の 1 回で成功します。OP は、受理された nonce がないリクエストや、受理対象から外れた nonce を含むリクエストにチャレンジを返します。クライアントが返された値で再試行したあとは、OP が新しい値を渡すまでその nonce を再利用できます。成功応答に DPoP-Nonce ヘッダを付ける必要はありません。
nonce と jti は役割が異なります。jti は proof の一意な識別子で、本ライブラリの consumed-JTI ストアは同じ proof の再利用を拒否します。設定した nonce source は proof にサーバが受理する値を追加し、現行値と直前の値をローテーションできます。
実装
ライブラリは in-memory 参考実装を同梱しています。シングルプロセス用、HA セーフではありませんが、開発と小規模 deploy には十分:
import "github.com/libraz/go-oidc-provider/op"
src, err := op.NewInMemoryDPoPNonceSource(ctx, 5*time.Minute)
if err != nil { /* ... */ }
op.New(
/* 必須オプション */
op.WithFeature(feature.DPoP),
op.WithDPoPNonceSource(src),
)ローテーション間隔（上の 5*time.Minute）は「現行」nonce が切り替わる頻度です。OP は現行値と直前の値の両方を受理するので、ローテーション境界でリクエストが競合してもハード失敗にはなりません。
複数インスタンス構成
プロセスローカルな nonce ソースはレプリカを跨げません — インスタンス B はインスタンス A が出した nonce を知りません。本番 HA 構成では、独自 DPoPNonceSource の裏に共有ストア（Redis）を置きます。Redis nonce ソースをライブラリに同梱しないのは意図的です。オプション群（TTL、ローテーション周期、ローテーション境界の取りこぼし許容度）が運用ごとに異なりすぎるためです。
OP が nonce を要求するエンドポイント
| Endpoint | nonce 必須？ | 設定箇所 |
|---|---|---|
/token | DPoP proof が提示され、DPoPNonceSource を設定している場合に必須 | op.WithDPoPNonceSource |
/userinfo | DPoP proof が提示され、DPoPNonceSource を設定している場合に必須 | 同上 |
/par | DPoP proof が提示され、DPoPNonceSource を設定している場合に必須 | 同上 |
/device_authorization | DPoP proof が提示され、DPoPNonceSource を設定している場合に必須 | 同上 |
/bc-authorize（CIBA） | DPoP proof が提示され、DPoPNonceSource を設定している場合に必須 | 同上 |
/par と /token は同じ nonce チャレンジと検証を行うので、PAR（プッシュ型認可リクエスト）を使う SPA も /token と同じ nonce リトライループを /par 呼び出しで回すことになります。
DPoP ヘッダが提示された場合、表中のすべての endpoint はその値を 1 つだけ受け付けます。複数値は、先頭が空で後続に有効な proof がある場合も含め、不正として拒否されます。OP が後続の値だけを選んだり、黙って proof なしの経路として扱ったりすることはありません。
本ライブラリでは、FAPI 2.0 Message Signing プロファイルは DPoP が有効な場合に nonce source を必須とし、profile.FAPI2Baseline では任意のままです。現行の FAPI 2.0 Security Profile は nonce の利用を認めており、ここでのプロファイル別の必須化は本ライブラリの制約です。
動作確認
# nonce なしの最初の呼び出し
curl -i -X POST -H "DPoP: <nonce なしの proof>" \
-d 'grant_type=authorization_code&code=...' \
http://localhost:8080/oidc/token | head -20
# HTTP/1.1 400 Bad Request
# DPoP-Nonce: <fresh-nonce>
# {"error":"use_dpop_nonce", ...}DPoP-Nonce の値を次の proof の nonce claim に入れて再試行します。
続きはこちら
- 送信者制約 — DPoP がそもそも何のためにあるか。
- FAPI 2.0 Baseline — DPoP nonce source を任意のままにする本ライブラリのプロファイル。