@auth/core

⚠️

实验性 @auth/core 正在积极开发中。

这是 Auth.js 库的主要入口点。

基于请求和响应 Web 标准 API。主要用于实现框架特定软件包，但也可以直接使用。

安装

npm install @auth/core

pnpm add @auth/core

yarn add @auth/core

bun add @auth/core

使用

import { Auth } from "@auth/core"
 
const request = new Request("https://example.com")
const response = await Auth(request, {...})
 
console.log(response instanceof Response) // true

资源

AuthConfig

配置 Auth 方法。

示例

import Auth, { type AuthConfig } from "@auth/core"
 
export const authConfig: AuthConfig = {...}
 
const request = new Request("https://example.com")
const response = await AuthHandler(request, authConfig)

参见

初始化

扩展自

属性

adapter?

optional adapter: Adapter;

您可以使用适配器选项传入您的数据库适配器。

basePath?

optional basePath: string;

Auth.js API 端点的基本路径。

默认

"/api/auth" in "next-auth"; "/auth" with all other frameworks

callbacks?

optional callbacks: {
  jwt: (params) => Awaitable<null | JWT>;
  redirect: (params) => Awaitable<string>;
  session: (params) => Awaitable<Session | DefaultSession>;
  signIn: (params) => Awaitable<string | boolean>;
};

回调是异步函数，您可以使用它们来控制执行操作时发生的事情。回调非常强大，尤其是在涉及 JSON Web 令牌的情况下，因为它们允许您在没有数据库的情况下实现访问控制，以及与外部数据库或 API 集成。

jwt()?

optional jwt: (params) => Awaitable<null | JWT>;

每当创建 JSON Web 令牌（即登录时）或更新 JSON Web 令牌（即访问客户端中的会话时）时，都会调用此回调。您在此处返回的任何内容都将保存在 JWT 中并转发到会话回调。您可以在那里控制应该返回给客户端的内容。其他任何内容将被保留在您的前端。JWT 默认情况下通过您的 AUTH_SECRET 环境变量加密。

session 回调

参数

参数	类型	描述
`params`	`对象`	-
`params.account`?	`null` \| `Account`	包含有关用于登录的提供商的信息。还包括 TokenSet 注意当 `trigger` 为 `"signIn"` 或 `"signUp"` 时可用
`params.isNewUser`?	`布尔值`	已弃用改为使用 `trigger === "signUp"`
`params.profile`?	`配置文件`	从您的提供商返回的 OAuth 配置文件。 (在 OIDC 的情况下，它将是解码的 ID 令牌或 /userinfo 响应) 注意当 `trigger` 为 `"signIn"` 时可用。
`params.session`?	`任何`	当使用 AuthConfig.session `strategy: "jwt"` 时，这是数据通过 `useSession().update` 方法从客户端发送。 ⚠ 注意，您应该在使用此数据之前对其进行验证。
`params.token`	`JWT`	当 `trigger` 为 `"signIn"` 或 `"signUp"` 时，它将是 JWT 的子集， `name`、`email` 和 `image` 将被包含。否则，它将是后续调用的完整 JWT。
`params.trigger`?	`"signIn"` \| `"signUp"` \| `"update"`	检查 jwt 回调被调用的原因。可能的原因是 - 用户登录：回调首次被调用时，`user`、`profile` 和 `account` 将存在。 - 用户注册：首次在数据库中创建用户（当 AuthConfig.session.strategy 设置为 `"database"` 时） - 更新事件：由 `useSession().update` 方法触发。在后者的情況下，`trigger` 将为 `undefined`。
`params.user`	`User` \| `AdapterUser`	OAuthConfig.profile 或 CredentialsConfig.authorize 回调的结果。注意当 `trigger` 为 `"signIn"` 或 `"signUp"` 时可用。资源 - 凭据提供者 - 用户数据库模型

Awaitable<null | JWT>

redirect()?

optional redirect: (params) => Awaitable<string>;

当用户被重定向到回调 URL 时（例如，登录或注销时）调用此回调。默认情况下，只允许与原点主机相同的 URL。您可以使用此回调来定制该行为。

