最初は読めないTokenを使う

Part 2ではOpaque Access Tokenから始めます。ClientにもRSにも、文字列をdecodeしてclaimを読む方法はありません。値を見ただけで権限を判断できないことが利点です。検証authorityをASへ集中できます。

Clientは次のrequestを送ります。

GET /notes HTTP/1.1
Host: 127.0.0.3:4300
Authorization: Bearer <access-token>

RSはverifyAccessTokenRequestへrequest method、URL、Authorization header、DPoP headerを渡します。生Tokenだけを検証するhelperではなくrequest単位のAPIを使うのは、後でsender-constrained DPoPも同じ境界で扱うためです。

introspectionのClient認証

Opaque TokenはASのintrospection endpointへ問い合わせます。RFC 7662のresponseにはactive、scope、client、subject、期限、audienceなどが含まれます。

remoteVerify: {
  introspectUrl: `${AUTH_ISSUER}/oauth2/introspect`,
  clientId: resourceApiClientId,
  clientSecret: resourceApiClientSecret,
  allowMissingAudience: true
}

ここで使うcredentialはPublic Clientのものではありません。RS自身をASへ認証するconfidential clientです。Better Auth 1.7.1のremote verifierはform bodyでcredentialを送るため、このClientをclient_secret_postとして登録します。登録方式と実際の送信方式を一致させます。

scopeをrouteごとに要求する

app.get('/notes', async (c) => {
  const claims = await verifyRequest(c.req.raw, ['notes:read'])
  return c.json(await findNotes(claims.sub))
})

app.post('/notes', async (c) => {
  const claims = await verifyRequest(c.req.raw, ['notes:write'])
  // ...
})

UIでbuttonを隠すだけでは不十分です。GETとPOSTがそれぞれ必要scopeを宣言し、検証済みsubをowner keyに使います。Request bodyのuserIdを信用しません。

RFC 9728 metadataとchallenge

RSはprotected resource metadataを公開します。

{
  "resource": "http://127.0.0.3:4300",
  "authorization_servers": ["http://localhost:4100/api/auth"],
  "scopes_supported": ["notes:read", "notes:write", "notes:index"]
}

Tokenがなければ次のようなchallengeを返します。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="...", scope="notes:read"

Tokenは有効でもscope不足なら403 insufficient_scopeです。認証できない状態と、認証済みだが許可されない状態を分けます。

audienceを段階導入する

最初のOpaque TokenではResource Indicatorを要求していないため、introspection responseにaudienceがない場合をlocal lab限定で許します。ただしintrospection Client自体はNotes Resourceへlink済みです。

Part 3でresource=http://127.0.0.3:4300を認可requestへ追加したら、JWTのaudを必須にし、allowMissingAudienceを外します。この移行点を残すことで、audience checkが最初から魔法のように存在していたと誤解しません。

次章では正常系を離れ、境界を一つずつ壊します。