コンテンツにスキップ

⚛️ 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 に置く値の暗号化
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 のエンドポイントと公開鍵の URL は、/.well-known/openid-configuration から取ります (discovery)。

lib/google.ts

import * as client from "openid-client";
// Google の OP の設定と、このアプリの client_id・client_secret
export 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`;

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);
}

Google の画面でのことなので、コードはありません。Google が redirect_uri に認可コードと state を付けて、利用者を戻します。

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 の 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 —

この例に、実際のアプリでは次のものを足します。どれも 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/ にあります。