NuxtAuthHandler

NuxtAuthHandler 是内置于 AuthJS 的 NextAuthHandler 的适配版本。您可以在快速入门部分了解有关如何设置 NuxtAuthHandler 最简版本的更多信息。

Secret

secret 是一个随机字符串，用于哈希令牌、签名和加密 cookie 以及生成加密密钥。在开发环境中，secret 会自动设置为 NuxtAuthHandler 的 SHA 哈希值。在生产环境中，我们建议设置一个 runtimeConfig 值来定义更安全的值。

~/server/api/auth/[...].ts

import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  secret: useRuntimeConfig().authSecret,
  // your authentication configuration here!
})

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    authSecret: '123',
  }
})

.env

NUXT_AUTH_SECRET="YOUR-SUPER-SECURE-SECRET"

提供商

提供商是已注册的身份验证方法，您的用户可以使用这些方法登录到您的应用程序。 NuxtAuth 提供了许多预配置的提供商，您可以使用它们来快速启动您的项目。 这些包括 OAuth 提供商、基于电子邮件的提供商 (Magic URLs) 和 凭据提供商。 除了使用预构建的提供商之外，您还可以创建自己的提供商。

您可以在此处找到所有预构建提供商的概述。 如果您想创建自己的提供商，请访问 NextAuth 文档。

警告

next-auth@4 提供商需要在 Vite 中额外添加 .default 才能工作。 这在 next-auth@5 (authjs) 中将不再是必需的。

import GithubProvider from 'next-auth/providers/github'

export default NuxtAuthHandler({
  providers: [
    // @ts-expect-error You need to use .default here for it to work during SSR. May be fixed via Vite at some point
    GithubProvider.default({ 
      // GitHub provider configuration
    })
  ]
})

回调

NuxtAuthHandler 内部的回调是异步函数，允许您Hook到身份验证流程并对其进行修改。 当您需要执行以下操作时，这很有帮助：

• 更改 JWT 令牌或会话数据内部的数据
• 添加对刷新令牌的支持

回调非常强大，允许您根据需要修改身份验证流程。

import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // your authentication configuration here!
  callbacks: {
    /* on before signin */
    async signIn({ user, account, profile, email, credentials }) {
      return true
    },
    /* on redirect to another url */
    async redirect({ url, baseUrl }) {
      return baseUrl
    },
    /* on session retrival */
    async session({ session, user, token }) {
      return session
    },
    /* on JWT token creation or mutation */
    async jwt({ token, user, account, profile, isNewUser }) {
      return token
    }
  }
})

每个回调的一些用例可能是

• signIn: 检查用户是否被限制访问应用程序等，并终止登录流程。
• redirect: 根据需要动态计算且无法在启动时设置的参数（例如，通过功能标志或数据库值）自定义回调 URL。
• session: 获取并将其他数据注入会话。 阅读更多 此处。
• jwt: 在 JWT 令牌内部注入或更新数据，并管理刷新令牌和访问令牌。

您可以在官方 NextAuth 文档上阅读有关这些回调中的每一个的更多信息，包括它们提供的数据以及期望的返回值。

事件

事件是在身份验证流程中某些操作期间调用的异步回调函数。 它们可用于记录某些事件或调试您的身份验证流程。

import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // your authentication configuration here!
  events: {
    async signIn(message) { /* on successful sign in */ },
    async signOut(message) { /* on signout */ },
    async createUser(message) { /* user created */ },
    async updateUser(message) { /* user updated - e.g. their email was verified */ },
    async linkAccount(message) { /* account (e.g. GitHub) linked to a user */ },
    async session(message) { /* session is active */ },
  }
})

您可以在官方 NextAuth 文档上阅读有关这些事件中的每一个以及它们提供的数据的更多信息。

页面

在页面配置中，您可以定义与您的身份验证相关页面匹配的自定义路由。 在此处设置新页面将覆盖模块中包含的默认身份验证页面。

如果您想了解有关自定义页面和自定义的更多信息，请阅读完整的指南此处。

import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // your authentication configuration here!
  pages: {
    signIn: '/auth/signIn',
    signOut: '/auth/signOut',
    error: '/auth/error',
    verifyRequest: '/auth/verify-request',
    newUser: '/auth/new-user'
  }
})