认证概述
认证是任何应用程序的关键部分。Payload 提供了一种安全、可移植的开箱即用用户账户管理方案。Payload 认证设计用于管理面板和你自己的外部应用程序，完全消除了对付费第三方平台和服务的需求。
以下是你自己应用程序中认证的一些常见用例：
- 电商应用的客户账户
- SaaS产品的用户账户
- 需要用户登录和管理个人资料的P2P应用或社交网站
- 需要玩家长期追踪进度的在线游戏
当在Collection上启用认证时，Payload会注入支持完整用户流程所需的所有功能。这包括所有认证相关操作如账户创建、登录登出和密码重置，所有认证相关邮件如邮箱验证和密码重置邮件，以及从管理面板管理用户所需的任何UI。
要在Collection上启用认证，使用Collection配置中的auth属性：
import type { CollectionConfig } from 'payload'
export const Users: CollectionConfig = {
// ...
auth: true, // highlight-line
}
启用认证的管理员Collection的管理面板截图
配置选项
任何 Collection 都可以选择启用认证功能。启用后，该 Collection 中创建的每个文档都可以视为一个"用户"。这将为你的 Collection 启用完整的认证流程，包括登录、登出、重置密码等功能。
注意： Payload 默认提供了一个启用认证的 User Collection，用于访问管理后台。更多详情。
要在 Collection 中启用认证功能，请在 Collection Config 中使用 auth 属性：
import type { CollectionConfig } from 'payload'
export const Admins: CollectionConfig = {
// ...
// highlight-start
auth: {
tokenExpiration: 7200, // 用户保持登录状态的秒数
verify: true, // 在允许认证前要求邮箱验证
maxLoginAttempts: 5, // 登录失败X次后自动锁定用户
lockTime: 600 * 1000, // 允许最大登录尝试次数的时间段
// 更多选项可用
},
// highlight-end
}
提示： 对于默认认证行为，可设置 auth: true。这是大多数应用的理想起点。
注意： 启用认证的 Collection 会自动注入 hash、salt 和 email 字段。更多详情。
以下是可用的配置选项：
| 选项 | 描述 |
|---|---|
cookies | 设置 cookie 选项，包括 secure、sameSite 和 domain。适用于高级用户。 |
depth | 创建 JWT 并将 user 绑定到 req 时，user 文档应填充的深度级别。默认为 0，除非绝对必要，否则不应修改，因为这会影响性能。 |
disableLocalStrategy | 高级选项 - 禁用 Payload 内置的本地认证策略。仅在你已用自定义认证机制替换 Payload 的认证机制时使用此属性。 |
forgotPassword | 自定义 forgotPassword 操作的功能方式。更多详情。 |
lockTime | 设置用户因超过 maxLoginAttempts 限制而被锁定的时间（毫秒）。 |
loginWithUsername | 允许用户使用用户名/密码登录的功能。更多详情 |
maxLoginAttempts | 限制用户登录尝试次数。超过此限制将自动锁定用户认证。设置为 0 可禁用此功能。 |
removeTokenFromResponses | 设置为 true 可从登录或刷新等认证 API 响应中移除 token。 |
strategies | 高级选项 - 自定义认证策略数组，用于扩展此 Collection 的认证功能。更多详情。 |
tokenExpiration | 用户保持登录状态的时间（秒）。JWT 和 HTTP-only cookie 将同时过期。 |
useAPIKey | Payload 认证支持在每个启用认证的 Collection 用户上设置 API 密钥。更多详情。 |
verify | 设置为 true 或传递带有验证选项的对象，要求用户在登录应用前通过邮箱验证。更多详情。 |
使用用户名登录
你可以通过将 loginWithUsername 属性设置为 true，允许用户使用用户名而非电子邮件地址登录。
示例：
{
slug: 'customers',
auth: {
loginWithUsername: true,
},
}
或者，你也可以传入一个包含额外选项的对象：
{
slug: 'customers',
auth: {
loginWithUsername: {
allowEmailLogin: true, // 默认值: false
requireEmail: false, // 默认值: false
},
},
}
allowEmailLogin
如果设置为 true，用户可以使用用户名或电子邮件地址登录。如果设置为 false，用户只能使用用户名登录。
requireEmail
如果设置为 true，创建新用户时需要提供电子邮件地址。如果设置为 false，创建时不需要电子邮件。
自动登录
出于测试和演示目的，你可能希望跳过强制用户登录才能访问应用的步骤。通常情况下，所有用户都应被要求登录，但你可以通过启用自动登录来加快本地开发速度。
要启用自动登录，请在 Payload 配置 中设置 autoLogin 属性：
import { buildConfig } from 'payload'
export default buildConfig({
// ...
// highlight-start
admin: {
autoLogin:
process.env.NODE_ENV === 'development'
? {
email: 'test@example.com',
password: 'test',
prefillOnly: true,
}
: false,
},
// highlight-end
})
警告： 推荐的使用方式是通过 环境变量 来控制此功能。这将确保它在生产环境中被禁用。
以下是可用的选项：
| 选项 | 描述 |
|---|---|
username | 要自动登录的用户名 |
email | 要自动登录的邮箱地址 |
password | 要自动登录的密码。仅在 prefillOnly 设为 true 时需要 |
prefillOnly | 如果设为 true，登录凭证将被预填充，但用户仍需点击登录按钮 |
操作
所有与认证相关的操作都可以通过 Payload 的 REST、Local 和 GraphQL API 进行。当你启用 Authentication 时，这些操作会自动添加到你的 Collection 中。更多详情。
策略
Payload 开箱即用提供了三种强大的认证策略：
这些策略可以协同工作或独立使用。你也可以创建自定义策略以满足特定需求。更多详情。
HTTP-Only Cookies
HTTP-only cookies 是一种高度安全的方法，用于在用户设备上存储可识别数据，使 Payload 能够自动识别返回用户，直到 cookie 过期。与 JWT 不同，它们完全受到保护，不受常见 XSS 攻击的影响，且无法通过浏览器中的 JavaScript 读取。更多详情。
JSON Web Tokens
JWT (JSON Web Tokens) 也可用于执行认证。令牌在 login、refresh 和 me 操作时生成，可以附加到后续请求中以认证用户。更多详情。
API Keys
可以在认证集合上启用 API Keys。当你需要从第三方服务对 Payload 进行认证时，这些特别有用。更多详情。
自定义策略
在某些情况下，这些可能不足以满足你的应用需求。Payload 设计上具有可扩展性，因此你可以在需要时连接自己的策略。更多详情。