Nuxt OIDC 身份驗證

歡迎使用 Nuxt OIDC 身份驗證，這是一個 Nuxt 模組，專注於為 Nuxt 提供基於原生 OIDC (OpenID Connect) 的身份驗證，並為 SSR 應用程式提供高度的客製化和安全性。除了令牌驗證（用於 JWT 互動的知名且經過測試的 jose 函式庫）之外，此模組不使用任何 unjs 生態系統之外的外部依賴項。此模組的會話實作基於 nuxt-auth-utils。

• Nuxt OIDC 身份驗證
  • 功能
    • 近期重大變更
    • 安全性資訊
  • 安裝
    • 將 nuxt-oidc-auth 依賴項新增至您的專案
    • 設定密鑰
  • 身份驗證提供者預設值
    • 提供者特定配置
    • Auth0
    • AWS Cognito
    • Entra ID/Microsoft
    • GitHub
    • Keycloak
    • Zitadel
  • Vue 可組合函式
    • loggedIn => 布林值
    • loginprovider?: ProviderKeys | 'dev', params?: Record<string, string> => Promise
    • user => 物件
    • currentProvider => 字串
    • fetch => void
    • refresh => void
    • logoutprovider: 字串 => Promise
    • 使用者物件
  • 伺服器工具
    • 中介軟體
    • 會話過期和重新整理
    • OIDC 事件處理程式
    • 在伺服器端程式碼中使用會話
    • 掛鉤
      • 範例
  • 組態參考
    • oidc
      • providers
      • session
      • middleware
  • 開發模式
    • 啟用
    • 令牌產生
  • 貢獻
  • ⚠️ 免責聲明

功能

🔒  安全且密封的 Cookie 會話
📝  符合一般規範的 OpenID Connect 提供者，具有完全可設定的 OIDC 流程 (state, nonce, PKCE, 令牌請求, ...)
⚙️  熱門 OIDC 提供者 的預設值
🗂️  透過自動註冊路由 (/auth/<provider>/login、/auth/<provider>/logout、/auth/<provider>/callback) 支援多個提供者
👤  useOidcAuth 可組合函式，用於取得使用者資訊、登入和登出、重新擷取目前會話和觸發令牌重新整理
💾  由 unstorage 提供支援的加密伺服器端重新整理/存取令牌儲存
📤  可選的全域中介軟體，具有自動重新導向到預設提供者或自訂登入頁面（請參閱 Playground）
🔑  可選的令牌驗證
🕙  可選的會話過期檢查，基於令牌過期時間
↩️  令牌過期時可選的自動會話續約

如果您正在尋找一個支援由您的 Nuxt 伺服器提供的本機身份驗證（及更多）的模組，請查看 sidebase 的 nuxt-auth 模組（由 authjs 和 NextAuth 提供支援）➡️ nuxt-auth

近期重大變更

⚠️ 自 0.16.0 起，來自提供者的 userInfo 端點的資料會寫入使用者物件的 userInfo，而不是 providerInfo。請據此調整您的 nuxt.config.ts 和 .env/環境檔案和組態。如果您正在使用來自 useOidcAuth 可組合函式的使用者物件，請將對 providerInfo 的存取變更為 userInfo。

安全性資訊

此模組僅在機密用戶端情境中實作 Authorization Code Flow 和可選的 Hybrid Flow，如 OpenID Connect 規格 中所述。我們未來將不支援 Implicit Flow，因為它不應再使用，且實際上已被 Authorization Code Flow 取代。我們也不會支援 Client Credential Flow，因為它不屬於 OIDC，而是 OAuth2 的一部分，並且正確地稱為 Client Credentials Grant。它基本上只是交換憑證以取得令牌，不是用於使用者身份驗證，並且可以使用簡單的 fetch 請求輕鬆實作。

此模組僅在啟用 SSR（伺服器端渲染）的情況下運作，因為它使用伺服器 API 路由。您無法將此模組與 nuxt generate 一起使用。

安裝

將 nuxt-oidc-auth 依賴項新增至您的專案

使用 nuxi

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

或手動

pnpm add -D nuxt-oidc-auth

將 nuxt-oidc-auth 新增至 nuxt.config.ts 的 modules 區段

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

設定密鑰

Nuxt OIDC 身份驗證使用三個不同的密鑰來加密使用者會話、個別的身份驗證會話和持久的伺服器端令牌儲存。您可以使用環境變數或在 .env 檔案中設定它們。如果未設定所有密鑰，則會自動產生，但應在生產環境中手動設定。這對於會話儲存尤其重要，因為如果密鑰變更，例如在伺服器重新啟動後，將無法再存取它。

如果您需要參考如何產生隨機密鑰或金鑰，我們建立了一個範例作為起點：密鑰產生範例

• NUXT_OIDC_TOKEN_KEY（隨機金鑰）：這需要是 base64 中的隨機加密 AES 金鑰。用於加密伺服器端令牌儲存。您可以使用 await subtle.exportKey('raw', await subtle.generateKey({ name: 'AES-GCM', length: 256, }, true, ['encrypt', 'decrypt'])) 在 JS 中產生金鑰。您只需在之後將其編碼為 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 身份驗證包含以下提供者的預設值，並經過測試的預設值

• Auth0
• AWS Cognito
• Entra ID/Microsoft
• GitHub
• Keycloak
• Zitadel
• 一般 OIDC

提供者特定配置

某些提供者具有特定的其他欄位，可用於擴充授權、登出或令牌請求。這些欄位可透過提供者組態中的 additionalAuthParameters、additionalLogoutParameters 或 additionalTokenParameters 取得。

