Nuxt OIDC 身份验证

欢迎来到 Nuxt OIDC 身份验证，这是一个 Nuxt 模块，专注于基于原生 OIDC（OpenID Connect）的 Nuxt 身份验证，为 SSR 应用程序提供高度的自定义性和安全性。除了令牌验证（用于 JWT 交互的著名且经过测试的 jose 库）之外，此模块不使用 unjs 生态系统之外的任何外部依赖项。此模块的会话实现基于 nuxt-auth-utils。

• Nuxt OIDC 身份验证
  • 特性
    • 最近的重大更改
    • 安全信息
  • 安装
    • 将 nuxt-oidc-auth 依赖项添加到您的项目
    • 设置密钥
  • 身份验证提供程序预设
    • 特定于提供程序的配置
    • Auth0
    • AWS Cognito
    • Entra ID/Microsoft
    • GitHub
    • Keycloak
    • Zitadel
  • Vue Composable
    • loggedIn => 布尔值
    • loginprovider?: ProviderKeys | 'dev', params?: Record<string, string> => Promise
    • user => 对象
    • currentProvider => 字符串
    • fetch => void
    • refresh => void
    • logoutprovider: string => Promise
    • 用户对象
  • 服务器实用程序
    • 中间件
    • 会话过期和刷新
    • OIDC 事件处理程序
    • 在服务器端代码中使用会话
    • 钩子
      • 示例
  • 配置参考
    • oidc
      • 提供程序
      • 会话
      • 中间件
  • 开发模式
    • 启用
    • 令牌生成
  • 贡献
  • ⚠️ 免责声明

特性

🔒  安全且密封的 Cookie 会话
📝  符合通用规范的 OpenID Connect 提供程序，具有完全可配置的 OIDC 流程（状态、随机数、PKCE、令牌请求等）
⚙️  流行的 OIDC 提供程序的预设
🗂️  支持多提供程序，自动注册路由 ( /auth/<provider>/login, /auth/<provider>/logout, /auth/<provider>/callback)
👤  useOidcAuth composable，用于获取用户信息、登录和注销、重新获取当前会话和触发令牌刷新
💾  由 unstorage 提供支持的加密服务器端刷新/访问令牌存储
📤  可选的全局中间件，自动重定向到默认提供程序或自定义登录页面（请参阅 playground）
🔑  可选的令牌验证
🕙  基于令牌过期的可选会话过期检查
↩️  令牌过期时可选的自动会话续订

如果您正在寻找由 Nuxt 服务器提供的支持本地身份验证（以及更多功能）的模块，请查看 sidebase 的 nuxt-auth 模块（由 authjs 和 NextAuth 提供支持）➡️ nuxt-auth

最近的重大更改

⚠️ 自 0.16.0 起，来自提供程序 userInfo 端点的数据写入用户对象上的 userInfo，而不是 providerInfo。请相应地调整您的 nuxt.config.ts 和 .env/环境变量文件和配置。如果您使用 useOidcAuth composable 中的用户对象，请将对 providerInfo 的访问更改为 userInfo。

安全信息

此模块仅在机密客户端场景中实现 授权码流程 和可选的 混合流程，如 OpenID Connect 规范中所详述。我们将来不会支持 隐式流程，因为它不应再使用，并且实际上已被 授权码流程 取代。我们也不会支持 客户端凭据流程，因为它不是 OIDC 的一部分，而是 OAuth2 的一部分，并且正确命名为 客户端凭据授权。它基本上只是凭据换取令牌，不用于用户身份验证，并且可以使用简单的 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 Auth 使用三个不同的密钥来加密用户会话、各个身份验证会话和持久的服务器端令牌存储。您可以使用环境变量或在 .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 Auth 包含以下提供程序的预设，并经过测试的默认值

• 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 属性始终是必需的，并且应始终指向特定提供程序的 callback 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
❌  随机数
✅  状态
✅  访问令牌验证
❌  ID 令牌验证

说明

要在 additionalAuthParameters、additionalTokenParameters 或 additionalLogoutParameters 中使用的其他参数

根据您的应用Credentials标签页中的设置，对于“客户端密钥（Post）”，将authenticationScheme设置为body；对于“客户端密钥（Basic）”，设置为header；对于“无”，设置为''。

AWS Cognito

提供程序支持

✅  PKCE
✅  Nonce
✅  状态
❌  访问令牌验证
❌  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。如果您没有在“Allowed callback URLs”下正确注册 redirectUri 或在“Allowed sign-out URLs”下正确注册 logoutRedirectUri，也会遇到错误。如果您需要额外的作用域，请在您的 nuxt 配置中的 scope 属性中指定它们，例如 scope: ['openid', 'email', 'profile'],。

Entra ID/Microsoft

提供程序支持

✅  PKCE
✅  Nonce
✅  状态
⚠️  访问令牌验证（支持，但已禁用，因为仅适用于自定义受众令牌）
✅  ID 令牌验证

说明

要在 additionalAuthParameters、additionalTokenParameters 或 additionalLogoutParameters 中使用的其他参数

如果要验证来自 Microsoft Entra ID（以前称为 Azure AD）的访问令牌，您需要确保作用域包含您自己的 API。您必须首先注册一个 API，并将一些作用域暴露给您要请求的应用注册。如果您的作用域中只有 GraphAPI 条目，如 openid、mail 等 GraphAPI 特有的条目，则返回的访问令牌无法且不应被验证。如果作用域设置正确，则可以将 validateAccessToken 选项设置为 true。

如果您将此模块与 Entra External ID（以前称为 Entra ID for Customers）一起使用，请确保已将 audience 配置字段设置为您的应用程序 ID，否则将无法获取有效的 OpenID Connect 众所周知的配置，从而无法验证 JWT 令牌。

GitHub

提供程序支持

❌  PKCE
❌  随机数
✅  状态
❌  访问令牌验证
❌  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 中包含您要使用的领域（例如，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 Composable

Nuxt OIDC Auth 会自动添加一些 API 路由以与当前用户会话交互，并添加 useOidcAuth composable，它提供以下 refs 和方法来从您的 Vue 组件访问会话

• 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，则必须手动将登录页面添加到 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) 在服务器端手动刷新会话。

会话过期和刷新完全由服务器端处理，用户会话中暴露的属性会自动更新。理论上，您可以注册一个钩子来覆盖会话字段，如 loggedInAt，但不建议这样做，因为每次刷新都会被覆盖。

OIDC 事件处理程序

所有配置的提供程序都会自动注册以下服务器路由。

• /auth/<提供程序>/callback
• /auth/<提供程序>/login
• /auth/<提供程序>/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 (在刷新用户会话之前调用)

⚠️ 请记住，如果您修改了会话，也要更新刷新钩子，否则声明和其他字段将被清除。

示例

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

提供程序

<提供程序>

会话

以下选项可用于全局会话配置。

以下选项在每个提供程序上都可用，作为全局会话配置的覆盖。

中间件

开发模式

从 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 (发布时间): 当前日期时间
• iss (颁发者): devMode.issuer 设置，默认为 nuxt:oidc:auth:issuer
• aud: devMode.audience 设置，默认为 nuxt:oidc:auth:audience
• sub: devMode.subject 设置，默认为 nuxt:oidc:auth:subject
• exp: 当前日期时间 + 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

⚠️ 免责声明

此模块仍在开发中，欢迎反馈和贡献！使用风险自负。