文档

示例

callbacks: {
  async redirect({ url, baseUrl }) {
    // Allows relative callback URLs
    if (url.startsWith("/")) return `${baseUrl}${url}`
 
    // Allows callback URLs on the same origin
    if (new URL(url).origin === baseUrl) return url
 
    return baseUrl
  }
}

参数

参数	类型	描述
`params`	`对象`	-
`params.baseUrl`	`字符串`	站点的默认基本 URL（可用作回退）
`params.url`	`字符串`	客户端提供的回调 URL

Awaitable<string>

session()?

optional session: (params) => Awaitable<Session | DefaultSession>;

每当检查会话时调用此回调。（例如，当调用 /api/session 端点，使用 useSession 或 getSession 时）。返回值将暴露给客户端，所以请谨慎使用这里返回的内容！如果您想向客户端提供通过 JWT 回调添加到令牌中的任何内容，您必须在这里也明确返回它。

⚠ 默认情况下，为了提高安全性，只返回令牌的一个子集（电子邮件、姓名、图像）。

只有在使用 JWT 会话策略时，token 参数才可用；只有在使用数据库会话策略时，user 参数才可用。

jwt 回调

示例

callbacks: {
  async session({ session, token, user }) {
    // Send properties to the client, like an access_token from a provider.
    session.accessToken = token.accessToken
 
    return session
  }
}

参数

参数	类型
`params`	{ `session`: { `user`: `AdapterUser`; } & `AdapterSession`; `user`: `AdapterUser`; } & { `session`: `Session`; `token`: `JWT`; } & { `newSession`: `any`; `trigger`: `"update"`; }

Awaitable<Session | DefaultSession>

optional signIn: (params) => Awaitable<string | boolean>;

控制用户是否被允许登录。返回 true 将继续登录流程。返回 false 或抛出错误将停止登录流程，并将用户重定向到错误页面。返回字符串将把用户重定向到指定的 URL。

未处理的错误将抛出一个 AccessDenied，其消息设置为原始错误。

AccessDenied

示例

