なぜ最初から一つのアプリにしないのか

OAuth endpoint、画面、Resource APIを一つのprocessへ入れると、通信自体は簡単になります。しかしCookieがどこへ送られ、どのprocessがTokenを検証したかが見えにくくなります。本書では責務ごとにpackageを分けます。

examples/better-auth-oauth-provider/
├── apps/
│   ├── auth-server/   # Better Auth + Hono + React UI
│   ├── client-app/    # React Public Client
│   ├── resource-api/  # Hono Protected Resource
│   └── bff-app/       # Part 5: Next.js + Hono
├── packages/protocol/ # PKCE、transaction、検証helper
├── tools/device-cli/
├── tools/indexer/
└── docker/postgres/

PostgreSQLだけをDockerで動かし、Node/Viteのprocessはhostで起動します。network問題とアプリのdebugを分けやすくし、Cloudflareへ移す前の実装をNode 22互換のWeb API中心に保つためです。

3 databaseに分ける理由

一つのPostgreSQL container内に、roleとdatabaseを3組作ります。

oauth_auth: user、session、client、consent、code、token、JWKS
oauth_notes: ノート本文
oauth_bff: BFF sessionと暗号化Token Set

ASがノートtableを直接読める権限や、RSがRefresh Tokenを読める権限を持たない構成です。同じcontainerを使うのは開発上の簡便さであり、DB ownershipまで共有する理由にはしません。

秘密値を生成する

最初に次を実行します。

cd examples/better-auth-oauth-provider
pnpm install
pnpm run setup

pnpm run setupは.local/.envをmode 0600で新規作成し、既存fileがあれば終了します。値は標準出力へ出しません。pnpm setupと書くとpnpm本体の別commandが実行されるため、runを省略しないでください。

生成対象にはDB password、BETTER_AUTH_SECRET、BFF用暗号鍵、seed user passwordが含まれます。.local/はrepositoryの.gitignoreへ登録されています。

migrationは生成物としてcommitする

Better Authのtableを手で推測しません。pinした1.7.1 CLIでschemaを生成します。

pnpm --filter @oauth-lab/auth-server db:auth-schema
pnpm db:generate
pnpm run db:migrate
pnpm run seed

db:auth-schemaはProviderとDevice Authorization pluginを読み込み、Drizzle schemaを生成します。oauth_clientだけでなく、oauth_resource、client-resource link、authorization code、access/refresh token、consent、client assertion、device codeまで含まれます。

seedはSQLを直書きせず、Better Authのserver-only admin APIで固定Clientを作ります。Client Secretは作成responseで一度だけ取得し、.local/clients.jsonへmode 0600で保存します。このfileもGitへ入れません。

ローカルRedirect URIの注意

Better Auth 1.7.1はHTTP loopback redirectをlocalhost、127.0.0.1、[::1]の完全なhost表記に限定します。またHTTP loopbackはapplication_type: nativeの登録だけで許可されます。

したがってラボのReact ClientとBFFは、ローカルtransport用登録ではnative metadataを使います。これはBFFをinstalled appとして設計したという意味ではありません。Part 6のHTTPS登録ではBFFをwebへ戻します。開発上の例外とproduction metadataを混ぜないため、この差分をseed codeの隣にコメントで残します。

起動後に見るもの

pnpm run lab:dev

起動時にmigrationとseedを再実行できるようにしてあります。seedは名前で既存Clientを探し、secretが.local/clients.jsonに残っている限り作り直しません。

最初の観測対象はdiscovery documentです。

curl http://localhost:4100/.well-known/oauth-authorization-server/api/auth

ここにはAuthorization、Token、JWKS、introspection、revocation、UserInfo、end-session、Device Authorization endpointが並びます。さらにS256、authorization_response_iss_parameter_supported、DPoP algorithm、Client認証方式も確認できます。

次章では、このmetadataを生成するProvider設定をソースまで追います。