跳到内容

AuthJS 快速入门

本指南旨在介绍如何使用 AuthJS 提供商设置 @sidebase/nuxt-auth,AuthJS 提供商最适合为已建立的 OAuth 提供商或基于 magic-url 的登录方式提供即插即用的 OAuth 功能。

安装

如果要使用 AuthJS 提供商,您必须安装 next-auth。 对于除 npm 以外的所有包管理器,您必须手动安装与 nuxt-auth 并行的对等依赖项。

bash
pnpm i next-auth@4.21.1
bash
yarn add next-auth@4.21.1

警告

由于 NextAuth 中的重大更改,nuxt-auth 仅与 v4.23.0 以下版本的 NextAuth 兼容。 我们建议将版本锁定为 4.21.1。 阅读此处了解更多信息。

配置

安装 @sidebase/nuxt-authnext-auth 后,您现在可以配置 NuxtAuth 以使用 AuthJS 提供商。 在您的 nuxt.config.ts 中添加以下配置

ts
export default defineNuxtConfig({
  modules: ['@sidebase/nuxt-auth'],
  auth: {
    provider: {
      type: 'authjs',
      trustHost: false,
      defaultProvider: 'github',
      addDefaultCallbackUrl: true
    }
  }
})

除了主要的模块配置之外,您还可以在 nuxt.config.ts 中配置 AuthJS 特定的选项。

trustHost

  • 类型: boolean
  • 默认值: false

如果设置为 trueauthjs 将使用 x-forwarded-hosthost 标头,而不是 auth.baseURL。 确保可以信任在您的托管平台上读取 x-forwarded-host

警告

这是一个高级选项。 高级选项的传递方式与基本选项相同,但可能具有复杂的含义或副作用。 除非您非常熟悉使用它们,否则应尽量避免使用高级选项。

defaultProvider

  • 类型: SupportedProviders
  • 默认值: undefined

选择在调用 signIn 时使用的默认提供商。 在此处设置此项也会影响全局中间件的行为。 例如,当您将其设置为 github 且用户未获得授权时,他们将被直接转发到 Github OAuth 页面,而不是看到应用登录页面。

addDefaultCallbackUrl

  • 类型: boolean | string
  • 默认值: true

是否向登录请求添加 callbackUrl。 将其设置为字符串值将导致该值用作 callbackUrl 路径。 设置为 true 将导致选择被阻止的原始目标路径(如果可以确定)。

NuxtAuthHandler

下一步,在 ~/server/api/auth/[...].ts 下创建您的 NuxtAuthHandler。 在其中,您可以配置要使用的身份验证提供商、JWT 令牌的创建和管理方式以及会话的组成方式。 NuxtAuthHandler 将自动创建所有必需的 API 端点,以处理应用程序内部的身份验证。

NuxtAuthHandler 是对 AuthJS 内置的 NextAuthHandler 的改编。 在 NuxtAuthHandler 内部,您可以配置

  • OAuth 提供商: 用户如何登录您的应用程序?
  • 适配器: 会话如何保存? (例如 JWT 令牌、数据库等)
  • JWT 加密: JWT 令牌如何加密和读取?
  • 回调: 挂钩到身份验证生命周期钩子。

首先在 ~/server/api/auth/[...].ts 中创建一个新的服务器路由文件。 然后,您可以开始添加您的 NuxtAuthHandler。 文件名必须是 [...].ts - 这是一个所谓的“catch-all”路由,请在 Nuxt catch-all 文档中阅读更多信息。

ts
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // your authentication configuration here!
})

添加提供商

创建 NuxtAuthHandler 后,您可以开始添加提供商。 您可以在此处找到所有可用提供商的概述。 对于此示例,我们将添加 GitHub 提供商。

ts
import GithubProvider from 'next-auth/providers/github'
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // A secret string you define, to ensure correct encryption
  secret: 'your-secret-here',
  providers: [
    // @ts-expect-error Use .default here for it to work during SSR.
    GithubProvider.default({
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret'
    })
  ]
})

警告

next-auth/providers/[PROVIDER] 导入您的提供商后,请在提供商数组配置中使用 .default() 调用它。 这是 SSR 正常运行所必需的。

NuxtAuthHandler 接受 NextAuth.js 接受的所有选项用于其 API 初始化。 使用此处配置身份验证提供商(OAuth、凭据流等)、您的密钥、为身份验证事件添加回调、配置自定义记录器等。 阅读 NextAuth.js 文档以查看所有可能的选项。

设置密钥

除了设置提供商之外,您还需要设置一个 secret,用于加密 JWT 令牌。 为了避免密钥的硬编码,您可以通过使用环境变量并在运行时导出它,或者通过使用 Nuxt useRuntimeConfig(然后在运行时也设置正确的环境)使其在运行时可配置。

ts
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // A secret string you define, to ensure correct encryption - NUXT_AUTH_SECRET required in production
  secret: useRuntimeConfig().authSecret

  // rest of your authentication configuration here!
})
完整代码
ts
// file: ~/server/api/auth/[...].ts
import GithubProvider from 'next-auth/providers/github'
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  secret: useRuntimeConfig().authSecret,
  providers: [
    // @ts-expect-error Use .default here for it to work during SSR.
    GithubProvider.default({
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret'
    })
  ]
})

下一步

恭喜! 您现在已经配置了您的第一个身份验证提供商,并且可以登录到应用程序了! 我们建议执行以下后续步骤以继续配置您的应用程序

根据 MIT 许可证发布。