callbacks: {
 async signIn({ profile }) {
  // Only allow sign in for users with email addresses ending with "yourdomain.com"
  return profile?.email?.endsWith("@yourdomain.com")
}

参数

参数	类型	描述
`params`	`对象`	-
`params.account`?	`null` \| `Account`	-
`params.credentials`?	`Record`<`string`, `CredentialInput`>	如果使用凭据提供者，它包含用户凭据
`params.email`?	`对象`	如果使用电子邮件提供者，在第一次调用时，它包含一个 `verificationRequest: true` 属性来指示它是在验证请求流程中触发的。当用户点击登录链接后，回调被调用时，此属性将不存在。您可以检查 `verificationRequest` 属性以避免向黑名单上的地址或域名发送电子邮件，或者只为允许列表中的电子邮件地址明确生成电子邮件。。
`params.email.verificationRequest`?	`布尔值`	-
`params.profile`?	`配置文件`	如果使用 OAuth 提供者，它包含您提供者返回的完整的 OAuth 个人资料。
`params.user`	`User` \| `AdapterUser`	-

Awaitable<string | boolean>

cookies?

optional cookies: Partial<CookiesOptions>;

您可以覆盖 Auth.js 使用的任何 cookie 的默认 cookie 名称和选项。您可以使用自定义属性指定一个或多个 cookie，缺失的选项将使用 Auth.js 定义的默认值。如果您使用此功能，您可能需要创建条件行为以支持在开发和生产版本中设置不同的 cookie 策略，因为您将选择退出内置的动态策略。

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

默认

{}

debug?

optional debug: boolean;

将 debug 设置为 true 以启用身份验证和数据库操作的调试消息。

⚠ 如果您添加了自定义 AuthConfig.logger，此设置将被忽略。

默认

false

events?

optional events: {
  createUser: (message) => Awaitable<void>;
  linkAccount: (message) => Awaitable<void>;
  session: (message) => Awaitable<void>;
  signIn: (message) => Awaitable<void>;
  signOut: (message) => Awaitable<void>;
  updateUser: (message) => Awaitable<void>;
};

事件是不会返回响应的异步函数，它们对于审计日志记录很有用。您可以为下面列出的任何事件指定一个处理程序——例如，用于调试或创建审计日志。消息对象的内容因流程而异（例如，OAuth 或电子邮件身份验证流程，JWT 或数据库会话等），但通常包含用户对象和/或 JSON Web 令牌的内容以及与事件相关的其他信息。

默认

{}

createUser()?

optional createUser: (message) => Awaitable<void>;

参数

参数	类型
`message`	`对象`
`message.user`	`用户`

Awaitable<void>

linkAccount()?

optional linkAccount: (message) => Awaitable<void>;

参数

参数	类型
`message`	`对象`
`message.account`	`账户`
`message.profile`	`User` \| `AdapterUser`
`message.user`	`User` \| `AdapterUser`

Awaitable<void>

session()?

optional session: (message) => Awaitable<void>;

消息对象将包含以下内容之一，具体取决于您使用的是 JWT 还是数据库持久化会话

token: 此会话的 JWT。
session: 来自您的适配器的会话对象。

参数

参数	类型
`message`	`对象`
`message.session`	`会话`
`message.token`	`JWT`

Awaitable<void>

optional signIn: (message) => Awaitable<void>;

如果使用 credentials 类型的身份验证，用户就是来自您的凭据提供者的原始响应。对于其他提供者，您将从您的适配器、帐户以及用户是否为您的适配器的新用户，获得用户对象。

参数

参数	类型
`message`	`对象`
`message.account`?	`null` \| `Account`
`message.isNewUser`?	`布尔值`
`message.profile`?	`配置文件`
`message.user`	`用户`

Awaitable<void>

signOut()?

optional signOut: (message) => Awaitable<void>;

消息对象将包含以下内容之一，具体取决于您使用的是 JWT 还是数据库持久化会话

token: 此会话的 JWT。
session: 来自您适配器的正在结束的会话对象。

参数

参数	类型
`message`	{ `session`: `undefined` \| `null` \| `void` \| `AdapterSession`; } \| { `token`: `null` \| `JWT`; }

Awaitable<void>

updateUser()?

optional updateUser: (message) => Awaitable<void>;

参数

参数	类型
`message`	`对象`
`message.user`	`用户`

Awaitable<void>

experimental?

optional experimental: {
  enableWebAuthn: boolean;
};

使用此选项启用实验性功能。启用后，它将向控制台打印警告消息。

注意

实验性功能不能保证稳定，可能会在未经通知的情况下更改或删除。请谨慎使用。

默认值

{}

enableWebAuthn?

optional enableWebAuthn: boolean;

启用 WebAuthn 支持。

默认值

false

jwt?

optional jwt: Partial<JWTOptions>;

如果您未指定 AuthConfig.adapter，则默认情况下会启用 JSON Web 令牌。 JSON Web 令牌默认情况下是加密的 (JWE)。我们建议您保持此行为。

logger?

optional logger: Partial<LoggerInstance>;

覆盖任何日志记录级别（undefined 级别将使用内置日志记录器），并在 NextAuth 中拦截日志。您可以使用此选项将 NextAuth 日志发送到第三方日志记录服务。

示例

// /auth.ts
import log from "logging-service"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  logger: {
    error(code, ...message) {
      log.error(code, message)
    },
    warn(code, ...message) {
      log.warn(code, message)
    },
    debug(code, ...message) {
      log.debug(code, message)
    }
  }
})

⚠ 设置后，将忽略 AuthConfig.debug 选项

默认值

console

pages?

optional pages: Partial<PagesOptions>;

如果您想创建自定义登录、注销和错误页面，请指定 URL。指定的页面将覆盖相应的内置页面。

默认值

{}

示例

  pages: {
    signIn: '/auth/signin',
    signOut: '/auth/signout',
    error: '/auth/error',
    verifyRequest: '/auth/verify-request',
    newUser: '/auth/new-user'
  }

