AuthJS 快速入门

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

安装

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

pnpmyarn

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-auth 和 next-auth 后，您现在可以配置 NuxtAuth 以使用 AuthJS 提供商。在您的 nuxt.config.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

如果设置为 true，authjs 将使用 x-forwarded-host 或 host 标头，而不是 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 文档中阅读更多信息。

import { NuxtAuthHandler } from '#auth'

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

添加提供商

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

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（然后在运行时也设置正确的环境）使其在运行时可配置。

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!
})

完整代码

// 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'
    })
  ]
})

下一步

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

AuthJS 快速入门 ​

安装 ​

配置 ​

trustHost ​

defaultProvider ​

addDefaultCallbackUrl ​

NuxtAuthHandler ​

添加提供商 ​

设置密钥 ​

下一步 ​