Nuxt OIDC Auth

Nuxt OIDC Authへようこそ。これは、Nuxt向けにネイティブOIDC（OpenID Connect）ベースの認証に焦点を当てたNuxtモジュールであり、SSRアプリケーションの高いカスタマイズ性とセキュリティを実現します。このモジュールは、トークン検証を除いて（広く知られ、テスト済みのJWT操作用joseライブラリ）、unjsエコシステム以外の外部依存関係を使用しません。このモジュールのセッション実装はnuxt-auth-utilsに基づいています。

• Nuxt OIDC Auth
  • 機能
    • 最近の破壊的変更
    • セキュリティ情報
  • インストール
    • プロジェクトにnuxt-oidc-auth依存関係を追加
    • シークレットの設定
  • 認証プロバイダープリセット
    • プロバイダー固有の設定
    • Auth0
    • AWS Cognito
    • Entra ID/Microsoft
    • GitHub
    • Keycloak
    • Zitadel
  • Vue Composable
    • loggedIn => boolean
    • loginprovider?: ProviderKeys | 'dev', params?: Record<string, string> => Promise
    • user => object
    • currentProvider => string
    • fetch => void
    • refresh => void
    • logoutprovider: string => Promise
    • ユーザーオブジェクト
  • サーバーユーティリティ
    • ミドルウェア
    • セッションの期限切れと更新
    • OIDCイベントハンドラー
    • サーバーサイドコードでのセッションの使用
    • フック
      • 例
  • 設定リファレンス
    • oidc
      • providers
      • session
      • middleware
  • 開発モード
    • 有効化
    • トークン生成
  • コントリビュート
  • ⚠️ 免責事項

機能

🔒  セキュアでシールドされたクッキーセッション
📝  完全な構成可能なOIDCフロー（状態、nonce、PKCE、トークンリクエストなど）を備えた、ジェネリックな仕様に準拠したOpenID Connectプロバイダー
⚙️  一般的なOIDCプロバイダーのプリセット
🗂️  自動登録されたルート（/auth/<provider>/login、/auth/<provider>/logout、/auth/<provider>/callback）によるマルチプロバイダーサポート
👤  ユーザー情報の取得、ログインとログアウト、現在のセッションの再取得、トークンの更新トリガーを行うuseOidcAuthコンポーザブル
💾  unstorageによって実現される暗号化されたサーバーサイド更新/アクセストークンストレージ
📤  デフォルトプロバイダーまたはカスタムログインページへの自動リダイレクトを備えたオプションのグローバルミドルウェア（プレイグラウンドを参照）
🔑  オプションのトークン検証
🕙  トークンの有効期限に基づくオプションのセッション有効期限チェック
↩️  トークンの有効期限切れ時のオプションの自動セッション更新

Nuxtサーバーによって提供されるローカル認証（およびその他）をサポートするモジュールをお探しの場合は、sidebaseのnuxt-authモジュール（authjsとNextAuthによって実現）をご覧ください➡️ nuxt-auth

最近の破壊的変更

⚠️ 0.16.0以降、プロバイダーのuserInfoエンドポイントからのデータは、providerInfoではなく、ユーザーオブジェクトのuserInfoに書き込まれます。nuxt.config.tsと.env/環境ファイル、および設定をそれに合わせて調整してください。useOidcAuthコンポーザブルからユーザーオブジェクトを使用している場合は、providerInfoへのアクセスをuserInfoに変更してください。

セキュリティ情報

このモジュールは、OpenID Connect仕様で詳述されているように、機密クライアントシナリオでAuthorization Code FlowとオプションでHybrid Flowのみを実装しています。Implicit Flowは今後サポートしません。これはもう使用すべきではなく、実際にはAuthorization Code Flowに取って代わられています。Client Credential Flowもサポートしません。これはOIDCの一部ではなく、OAuth2の一部であり、正しくはClient Credentials Grantと呼ばれます。これは基本的に資格情報のトークンへの単純な交換であり、ユーザー認証を目的としたものではなく、単純なfetchリクエストを使用して簡単に実装できます。

このモジュールは、サーバーAPIルートを使用するため、SSR（サーバーサイドレンダリング）が有効になっている場合のみ機能します。nuxt generateではこのモジュールを使用できません。

