⚛️ Next.js での OIDC (BFF) の実装例
OAuth の資料 の OIDC のシーケンス (1〜5) を、Next.js (App Router) の Route Handler 2 つで書いた例です。Next.js のサーバーが機密クライアント (BFF) になり、トークンはブラウザに渡しません。
流れがつかめるよう、エラーの扱い・IdP を増やす仕組み・セキュリティの細かい確認は省いています。このアプリで実際に気をつけていることは identity の README にあります。
使うライブラリ:
- openid-client: OP との通信 (認可リクエストの URL・トークンの交換・ID トークンの検証)
- iron-session: Cookie に置く値の暗号化
🗺️ シーケンス図
Section titled “🗺️ シーケンス図”sequenceDiagram
actor User as 🥸 エンドユーザー
participant Start as 🖥️ /oauth/google
participant Callback as 🖥️ /oauth/google/callback
participant Google as 🛡️ Google (OP)
rect rgb(150, 150, 150)
Note over User,Start: 1. フロー開始
User->>Start: GET /oauth/google
Start->>Start: 🎲 state・🧷 nonce・🧩 code_verifier を作り、<br/>暗号化した Cookie に覚える
Start-->>User: 302 Google の認可エンドポイント<br/>(state・nonce・code_challenge 付き)
end
rect rgb(150, 150, 150)
Note over User,Google: 2. 🎫 認可コード取得
User->>Google: ログイン・同意
Google-->>User: 302 /oauth/google/callback?code=🎫&state=🎲
end
rect rgb(150, 100, 100)
Note over User,Google: 3. 🔑 トークン取得
User->>Callback: GET /oauth/google/callback?code=🎫&state=🎲
Callback->>Callback: 🎲 state が Cookie の値と同じか確かめる
Callback->>Google: 🎫 認可コード・🧩 code_verifier・client_secret を送る
Google-->>Callback: 🔑 アクセストークン・🆔 ID トークン
end
rect rgb(100, 120, 150)
Note over Callback,Google: 4. 🆔 ID トークンの検証
Callback->>Google: 🔐 公開鍵 (JWKS) を取る
Callback->>Callback: 署名・iss・aud・exp・🧷 nonce を確かめる
end
rect rgb(150, 150, 150)
Note over User,Callback: 5. ✅ ログイン
Callback->>Callback: iss と sub で利用者を探し (初めてなら登録)、<br/>ログイン前の Cookie を消してセッションを作る
Callback-->>User: 302 ログインした後の画面<br/>Set-Cookie: 🍪 セッション
end
上の 1〜5 は、下のコードのコメントの番号と対応しています。openid-client が受け持つのは、3 と 4 の大部分です。
OP の設定
Section titled “OP の設定”OP のエンドポイントと公開鍵の URL は、/.well-known/openid-configuration から取ります (discovery)。
lib/google.ts
import * as client from "openid-client";
// Google の OP の設定と、このアプリの client_id・client_secretexport async function google(): Promise<client.Configuration> { const config = await client.discovery( new URL("https://accounts.google.com"), process.env.GOOGLE_CLIENT_ID!, process.env.GOOGLE_CLIENT_SECRET!, ); // 4. ID トークンの署名を、公開鍵 (jwks_uri) で確かめるようにする client.enableNonRepudiationChecks(config); return config;}
// 認可コードを受け取るコールバックの URL。Google の OAuth クライアントの「承認済みのリダイレクト URI」に登録するexport const redirectUri = `${process.env.APP_URL}/oauth/google/callback`;1. フロー開始
Section titled “1. フロー開始”app/oauth/google/route.ts
import { sealData } from "iron-session";import { cookies } from "next/headers";import { NextResponse } from "next/server";import * as client from "openid-client";import { google, redirectUri } from "@/lib/google";
const password = process.env.SESSION_SECRET!;
export async function GET() { // 1. 🎲 state・🧷 nonce・🧩 code_verifier を作る (ログインを始めるたびに作り直す) const state = client.randomState(); const nonce = client.randomNonce(); const codeVerifier = client.randomPKCECodeVerifier();
// コールバックで確かめるまで、暗号化した Cookie に覚えておく (10 分) (await cookies()).set( "login", await sealData({ state, nonce, codeVerifier }, { password, ttl: 600 }), // Google から戻ってきたときにも送られるよう、SameSite は Lax にする { httpOnly: true, secure: true, sameSite: "lax", path: "/", maxAge: 600 }, );
// 認可エンドポイントへ送る。code_challenge は code_verifier の SHA-256 const url = client.buildAuthorizationUrl(await google(), { redirect_uri: redirectUri, scope: "openid email profile", state, nonce, code_challenge: await client.calculatePKCECodeChallenge(codeVerifier), code_challenge_method: "S256", }); return NextResponse.redirect(url);}2. 🎫 認可コード取得
Section titled “2. 🎫 認可コード取得”Google の画面でのことなので、コードはありません。Google が redirect_uri に認可コードと state を付けて、利用者を戻します。
3〜5. コールバック
Section titled “3〜5. コールバック”app/oauth/google/callback/route.ts
import { sealData, unsealData } from "iron-session";import { cookies } from "next/headers";import { type NextRequest, NextResponse } from "next/server";import * as client from "openid-client";import { google, redirectUri } from "@/lib/google";import { findOrCreateUser } from "@/lib/users";
const password = process.env.SESSION_SECRET!;
export async function GET(request: NextRequest) { const cookieStore = await cookies(); // 1. で覚えた値 (Cookie が無い・改ざんされているときは、ログインし直してもらう) const login = await unsealData<{ state: string; nonce: string; codeVerifier: string; }>(cookieStore.get("login")?.value ?? "", { password });
// 3. 🎲 state を確かめ、🎫 認可コードと 🧩 code_verifier を送って、トークンに交換する。 // 4. ID トークンの署名・iss・aud・exp・🧷 nonce も、openid-client がここで確かめる const tokens = await client.authorizationCodeGrant( await google(), new URL(`${redirectUri}${request.nextUrl.search}`), { expectedState: login.state, expectedNonce: login.nonce, pkceCodeVerifier: login.codeVerifier, idTokenExpected: true, }, ); const claims = tokens.claims()!;
// 5. iss と sub の組で利用者を探す (初めてなら登録する)。 // メールアドレスで既存の利用者と紐付けるなら、email_verified が true のときだけにする const user = await findOrCreateUser({ iss: claims.iss, sub: claims.sub, email: claims.email, emailVerified: claims.email_verified === true, });
// ログイン前の Cookie を消し、新しい Cookie でセッションを作る (セッション固定攻撃の対策)。 // トークンはブラウザに渡さない (API を呼ぶなら、サーバー側のセッションストアに置く) cookieStore.delete("login"); cookieStore.set( "session", await sealData({ userId: user.id }, { password, ttl: 14 * 24 * 60 * 60 }), { httpOnly: true, secure: true, sameSite: "lax", path: "/" }, ); return NextResponse.redirect(new URL("/", process.env.APP_URL));}🔍 README の手順との対応
Section titled “🔍 README の手順との対応”| README の OIDC | コード | 誰が確かめるか |
|---|---|---|
| 1. 🎲 state・🧩 code_verifier・🧷 nonce を作って覚える | route.ts の randomState・randomPKCECodeVerifier・randomNonce と Cookie |
— |
1. 認可リクエスト (response_type=code・scope=openid ...) |
route.ts の buildAuthorizationUrl |
— |
| 3. 🎲 state が覚えた値と同じか | callback/route.ts の expectedState |
クライアント (openid-client) |
| 3. 🎫 認可コードを 🔑・🆔 に交換する | callback/route.ts の authorizationCodeGrant |
— |
| 3. 🧩 code_verifier のハッシュが code_challenge と同じか | pkceCodeVerifier を送る |
OP (Google) |
| 4. 🔐 署名を公開鍵で確かめる | google.ts の enableNonRepudiationChecks |
クライアント (openid-client) |
| 4. iss・aud・exp・🧷 nonce を確かめる | callback/route.ts の expectedNonce |
クライアント (openid-client) |
| 5. iss と sub で利用者を探す・セッションを作り直す | callback/route.ts の findOrCreateUser と Cookie |
— |
➕ 実際のアプリで足すもの
Section titled “➕ 実際のアプリで足すもの”この例に、実際のアプリでは次のものを足します。どれも identity の README の「実装で気をつけること」に理由があります。
- ログインした後の戻り先 (
?returnTo=) と、それが自サイトのパスかの確認 (オープンリダイレクトの対策) - ログインを始める URL を、別のサイトから開かせない (
Sec-Fetch-Site) - IdP ごとにコールバックの URL を分け、ログインを始めた IdP と同じかを確かめる (mix-up 攻撃の対策)
- 失敗したとき (同意画面での拒否・state の不一致・認可コードの使い回し) に、ログイン画面に理由を出す
- 302 の応答をキャッシュさせない (
Cache-Control: no-store)、本番の Cookie の名前に__Host-を付ける
このアプリの以前の実装 (この例を、上のものまで含めて書いたもの) は、コミット 1b44fc7 の lib/oauth/ と app/(identity)/oauth/ にあります。