providers

providers: Provider[];

用于登录的认证提供商列表（例如 Google、Facebook、Twitter、GitHub、电子邮件等），按任何顺序。这可以是内置提供商之一，也可以是具有自定义提供商的对象。

默认值

[]

raw?

optional raw: typeof raw;

redirectProxyUrl?

optional redirectProxyUrl: string;

设置后，在 OAuth 登录流程期间，授权请求的 redirect_uri 将根据此值设置。

如果您希望在预览 URL（如 Vercel）上使用 OAuth，那么这很有用，您事先不知道最终的部署 URL。

url 必须包含完整路径，直到 Auth.js 初始化的位置。

注意

这将自动启用提供商上的 state OAuth2Config.checks。

示例

"https://authjs.example.com/api/auth"

您也可以单独覆盖每个提供商的此设置。

示例

GitHub({
  ...
  redirectProxyUrl: "https://github.example.com/api/auth"
})

默认值

AUTH_REDIRECT_PROXY_URL 环境变量

另请参见：指南：保护预览部署

secret?

optional secret: string | string[];

用于对令牌进行哈希处理、签名 Cookie 和生成加密密钥的随机字符串。

要生成随机字符串，您可以使用 Auth.js CLI：npx auth secret

注意

您也可以传递一个 secrets 数组，在这种情况下，第一个成功解密 JWT 的 secret 将被使用。这对于在不使现有会话失效的情况下轮换 secret 很有用。较新的 secret 应该添加到数组的开头，它将用于所有新的会话。

session?

optional session: {
  generateSessionToken: () => string;
  maxAge: number;
  strategy: "jwt" | "database";
  updateAge: number;
};

配置您的会话，例如您是否要使用 JWT 或数据库、闲置会话过期的时间或在使用数据库时限制写入操作。

generateSessionToken()?

optional generateSessionToken: () => string;

为基于数据库的会话生成自定义会话令牌。默认情况下，根据 Node.js 版本生成随机 UUID 或字符串。但是，您可以指定自己的自定义字符串（例如 CUID）来使用。

默认值

randomUUID 或 randomBytes.toHex 取决于 Node.js 版本

字符串

maxAge?

optional maxAge: number;

从现在起会话到期时的相对时间（以秒为单位）。

默认值

2592000 // 30 days

strategy?

optional strategy: "jwt" | "database";

选择您要保存用户会话的方式。默认值为 "jwt"，即会话 cookie 中的加密 JWT (JWE)。

但是，如果您使用 adapter，我们将将其默认设置为 "database"。您仍然可以通过显式定义 "jwt" 来强制使用 JWT 会话。

使用 "database" 时，会话 cookie 将只包含 sessionToken 值，该值用于在数据库中查找会话。

文档 | 适配器 | 关于 JSON Web 令牌

updateAge?

optional updateAge: number;

会话更新的频率（以秒为单位）。如果设置为 0，则每次都会更新会话。

默认值

86400 // 1 day

skipCSRFCheck?

optional skipCSRFCheck: typeof skipCSRFCheck;

theme?

optional theme: Theme;

更改内置 AuthConfig.pages 的主题。

trustHost?

optional trustHost: boolean;

Auth.js 依赖于传入请求的 host 标头才能正常运行。因此，此属性需要设置为 true。

确保您的部署平台安全地设置了 host 标头。

基于官方 Auth.js 的库将尝试自动为某些已知安全地设置 host 标头的部署平台（例如：Vercel）设置此值。

useSecureCookies?

optional useSecureCookies: boolean;

设置为 true 时，NextAuth.js 设置的所有 Cookie 将只能从 HTTPS URL 访问。此选项默认为 false，用于以 http:// 开头的 URL（例如 https://127.0.0.1:3000），以方便开发人员。您可以手动将此选项设置为 false 来禁用此安全功能，并允许从非安全 URL 访问 Cookie（不建议这样做）。

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

默认值为 false HTTP 和 true 用于 HTTPS 站点。

customFetch

const customFetch: typeof customFetch;

🚫