インストール

プロジェクトにnuxt-oidc-auth依存関係を追加

nuxiを使用する場合

pnpm dlx nuxi@latest module add nuxt-oidc-auth

手動で行う場合

pnpm add -D nuxt-oidc-auth

nuxt.config.tsのmodulesセクションにnuxt-oidc-authを追加

export default defineNuxtConfig({
  modules: [
    'nuxt-oidc-auth'
  ]
})

シークレットの設定

Nuxt OIDC Authは、ユーザーセッション、個々の認証セッション、永続的なサーバーサイドトークンストアを暗号化するために、3つの異なるシークレットを使用します。環境変数または.envファイルを使用して設定できます。すべてのシークレットは設定されていない場合に自動生成されますが、本番環境では手動で設定する必要があります。これは特にセッションストレージにとって重要です。たとえば、サーバーの再起動後にシークレットが変更されると、アクセスできなくなります。

ランダムなシークレットまたはキーの生成方法の参照が必要な場合は、出発点として例を作成しました。シークレット生成の例

• NUXT_OIDC_TOKEN_KEY（ランダムキー）：これはbase64でエンコードされたランダムな暗号化AESキーである必要があります。サーバーサイドトークンストアの暗号化に使用されます。JSでawait subtle.exportKey('raw', await subtle.generateKey({ name: 'AES-GCM', length: 256, }, true, ['encrypt', 'decrypt']))を使用してキーを生成できます。その後、base64にエンコードするだけです。
• NUXT_OIDC_SESSION_SECRET（ランダム文字列）：これは少なくとも48文字のランダム文字列である必要があります。ユーザーセッションの暗号化に使用されます。
• NUXT_OIDC_AUTH_SESSION_SECRET（ランダム文字列）：これは少なくとも48文字のランダム文字列である必要があります。OAuthフロー中の個々のセッションの暗号化に使用されます。

.envファイルに少なくとも48文字のNUXT_OIDC_SESSION_SECRET環境変数を追加します。

# .env
NUXT_OIDC_TOKEN_KEY=base64_encoded_key
NUXT_OIDC_SESSION_SECRET=48_characters_random_string
NUXT_OIDC_AUTH_SESSION_SECRET=48_characters_random_string

✨ これだけです！これで、事前定義されたプロバイダーまたはカスタムOIDCプロバイダーを使用して、Nuxtアプリに認証を追加できます✨

認証プロバイダープリセット

Nuxt OIDC Authには、テスト済みのデフォルト値を持つ次のプロバイダーのプリセットが含まれています。

• Auth0
• AWS Cognito
• Entra ID/Microsoft
• GitHub
• Keycloak
• Zitadel
• ジェネリックOIDC

プロバイダー固有の設定

一部のプロバイダーには、承認、ログアウト、またはトークンリクエストを拡張するために使用できる特定の追加フィールドがあります。これらのフィールドは、プロバイダー設定のadditionalAuthParameters、additionalLogoutParameters、またはadditionalTokenParametersを介して使用できます。

⚠️ トークンは、clientIdまたはオプションのaudienceフィールドがアクセストークン（または存在する場合のid_token）のオーディエンスの一部である場合にのみ検証されます。validateAccessTokenまたはvalidateIdTokenが設定されていても、オーディエンスが一致しない場合、トークンは検証されません。EntraやZitadelなどの一部のプロバイダーは、解析可能なJWTアクセストークンをまったく提供しないか、特定の場合にのみ提供します。これらのプロバイダーでは検証に失敗するため、オーディエンスが設定されている場合でも、検証を無効にする必要があります。

redirectUriプロパティは常に必須であり、常に特定のプロバイダーのコールバックURIを指す必要があります。Auth0の場合、https://YOURDOMAIN/auth/auth0/callbackのようになります。プレイグラウンドのnuxt.config.tsには、複数のプロバイダーの例があります。

