verifierとchallenge

PKCEはRFC 7636で定義されます。Clientは十分にランダムなcode_verifierを作り、SHA-256で変換したcode_challengeだけをAuthorization Requestへ送ります。

const verifier = randomBase64Url(48)
const challenge = base64url(await sha256(verifier))

callback後のToken Requestで元のverifierを送ります。

POST /api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=...&
client_id=...&
redirect_uri=http%3A%2F%2F127.0.0.1%3A4200%2Fcallback&
code_verifier=...

Public ClientはClient Secretを送信しません。Browser bundleへ埋めた文字列は誰でも取得できるため、secretとして機能しないからです。

stateとの違い

両方ともランダム値ですが、守る関係が違います。

mechanism	結び付けるもの	主な検証場所
`state`	Authorization responseとBrowser transaction	Client callback
PKCE	Authorization Codeと開始したClient instance	AS Token endpoint

どちらか一方で代用しません。盗まれたCodeの交換をASが防ぐのはPKCE、攻撃者が作ったresponseをClientが受け入れないようにするのはstateです。

Better AuthのToken call path

Token endpointはformをparseし、Client認証方式を特定してからgrant handlerへ進みます。Authorization Code Grantでは次を検証します。

Codeが存在し期限内か
Client IDがCodeの発行先か
Redirect URIが認可時と完全一致するか
PKCE verifierから得たchallengeが保存値と一致するか
Codeが未消費か

条件が揃った後でAccess Tokenを発行し、Codeを再利用不能にします。発行と消費を別々の無関係な処理にするとraceで二重交換が起きるため、adapterとtransactionの境界が重要です。

Token Responseをparseする

成功responseの最小形は次です。

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "notes:read"
}

ClientはHTTP statusだけでなく、OAuth error bodyも読みます。200以外でerrorがある場合、error_descriptionと合わせて扱います。ただしTokenやverifierをerror logへ含めません。

negative test

RFC 7636 Section 4.6は、verifierから計算した値とchallengeが一致しない場合にinvalid_grantを返すよう定めています。しかしBetter Auth 1.7.1のtoken.tsはこの分岐でUNAUTHORIZEDとinvalid_requestを投げ、ラボのE2Eでも401 invalid_requestを観測します。これは仕様とProvider実装の差分として適合性表へ残し、Client側で別の値へ読み替えません。

negative testでは正しいCodeに対してverifierを変え、現在のProvider挙動を固定します。Better Auth 1.7.1はCode recordを先に取得・削除してからPKCEを照合するため、不一致になったCodeへ正しいverifierを送り直してもinvalid_grantです。verifierの試行を一回に閉じる点は強いものの、Clientは入力訂正では回復できず、Authorization Requestからやり直す必要があります。

同じCodeを成功後にもう一度送るtestも必須です。二回目が成功するなら、PKCEが正しくてもAuthorization Codeのone-time invariantが壊れています。

次章では、得たOpaque Access TokenをResource APIへ送り、ASへのintrospectionで検証します。