JavaScript 生態系における OIDC 認証ライブラリの選定と実装

JavaScript で認証システムを構築する際、OpenID Connect (OIDC) 標準をサポートするライブラリの選択はセキュリティとアーキテクチャに直結する重要な決定です。提示された 5 つのパッケージは、名前が似ていても「クライアント側かサーバー側か」「認証を行う側か提供するか」「フレームワーク依存か」という点で明確な役割分担があります。これらを混同すると、セキュリティホールや不適切なアーキテクチャにつながるため、それぞれの特性を深く理解する必要があります。

🏗️ 役割と実行環境の明確な区別

最も重要な点は、これらがどの環境で動作し、どの役割を担うかです。大きく分けて「ブラウザクライアント」、「サーバーサイドクライアント」、「認証サーバー提供者」、「フレームワークラッパー」の 4 種類に分類できます。

oidc-client-ts と oidc-client は、ブラウザ上で動作する「Public Client」向けのライブラリです。シークレットを保持できない環境のため、PKCE (Proof Key for Code Exchange) 拡張を用いた Authorization Code Flow を使用します。

// oidc-client-ts: ブラウザでの設定例
import { UserManager } from "oidc-client-ts";

const userManager = new UserManager({
  authority: "https://accounts.google.com",
  client_id: "your-client-id",
  redirect_uri: "https://yourapp.com/callback",
  response_type: "code",
  scope: "openid profile email",
  post_logout_redirect_uri: "https://yourapp.com/logout"
});

// ログイン開始
await userManager.signinRedirect();

openid-client は、Node.js 環境で動作する「Confidential Client」向けのライブラリです。サーバー側でクライアントシークレットを安全に保持できるため、より高い信頼性が求められるバックエンド連携に適しています。

// openid-client: Node.js サーバーでの設定例
import { generators, Issuer } from 'openid-client';

const issuer = await Issuer.discover('https://accounts.google.com');
const client = new issuer.Client({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret', // サーバー側で管理
  redirect_uris: ['https://yourapp.com/callback'],
  response_types: ['code']
});

const code_verifier = generators.codeVerifier();
const code_challenge = generators.codeChallenge(code_verifier);

const authUrl = client.authorizationUrl({
  scope: 'openid profile',
  code_challenge,
  code_challenge_method: 'S256'
});

oidc-provider は、これらクライアントが接続する「認証サーバー」そのものを実装するためのライブラリです。自前でユーザーデータベースを持ち、トークンを発行する立場になります。

// oidc-provider: 認証サーバーの実装例 (Koa/Express 等)
import Provider from 'oidc-provider';

const configuration = {
  clients: [
    {
      client_id: 'client-id',
      client_secret: 'client-secret',
      redirect_uris: ['https://client-app.com/callback']
    }
  ],
  scopes: ['openid', 'profile'],
  features: {
    registration: { enabled: true }
  }
};

const provider = new Provider('https://your-identity-server.com', configuration);
// provider.listen(3000); // 認証サーバーとして起動

react-oidc-context は、これらのロジックを React のコンテキスト API でラップし、コンポーネント内で useAuth() などのフックを使えるようにする橋渡し役です。

// react-oidc-context: React での利用例
import { AuthProvider, useAuth } from 'react-oidc-context';

const authConfig = {
  authority: "https://accounts.google.com",
  client_id: "your-client-id",
  redirect_uri: "https://yourapp.com/callback",
  scope: "openid profile"
};

function App() {
  return (
    <AuthProvider {...authConfig}>
      <Dashboard />
    </AuthProvider>
  );
}

function Dashboard() {
  const auth = useAuth();
  
  if (auth.isLoading) return <div>Loading...</div>;
  if (auth.error) return <div>Error: {auth.error.message}</div>;
  if (!auth.isAuthenticated) return <button onClick={auth.signinRedirect}>Login</button>;

  return <div>Hello {auth.user?.profile.name}</div>;
}

⚠️ oidc-client vs oidc-client-ts: 移行の必要性

oidc-client は長年標準として使われてきましたが、現在はメンテナンスモードに入っており、新規プロジェクトでの使用は避けるべきです。oidc-client-ts はその公式な後継であり、TypeScript で完全に書き直されています。

oidc-client (非推奨)

• JavaScript (ES5) で書かれており、型定義が外部依存でした。
• 最新のセキュリティ標準への追従が遅れるリスクがあります。

// oidc-client: 古い書き方
import { UserManager } from 'oidc-client';
const mgr = new UserManager(settings);
mgr.signinRedirect();

oidc-client-ts (推奨)

• TypeScript ネイティブであり、型安全性が保証されます。
• モダンなビルドツールとの親和性が高く、バンドルサイズも最適化されています。
• 将来的なセキュリティパッチはこちらに適用されます。