プロバイダーにプリセットがない場合は、設定でoidcプロバイダーキーを使用して、ジェネリックOpenID Connectプロバイダーを追加できます。必要なフィールドを設定し、プロバイダーがOAuthおよびOIDC仕様で定義されているものとはわずかに異なる動作をすることを想定してください。セキュリティ上の理由から、nuxt.config.tsファイルにクライアントシークレットを直接記述することは避ける必要があります。環境変数を使用して、ランタイム設定に設定を挿入できます。参照としてプレイグラウンドフォルダの.env.exampleファイルを確認してください。

追加のプロバイダーの追加を要求する問題を作成することも検討してください。

# OIDC MODULE CONFIG
NUXT_OIDC_TOKEN_KEY=
NUXT_OIDC_SESSION_SECRET=
NUXT_OIDC_AUTH_SESSION_SECRET=
# AUTH0 PROVIDER CONFIG
NUXT_OIDC_PROVIDERS_AUTH0_CLIENT_SECRET=
NUXT_OIDC_PROVIDERS_AUTH0_CLIENT_ID=
NUXT_OIDC_PROVIDERS_AUTH0_BASE_URL=
# KEYCLOAK PROVIDER CONFIG
NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_SECRET=
NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_ID=
NUXT_OIDC_PROVIDERS_KEYCLOAK_BASE_URL=
...

Auth0

プロバイダーサポート

✅  PKCE
❌  Nonce
✅  State
✅  アクセストークン検証
❌  IDトークン検証

手順

additionalAuthParameters、additionalTokenParameters、またはadditionalLogoutParametersで使用される追加パラメーター

アプリのCredentialsタブの設定に応じて、authenticationSchemeを次のように設定します。'Client Secret (Post)'の場合はbody、'Client Secret (Basic)'の場合はheader、'None'の場合は''。

AWS Cognito

プロバイダーサポート

✅  PKCE
✅ Nonce
✅  State
❌ アクセストークンの検証
❌  IDトークン検証

AWS CognitoはOAuth 2標準を正しく実装しておらず、対象者を示すaudフィールドを提供しません。そのため、アクセストークンまたはIDトークンの検証はできません。

手順

AWS Cognitoを使用するには、少なくともbaseUrl、clientId、clientSecret、logoutRedirectUriのプロパティを指定する必要があります。baseUrlは、authorizationUrl、tokenUrl、logoutUrl、userInfoUrlを動的に作成するために使用されます。サポートされているOAuthグラントタイプはAuthorization code grantのみです。最終的なURLは、https://cognito-idp.eu-north-1.amazonaws.com/eu-north-1_SOMEID/.well-known/openid-configurationのようになります。"許可されたコールバックURL"にredirectUri、"許可されたサインアウトURL"にlogoutRedirectUriを正しく登録していない場合もエラーが発生します。追加のスコープが必要な場合は、Nuxtの設定でscopeプロパティに指定します（例：scope: ['openid', 'email', 'profile'],）。

Entra ID/Microsoft

プロバイダーサポート

✅  PKCE
✅ Nonce
✅  State
⚠️ アクセストークンの検証（サポートされていますが、カスタムオーディエンストークンでのみ可能なため無効になっています）
✅ IDトークンの検証

手順

additionalAuthParameters、additionalTokenParameters、またはadditionalLogoutParametersで使用される追加パラメーター

Microsoft Entra ID（旧Azure AD）からのアクセストークンを検証する場合は、スコープに独自のAPIが含まれていることを確認する必要があります。最初にAPIを登録し、要求するスコープをアプリ登録に公開する必要があります。openid、mailなどのGraphAPI固有のエントリのみがスコープに含まれている場合、返されたアクセストークンは検証できませんし、検証すべきではありません。スコープが正しく設定されている場合は、validateAccessTokenオプションをtrueに設定できます。

Entra External ID（旧Entra ID for Customers）でこのモジュールを使用する場合は、audience設定フィールドをアプリケーションIDに設定してください。設定しないと、有効なOpenID Connect既知の設定を取得できず、JWTトークンを検証できなくなります。

GitHub

プロバイダーサポート

❌ PKCE
❌  Nonce
✅  State
❌ アクセストークンの検証
❌  IDトークン検証

手順

GitHubは厳密にはOIDCプロバイダーではありませんが、OIDCプロバイダーとして使用できます。検証が無効になっていること、およびskipAccessTokenParsingオプションがtrueのままになっていることを確認してください。