此选项允许您覆盖提供程序用来直接向提供程序的 OAuth 端点发出请求的默认 fetch 函数。使用不当会导致安全隐患。

它可用于支持公司代理、自定义获取库、缓存发现端点、为测试添加模拟、记录、为不符合规范的提供商设置自定义标头/参数等。

示例

import { Auth, customFetch } from "@auth/core"
import GitHub from "@auth/core/providers/github"
 
const dispatcher = new ProxyAgent("my.proxy.server")
function proxy(...args: Parameters<typeof fetch>): ReturnType<typeof fetch> {
  return undici(args[0], { ...(args[1] ?? {}), dispatcher })
}
 
const response = await Auth(request, {
  providers: [GitHub({ [customFetch]: proxy })]
})

参见

raw

const raw: typeof raw;

🚫

此选项适用于框架作者。

Auth.js 默认情况下返回一个 Web 标准 Response，但如果您正在实现一个框架，您可能希望通过将此值传递给 AuthConfig.raw 来访问原始内部响应。

skipCSRFCheck

const skipCSRFCheck: typeof skipCSRFCheck;

🚫

此选项适用于框架作者。

Auth.js 带有内置的 CSRF 保护，但如果您正在实现一个已经针对 CSRF 攻击受到保护的框架，您可以通过将此值传递给 AuthConfig.skipCSRFCheck 来跳过此检查。

Auth()

Auth(request, config)

Auth(request, config): Promise<ResponseInternal>

Auth.js 提供的核心功能。

接收标准 Request 并返回 Response。

参数

参数	类型
`request`	`Request`
`config`	`AuthConfig` & { `raw`: typeof `raw`; }

Promise<ResponseInternal>

示例

import { Auth } from "@auth/core"
 
const request = new Request("https://example.com")
const response = await Auth(request, {
  providers: [Google],
  secret: "...",
  trustHost: true,
})

参见

文档

Auth(request, config)

Auth(request, config): Promise<Response>

Auth.js 提供的核心功能。

接收标准 Request 并返回 Response。

参数

参数	类型
`request`	`Request`
`config`	`Omit`<`AuthConfig`, `"raw"`>

Promise<Response>

示例

import { Auth } from "@auth/core"
 
const request = new Request("https://example.com")
const response = await Auth(request, {
  providers: [Google],
  secret: "...",
  trustHost: true,
})

参见

文档

createActionURL()

createActionURL(
   action, 
   protocol, 
   headers, 
   envObject, 
   config): URL

参数

参数	类型
`action`	`AuthAction`
`protocol`	`字符串`
`headers`	`Headers`
`envObject`	`任何`
`config`	`Pick`<`AuthConfig`, `"logger"` \| `"basePath"`>

URL

isAuthAction()

isAuthAction(action): action is AuthAction

参数

参数	类型
`action`	`字符串`

action 是 AuthAction

setEnvDefaults()

setEnvDefaults(
   envObject, 
   config, 
   suppressBasePathWarning): void

在配置对象上设置默认的 env 变量

参数

参数	类型	默认值
`envObject`	`任何`	`undefined`
`config`	`AuthConfig`	`undefined`
`suppressBasePathWarning`	`布尔值`	`false`

void

概述 adapters

@auth/core

安装

使用

资源

AuthConfig

示例

参见

扩展自

属性

adapter?

basePath?

默认

callbacks?

jwt()?

参数

返回

redirect()?

示例

参数

返回

session()?

示例

参数

返回

signIn()?

示例

参数

返回

cookies?

默认

debug?

默认

events?

默认

createUser()?

参数

返回

linkAccount()?

参数

返回

session()?

参数

返回

signIn()?

参数

返回

signOut()?

参数

返回

updateUser()?

参数

返回

experimental?

注意

默认值

enableWebAuthn?

默认值

jwt?

logger?

示例

默认值

pages?

默认值

示例

providers

默认值

raw?

redirectProxyUrl?

注意

示例

示例

默认值

secret?

注意

session?

generateSessionToken()?

默认值

返回

maxAge?

默认值