⚠️ 僅當 clientId 或可選的 audience 欄位是 access_tokens (如果存在則為 id_token) 授權對象的一部分時，才會驗證令牌。即使設定了 validateAccessToken 或 validateIdToken，如果授權對象不符，則不應且不會驗證令牌。某些提供者（例如 Entra 或 Zitadel）不提供或僅在某些情況下提供可剖析的 JWT 存取令牌。這些驗證將會失敗，即使設定了授權對象，也應該停用。

redirectUri 屬性始終為必要項目，且應始終指向特定提供者的回呼 URI。對於 Auth0，它應該看起來像這樣 https://YOURDOMAIN/auth/auth0/callback。Playground 的 nuxt.config.ts 具有多個提供者的範例。

如果您的提供者沒有預設值，您可以使用組態中的 oidc 提供者金鑰新增一般 OpenID Connect 提供者。請記住設定必要的欄位，並預期您的提供者的行為會與 OAuth 和 OIDC 規格中定義的略有不同。為了安全起見，您應避免將用戶端密碼直接寫入 nuxt.config.ts 檔案。您可以使用環境變數將設定注入到執行階段組態中。請查看 playground 資料夾中的 .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 中的其他參數

根據應用程式的 [憑證] 索引標籤設定，針對 [用戶端密碼 (Post)]，將 authenticationScheme 設定為 body，針對 [用戶端密碼 (基本)] 設定為 header，針對 [無] 設定為 ''

AWS Cognito

提供者支援

✅  PKCE
✅  Nonce
✅  State
❌  存取令牌驗證
❌  ID 令牌驗證

AWS Cognito 並未正確實作 OAuth 2 標準，且未提供用於受眾的 aud 欄位。因此，無法驗證存取或 ID 權杖。

說明

對於 AWS Cognito，您必須至少提供 baseUrl、clientId、clientSecret 和 logoutRedirectUri 屬性。baseUrl 用於動態建立 authorizationUrl、tokenUrl、logoutUrl 和 userInfoUrl。唯一支援的 OAuth 授權類型為授權碼授權。最終的網址看起來應該像這樣：https://cognito-idp.eu-north-1.amazonaws.com/eu-north-1_SOMEID/.well-known/openid-configuration。如果您的 redirectUri 未在「允許的回呼 URL」下正確註冊，或 logoutRedirectUri 未在「允許的登出 URL」下正確註冊，您也會遇到錯誤。如果您需要其他 scopes，請在您的 Nuxt 設定的 scope 屬性中指定它們，例如 scope: ['openid', 'email', 'profile'],。

Entra ID/Microsoft

提供者支援

✅  PKCE
✅  Nonce
✅  State
⚠️  存取權杖驗證（支援，但已停用，因為僅適用於自訂受眾權杖）
✅  ID 權杖驗證

說明

要用於 additionalAuthParameters、additionalTokenParameters 或 additionalLogoutParameters 中的其他參數

如果您想要驗證來自 Microsoft Entra ID（先前為 Azure AD）的存取權杖，您需要確保 scope 中包含您自己的 API。您必須先註冊一個 API，並將一些 scopes 公開給您想要請求的應用程式註冊。如果您的 scope 中只有 GraphAPI 條目，例如 openid、mail 等 GraphAPI 特定條目，則傳回的存取權杖無法也應該無法驗證。如果 scope 設定正確，您可以將 validateAccessToken 選項設為 true。

如果您使用此模組搭配 Entra External ID (先前為 Entra ID for Customers)，請確保您已將 audience 設定欄位設定為您的應用程式 ID，否則將無法取得有效的 OpenID Connect well-known 設定，從而無法驗證 JWT 權杖。

GitHub

提供者支援

❌  PKCE
❌  Nonce
✅  State
❌  存取令牌驗證
❌  ID 令牌驗證

說明

GitHub 並非嚴格意義上的 OIDC 提供者，但可以用作 OIDC 提供者。請確保停用驗證，並將 skipAccessTokenParsing 選項保持為 true。

請嘗試使用GitHub 應用程式，而不是舊版的 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 和程式碼驗證方案。對於 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 可組合函式

Nuxt OIDC Auth 會自動新增一些 API 路由，以與目前的使用者會話互動，並新增 useOidcAuth composable，其提供以下 refs 和方法，以從您的 Vue 元件存取會話

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

loggedIn => (布林值)

指示使用者目前是否已登入。

範例用法

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 => (物件)

目前的使用者物件。

currentProvider => (字串)

目前登入的提供者名稱。

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，您必須手動將登入頁面新增至您的 Nuxt 應用程式的 /auth/login 下。您可以使用來自 useOidcAuth composable 的 login 方法，將使用者重新導向至各自的提供者登入頁面。將 customLoginPage 設定為 true 也會停用 /auth/logout 路由。您必須手動將登出頁面新增至您的 Nuxt 應用程式的 /auth/logout 下，並使用來自 useOidcAuth composable 的 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) 來手動重新整理會話。

會話過期和重新整理完全在伺服器端處理，使用者會話中公開的屬性會自動更新。理論上，您可以註冊一個 hook 來覆寫會話欄位，例如 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
})

請小心不要從處理常式程式碼中公開任何敏感資訊。

掛鉤

以下 hook 可用於擴充 OIDC 模組的預設行為

• fetch (當使用者會期被擷取時呼叫)
• clear (在使用者會期被清除之前呼叫)
• refresh (在使用者會期被重新整理之前呼叫)

⚠️ 如果您修改了會期，請記得同時更新重新整理的鉤子 (refresh hook)，否則宣告 (claims) 和其他欄位將會被清除。

範例

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 -> 在您的 nuxt.config.ts 的 oidc 部分中，將 enabled 設定為 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

⚠️ 免責聲明

此模組仍在開發中，歡迎提供意見和貢獻！使用風險自負。