レガシーなOAuthアプリではなく、GitHub Appの使用を試してください。レガシーなOAuthアプリは同じレベルのセキュリティを提供せず、きめ細かい権限がなく、更新トークンを提供せず、テストもされていません。

OAuthアプリの設定でコールバックURLを<your-domain>/auth/githubとして設定してください。

Keycloak

プロバイダーサポート

✅  PKCE
✅ Nonce
❌ State
✅  アクセストークン検証
❌  IDトークン検証

手順

additionalAuthParameters、additionalTokenParameters、またはadditionalLogoutParametersで使用される追加パラメーター

これらのパラメータの詳細については、KeyCloakのドキュメントを参照してください。

Keycloakを使用するには、少なくともbaseUrl、clientId、clientSecretのプロパティを指定する必要があります。baseUrlは、authorizationUrl、tokenUrl、logoutUrl、userInfoUrlを動的に作成するために使用されます。baseUrlには使用するrealmを含めてください（例：https://<keycloak-url>/realms/<realm>）。Keycloakのポストログアウトリダイレクト機能を使用しない場合は、logoutUrlをundefinedまたは''に設定します。また、クライアントシークレットを取得できるようにClient authenticationを有効にすることも忘れないでください。

Zitadel

プロバイダーサポート

✅  PKCE
✅ Nonce
❌ State
✅  アクセストークン検証
❌  IDトークン検証

手順

Zitadelを使用するには、少なくともbaseUrl、clientId、clientSecretのプロパティを指定する必要があります。baseUrlは、authorizationUrl、tokenUrl、logoutUrl、userInfoUrlを動的に作成するために使用されます。このプロバイダーはPKCEとCode認証スキームをサポートしています。PKCEを使用する場合は、clientSecretを空文字列（''）のままにします。

設定例

zitadel: {
  clientId: '',
  clientSecret: '', // Works with PKCE and Code flow, just leave empty for PKCE
  redirectUri: 'https://127.0.0.1:3000/auth/zitadel/callback', // Replace with your domain
  baseUrl: '', // For example https://PROJECT.REGION.zitadel.cloud
  audience: '', // Specify for id token validation, normally same as clientId
  logoutRedirectUri: 'https://google.com', // Needs to be registered in Zitadel portal
  authenticationScheme: 'none', // Set this to 'header' if Code is used instead of PKCE
},

Vue Composable

Nuxt OIDC Authは、現在のユーザーセッションとやり取りするためのいくつかのAPIルートを自動的に追加し、useOidcAuthコンポーザブルを追加します。これにより、Vueコンポーネントからセッションにアクセスするための次のrefとメソッドが提供されます。

• loggedIn
• user
• currentProvider
• fetch
• refresh
• login
• logout

loggedIn => (boolean)

ユーザーが現在ログインしているかどうかを示します。

使用例

const { loggedIn } = useOidcAuth()

if (loggedIn.value) {
  console.log('User is logged in')
}
else {
  console.log('User is not logged in')
}

login(provider?: ProviderKeys | 'dev', params?: Record<string, string>) => (Promise)

ログインプロセスを開始します。

パラメータ

使用例

<script setup>
const { loggedIn, user, login, logout } = useOidcAuth()
</script>

<template>
  <div v-if="loggedIn">
    <h1>Welcome {{ user.userName }}!</h1>
    <p>Logged in since {{ user.loggedInAt }}</p>
    <button @click="logout()">
      Logout
    </button>
  </div>
  <div v-else>
    <h1>Not logged in</h1>
    <a href="/auth/github/login">Login with GitHub</a>
    <button @click="login()">
      Login with default provider
    </button>
  </div>
</template>

user => (object)

現在のユーザーオブジェクト。

currentProvider => (string)

現在ログインしているプロバイダーの名前。

fetch() => (void)

現在のユーザーセッションを取得/更新します。

refresh() => (void)

新しいアクセストークンを取得するために、使用されているプロバイダーに対して現在のユーザーセッションを更新します。userオブジェクトのcanRefreshプロパティで示されているように、現在のプロバイダーが更新トークンを発行した場合にのみ使用できます。

logout(provider: string) => (Promise)