// oidc-client-ts: 現在の標準
import { UserManager } from 'oidc-client-ts';
const mgr = new UserManager(settings);
await mgr.signinRedirect();

既存の oidc-client 実装がある場合、API はほぼ互換性がありますが、型定義の扱いや一部の非同期処理の戻り値が異なるため、移行時にはテストが必須です。

🔐 セキュリティモデルとトークン管理

ライブラリ選びは、そのままトークンの保管場所とセキュリティモデルの選択になります。

ブラウザクライアント (oidc-client-ts, react-oidc-context)

• トークン保管: アクセストークンはメモリ、リフレッシュトークンは通常使用しない（またはsecure なストレージ）のが推奨です。ローカルストレージへの保存は XSS 攻撃のリスクがあるため注意が必要です。
• フロー: Implicit Flow は廃止され、Authorization Code Flow with PKCE が必須です。
• 実装: ライブラリが自動的に PKCE のコードチャレンジ生成と検証を行います。

// oidc-client-ts: PKCE は自動処理されるが、設定で明示可能
const settings = {
  // ...
  response_type: "code", // Implicit ('token') は使用しない
  // pkce_method: 'S256' // デフォルトで S256 が使用される
};

サーバーサイドクライアント (openid-client)

• トークン保管: サーバー側のセッションストアや、暗号化された Cookie に保管します。ブラウザに露出しないため、より高いセキュリティを確保できます。
• フロー: 通常の Authorization Code Flow を使用し、クライアントシークレットで認証します。
• 実装: トークンの交換（コード → トークン）をサーバー側で行うため、ネットワーク経由でトークンが漏れるリスクを減らせます。

// openid-client: サーバー側でコードをトークンに交換
const params = client.callbackParams(req);
const tokenSet = await client.callback('https://yourapp.com/callback', params, { code_verifier });
// tokenSet.access_token をサーバー側セッションで管理

認証サーバー (oidc-provider)

• 責任: トークンの署名、有効期限の管理、ユーザーの認証ロジックを自ら実装する必要があります。
• リスク: 設定ミスが直接的なセキュリティ侵害（不正トークン発行など）につながります。

// oidc-provider: 署名鍵の管理が重要
const configuration = {
  keys: [
    {
      kid: 'my-key-id',
      kty: 'RSA',
      use: 'sig',
      // 秘密鍵の管理は環境変数や HSM 経由で行うべき
      crv: 'RS256', 
      n: '...', 
      e: '...', 
      d: '...', 
    }
  ]
};

🔄 認証フローのライフサイクル管理

認証状態の維持と更新（サイレントリニュー）は、ユーザー体験に直結します。

oidc-client-ts / react-oidc-context

• サイレントリニュー: iframe を使用してバックグラウンドでトークンを更新します。最近のブラウザ規制（ITP など）により、サードパーティ Cookie がブロックされる環境では動作しない可能性があります。
• 代替案: リフレッシュトークンを使用するフロー（Refresh Token Rotation）への移行が進んでいます。

// oidc-client-ts: サイレントリニュー設定
const settings = {
  // ...
  automaticSilentRenew: true,
  // 最近では refreshToken 使用が推奨されるケースが多い
  useRefreshToken: true, 
  scope: "openid profile offline_access"
};

openid-client

• セッション管理: サーバー側でセッション期限を管理するため、ブラウザの制限を受けにくいです。
• トークン更新: サーバー側でリフレッシュトークンを使用して新しいアクセストークンを取得し、セッションを更新します。

// openid-client: リフレッシュトークンでの更新
if (tokenSet.expired() || needsRefresh(tokenSet)) {
  const newTokenSet = await client.refresh(tokenSet.refresh_token);
  // セッションストアを更新
}

📊 選定マトリクスと結論

プロジェクトの要件に応じて、以下の基準で選択を行います。

💡 最終的なアドバイス

認証はアプリケーションの心臓部です。ライブラリを選ぶ際は、単に「使えるか」だけでなく、「メンテナンスされ続けているか」「セキュリティ標準に準拠しているか」を最優先してください。

フロントエンド開発者が最も頻繁に選ぶべき組み合わせは、oidc-client-ts （またはそれをラップした react-oidc-context）です。oidc-client からの移行は避けられない流れであり、TypeScript 環境での開発体験とセキュリティの両面で優れています。

一方で、バックエンドエンジニアが API サーバーの認証を担う場合は openid-client が唯一の正解です。ブラウザとサーバーでライブラリを混在させないよう、アーキテクチャ図面上で境界を明確にすることが重要です。

もし「認証サーバー自体を作りたい」という要件であれば、oidc-provider が出番ですが、これは認証専門のエンジニアリングを要求されるため、通常は Auth0 や Cognito などのマネージドサービスの利用を先に検討すべきです。

適切なツールを適切な場所に配置することで、堅牢でメンテナンスしやすい認証システムを構築できます。