Nuxt OIDC 身份验证

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

• Nuxt OIDC 身份验证
  • 功能
    • 最近重大更改
    • 安全信息
  • 安装
    • 将 nuxt-oidc-auth 依赖项添加到您的项目中
    • 设置密钥
  • 身份验证提供程序预设
    • 特定于提供程序的配置
    • Auth0
    • AWS Cognito
    • Entra ID/Microsoft
    • GitHub
    • Keycloak
    • Zitadel
  • Vue 可组合函数
    • 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
  • 开发模式
    • 启用
    • 令牌生成
  • 贡献
  • ⚠️ 免责声明

功能

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

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

最近重大更改

⚠️ 从 0.16.0 开始，提供程序 userInfo 端点的数据写入用户对象上的 userInfo 而不是 providerInfo。请相应地调整您的 nuxt.config.ts 和 .env/环境文件以及配置。如果您正在使用 useOidcAuth 可组合函数中的用户对象，请将对 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 密钥。用于加密服务器端令牌存储。您可以在 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

✨就是这样！您现在可以向您的 Nuxt 应用程序添加使用预定义提供程序或自定义 OIDC 提供程序的身份验证✨

身份验证提供程序预设

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
❌  随机数
✅  状态
✅  访问令牌验证
❌  ID 令牌验证

说明

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

根据应用程序“凭据”选项卡的设置，对于“客户端密钥（发布）”，将 authenticationScheme 设置为 body，对于“客户端密钥（基本）”，将设置为 header，对于“无”，将设置为 ''

AWS Cognito

提供程序支持

✅  PKCE
✅  随机数
✅  状态
❌  访问令牌验证
❌  ID 令牌验证

AWS Congito 未正确实现 OAuth 2 标准，未为受众提供 aud 字段。因此，无法验证访问或 id 令牌。

说明

对于 AWS Cognito，您必须至少提供 baseUrl、clientId、clientSecret 和 logoutRedirectUri 属性。baseUrl 用于动态创建 authorizationUrl、tokenUrl、logoutUrl 和 userInfoUrl。唯一支持的 OAuth 授权类型是 授权码授权。最终 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
✅  随机数
✅  状态
⚠️  访问令牌验证（受支持，但已禁用，因为仅适用于自定义受众令牌）
✅  ID 令牌验证

说明

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

如果您想验证来自 Microsoft Entra ID（以前称为 Azure AD）的访问令牌，则需要确保范围包含您自己的 API。您必须首先注册一个 API 并向您的应用注册公开您想要请求的一些范围。如果您的范围内只有像 openid、mail 这样的 GraphAPI 条目或 GraphAPI 特定的条目，则返回的访问令牌不能也不应该被验证。如果范围设置正确，则可以将 validateAccessToken 选项设置为 true。

如果您将此模块与 Entra 外部 ID（以前称为适用于客户的 Entra ID）一起使用，请确保已将 audience 配置字段设置为您的应用程序 ID，否则将无法获得有效的 OpenID Connect 已知配置，从而无法验证 JWT 令牌。

GitHub

提供程序支持

❌ PKCE
❌  随机数
✅  状态
❌  访问令牌验证
❌  ID 令牌验证

说明

GitHub 不是严格的 OIDC 提供商，但可以用作 OIDC 提供商。确保验证已禁用，并且您将 skipAccessTokenParsing 选项保留为 true。

尝试使用 GitHub 应用程序，而不是旧版 OAuth 应用程序。它们没有提供相同的安全级别，没有细粒度的权限，不提供刷新令牌，并且未经测试。

确保在您的 OAuth 应用程序设置中将回调 URL 设置为 <your-domain>/auth/github。

Keycloak

提供程序支持

✅  PKCE
✅  随机数
❌ 状态
✅  访问令牌验证
❌  ID 令牌验证

说明

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

有关这些参数的更多信息，请查看 KeyCloak 文档。

对于 Keycloak，您必须至少提供 baseUrl、clientId 和 clientSecret 属性。 baseUrl 用于动态创建 authorizationUrl、tokenUrl、logoutUrl 和 userInfoUrl。请在 baseUrl 中包含您要使用的 realm（例如 https://<keycloak-url>/realms/<realm>）。如果您不想使用 key cloak 的注销重定向功能，请将 logoutUrl 设置为 undefined 或 ''。还要记住启用 客户端身份验证才能获取客户端密钥。

Zitadel

提供程序支持

✅  PKCE
✅  随机数
❌ 状态
✅  访问令牌验证
❌  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 可组合函数

Nuxt OIDC Auth 自动添加一些 API 路由以与当前用户会话进行交互，并添加 useOidcAuth 组合，该组合提供以下 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() => (空)

获取/更新当前用户会话。

refresh() => (空)

针对所使用的提供商刷新当前用户会话以获取新的访问令牌。仅当当前提供商发出刷新令牌（由 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 组合中的 login 方法将用户重定向到相应的提供商登录页面。将 customLoginPage 设置为 true 还会禁用 /auth/logout 路由。您必须手动将注销页面添加到您的 Nuxt 应用程序中，位于 /auth/logout 下，并使用 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（在刷新用户会话之前调用）

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

示例

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（发出时间）：当前日期时间，
• 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

⚠️ 免责声明

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