ログアウトプロセスを処理します。デフォルトのプロバイダーを設定していない場合は、常にオプションのproviderパラメータを指定してください。currentProviderプロパティから現在のプロバイダーを取得できます。

使用例

<script setup>
const { logout } = useOidcAuth()
</script>

<template>
  <button @click="logout()">
    Logout
  </button>
</template>

デフォルトのプロバイダーが設定されていない場合、またはミドルウェアcustomLoginPageがtrueに設定されている場合の使用例

<script setup>
const { logout, currentProvider } = useOidcAuth()
</script>

<template>
  <button @click="logout(currentProvider)">
    Logout
  </button>
</template>

ユーザーオブジェクト

useOidcAuthによって提供されるuserオブジェクトには、次のプロパティが含まれています。

プロジェクトに型宣言ファイル（例：auth.d.ts）を作成することで、プロバイダー情報の型を拡張できます。

declare module '#oidc-auth' {
  interface UserInfo {
    // define the type here e.g.,
    providerName: string
  }
}

サーバーユーティリティ

次のヘルパーは、server/ディレクトリに自動的にインポートされます。

ミドルウェア

このモジュールは、Nuxtサーバーにグローバルミドルウェアを自動的に追加できます。設定のmiddlewareセクションの下にあるglobalMiddlewareEnabledを設定することで有効にできます。ミドルウェアは、ユーザーがログインしていない場合、すべてのリクエストを/auth/loginに自動的にリダイレクトします。middleware設定でredirectをfalseに設定することで、この動作を無効にできます。/auth/loginルートは、デフォルトのプロバイダーを定義した場合にのみ設定されます。カスタムログインページを使用し、デフォルトのプロバイダーを維持するか、デフォルトのプロバイダーをまったく設定しない場合は、middleware設定でcustomLoginPageをtrueに設定できます。

customLoginPageをtrueに設定した場合、/auth/loginの下にNuxtアプリにログインページを手動で追加する必要があります。useOidcAuthコンポーザブルのloginメソッドを使用して、ユーザーをそれぞれのプロバイダーのログインページにリダイレクトできます。customLoginPageをtrueに設定すると、/auth/logoutルートも無効になります。/auth/logoutの下にNuxtアプリにログアウトページを手動で追加し、useOidcAuthコンポーザブルのlogoutメソッドを使用してユーザーをログアウトするか、logoutメソッドに常にオプションのproviderパラメータを指定してください。

<script setup>
const { logout, currentProvider } = useOidcAuth()
</script>

<template>
  <button @click="logout(currentProvider)">
    Logout
  </button>
</template>

⚠️ /authパス以下のものは、グローバルミドルウェアによって保護されていません。認証以外の目的でこのパスを使用しないでください。

セッションの期限切れと更新

Nuxt OIDC Authは、セッションの有効期限切れをチェックし、必要に応じて自動的に更新します。 session設定でexpirationCheckとautomaticRefreshをfalseに設定することで、この動作を無効にできます。 sessionオブジェクトにアクセスすると、セッションは自動的に更新されます。クライアント側ではuseOidcAuthのrefreshを使用して、サーバー側ではrefreshUserSession(event)を呼び出すことで、セッションを手動で更新することもできます。

セッションの有効期限切れと更新は完全にサーバー側で処理され、ユーザーセッションの公開プロパティは自動的に更新されます。loggedInAtなどのセッションフィールドを上書きするフックを理論的には登録できますが、これは推奨されず、各更新で上書きされます。

OIDCイベントハンドラー

構成されたすべてのプロバイダーは、次のサーバールートを自動的に登録します。

• /auth/<provider>/callback
• /auth/<provider>/login
• /auth/<provider>/logout

さらに、defaultProviderが設定されている場合、次のルートルールはデフォルトのプロバイダーへの転送として登録されます。

• /auth/login
• /auth/logout

サーバーサイドコードでのセッションの使用

@nuxtjs/oidc-authモジュールのgetUserSession関数を使用して、サーバー側のコードでユーザーセッションにアクセスできます。

import { getUserSession } from "nuxt-oidc-auth/runtime/server/utils/session.mjs"

export default eventHandler(async (event) => {
  const session = await getUserSession(event)
  return session.userName
})

ハンドラーコードから機密情報を公開しないように注意してください。

