AuthJS 快速入门
本指南旨在介绍如何使用 AuthJS 提供商设置 @sidebase/nuxt-auth
,AuthJS 提供商最适合为已建立的 OAuth 提供商或基于 magic-url 的登录方式提供即插即用的 OAuth 功能。
安装
如果要使用 AuthJS 提供商,您必须安装 next-auth
。 对于除 npm 以外的所有包管理器,您必须手动安装与 nuxt-auth 并行的对等依赖项。
pnpm i next-auth@4.21.1
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'
})
]
})
下一步
恭喜! 您现在已经配置了您的第一个身份验证提供商,并且可以登录到应用程序了! 我们建议执行以下后续步骤以继续配置您的应用程序