このBookで作るもの

OAuthを学び始めると、最初に「Googleでログイン」のボタンへ目が向きがちです。しかしOAuthが解決する中心課題は、認証そのものではありません。あるClientに、Resource Ownerの権限の一部を、期限と用途を限定して委譲することです。

このBookではCloud Notesという小さなサービスを段階的に組み立てます。登場するプロセスは次の4つです。

Better Auth OAuth Providerを載せたAuthorization Server
Client Secretを持たないReactのPublic Client
ノートを保持するHono Resource API
後半で追加するNext.js + HonoのBFF

最初はnotes:readだけを委譲し、必要になった時点でnotes:writeへ権限を広げます。その後、長期利用のRefresh Token、機械間処理のClient Credentials、キーボードを持たない端末のDevice Authorizationを追加します。OIDCはOAuthの説明へ混ぜず、Part 4でidentity layerとして重ねます。

仕様・実装・観測を分ける

本書では、根拠を次の4層に分けます。

公開済みRFCやOpenID Connect仕様が要求すること
draft-ietf-oauth-v2-1-15が提案していること
Better Auth 1.7.1が実装していること
このラボでHTTP・DB・ブラウザから観測できたこと

OAuth 2.1は、本書執筆時点ではRFCではありません。そのため「OAuth 2.1だから必須」と断定せず、公開済みのSecurity Best Current PracticeであるRFC 9700と、OAuth 2.1 draftの位置づけを分けます。

Better Authについても同様です。Providerの便利なAPIをOAuth仕様そのものとして扱いません。対象バージョンはbetter-authと@better-auth/oauth-providerの1.7.1に固定し、ソースはtagだけでなくcommitとSHA-256をupstream-sources.jsonへ記録します。

毎章で使う読み方

主要な処理は、同じ5段階で読みます。

HTTP: BrowserやClientは何を送受信するか
call path: HonoからBetter Authのどのendpointへ入るか
invariant: 一度だけ使える、完全一致する、といった不変条件は何か
DB: その条件をどのrecordが支えるか
failure: 条件を壊すと、どのOAuth errorになるか

成功例だけを見ると、stateもPKCEも飾りに見えます。古いcode、間違ったredirect_uri、使い回したRefresh Tokenを実際に拒否させることで、各値の所有者と役割が見えるようになります。

最初に守る安全境界

Public ClientのTokenはReactのstate、つまりメモリだけに置きます。localStorage、URL、console、画面のpre要素へTokenの生値は出しません。Inspectorが表示するのは種類、長さ、先頭8文字、SHA-256 fingerprintだけです。

認可transactionはsessionStorageに置きますが、保存するのはtransaction ID、state、PKCE verifier、OIDC利用時のnonce、issuer、redirect URI、開始時刻だけです。callbackで読み出した直後に削除します。

Bookのコードは学習用でも、秘密値の扱いを簡略化しません。理解のために危険な実装を正解例として残すと、その断片だけが別の製品へコピーされるからです。

到達点

最後には、次の問いへ自分の言葉で答えられる状態を目指します。

Authorization CodeはなぜTokenそのものではないのか
stateとPKCEは、それぞれ何を結び付けるのか
Opaque TokenとJWTを誰が検証するのか
OAuth Access TokenとOIDC ID Tokenをなぜ交換できないのか
BrowserにTokenを置くPublic Clientと、BFFのどちらを選ぶべきか
Better Authの設定、endpoint、DB recordが仕様上のどの責務を担当するのか

次章では、コードを書く前に4つのroleと3種類のcredentialを配置します。