フック

OIDCモジュールのデフォルトの動作を拡張するために、次のフックを使用できます。

• fetch（ユーザーセッションがフェッチされたときに呼び出されます）
• clear（ユーザーセッションがクリアされる前に呼び出されます）
• refresh（ユーザーセッションが更新される前に呼び出されます）

⚠️ セッションを変更した場合は、refreshフックも更新してください。 そうしないと、クレームやその他のフィールドが消去されます。

例

export default defineNitroPlugin(() => {
  sessionHooks.hook('fetch', async (session) => {
    // Extend User Session
    // Or throw createError({ ... }) if session is invalid
    // session.extended = {
    //   fromHooks: true
    // }
    console.log('Injecting "status" claim as test')
    if (!(Object.keys(session).length === 0)) {
      const claimToAdd = { status: 'Fetch' }
      session.claims = { ...session.claims, ...claimToAdd }
    }
  })

  sessionHooks.hook('refresh', async (session) => {
    console.log('Injecting "status" claim as test on refresh')
    if (!(Object.keys(session).length === 0)) {
      const claimToAdd = { status: 'Refresh' }
      session.claims = { ...session.claims, ...claimToAdd }
    }
  })

  sessionHooks.hook('clear', async (session) => {
    // Log that user logged out
    console.log('User logged out')
  })
})

理論上は、loggedInAtのような内部セッションフィールドを上書きするフックを登録できますが、これはセッションのloggedIn状態に影響を与えるため、推奨されません。サーバー側の更新と期限切れロジックには影響しませんが、更新ごとに上書きされます。

設定リファレンス

このモジュールの設定は、nuxt.config.tsファイルで定義できます。

export default defineNuxtConfig({
  oidc: {
    defaultProvider: '<provider>',
    providers: {
      <provider>: {
        clientId: '...',
        clientSecret: '...'
      }
    },
    middleware: {
      globalMiddlewareEnabled: true,
      customLoginPage: false
    }
  }
})

oidc

providers

<provider>

session

グローバルセッション設定には、次のオプションがあります。

グローバルセッション設定のオーバーライドとして、各プロバイダーで次のオプションを使用できます。

middleware

開発モード

0.10.0以降、ローカル開発モードが利用可能です。NODE_ENV環境変数がprod/productionに設定されておらず、設定で開発モードが明示的に有効になっている場合にのみ有効にできます。開発モードは**ローカル**および**オフライン**開発用であり、設定または.envの変数で設定できる静的なユーザーオブジェクトを返します。返されるユーザーオブジェクトの次のフィールドを設定できます。

• claims: devMode.claims 設定
• provider: devMode.provider 設定
• userName: devMode.userName 設定
• userInfo: devMode.userInfo 設定
• idToken: devMode.idToken 設定
• accessToken: devMode.accessToken 設定

必要なタイプについては、ユーザーオブジェクトを参照してください。

有効化

開発モードを有効にするには、少なくとも次の設定が設定されていることを確認する必要があります。

• session -> expirationCheckをオフにする必要があります（false）
• devMode -> enabledをnuxt.config.tsのoidc部分でtrueに設定します。

トークン生成

必要に応じて、開発モードはdevMode -> generateAccessToken設定がtrueに設定されている場合、有効な署名付きアクセストークンを生成できます。このトークンはuser.accessTokenプロパティに公開されます。生成されたトークンのプロパティは次のとおりです。

• iat（発行日時）：現在のDateTime
• iss（発行者）：devMode.issuer設定、デフォルトnuxt:oidc:auth:issuer
• aud：devMode.audience設定、デフォルトnuxt:oidc:auth:audience
• sub：devMode.subject設定、デフォルトnuxt:oidc:auth:subject
• exp：現在のDateTime + 24時間

⚠️ アクセストークンは固定されたローカルシークレットを使用して生成され、安全とは決して言えません。開発モードはローカル開発でのみ有効にでき、テスト目的でのみ使用してください。本番システムに開発モードにする可能性のある環境変数を設定しないでください。

コントリビュート

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

⚠️ 免責事項

このモジュールはまだ開発中です。フィードバックと貢献は大歓迎です！自己責任でご使用ください。