安全性

本页面包含有关 Better Auth 安全功能的信息。

密码哈希

Better Auth 默认使用 scrypt 算法进行密码哈希。该算法设计为内存硬且 CPU 密集型，能够抵抗暴力破解攻击。您可以通过配置中的 password 选项自定义密码哈希函数。该选项应包含用于哈希密码的 hash 函数和用于验证密码的 verify 函数。

秘钥轮换

Better Auth 支持对 BETTER_AUTH_SECRET 进行非破坏性的轮换。当您通过 secrets 选项或 BETTER_AUTH_SECRETS 环境变量配置版本化秘钥时，所有新的加密数据都会包含一个密钥版本标识符。解密时会直接通过版本号查找密钥——无需尝试性解密。

轮换前使用旧秘钥加密的遗留数据（裸十六进制格式）仍可通过原始的 BETTER_AUTH_SECRET 作为回退进行解密。无需数据库迁移或停机。数据在下一次写入时会懒惰地使用当前密钥重新加密。

配置细节请参见 secrets 选项。

会话管理

会话过期

Better Auth 使用安全的会话管理来保护用户数据。会话存储在数据库或次级存储（如果配置了）中，以防止未经授权的访问。默认情况下，会话在 7 天后过期，您可以在配置中自定义这个值。此外，每次使用会话时，如果达到 updateAge 阈值（默认 1 天），过期时间将被延长。

会话撤销

Better Auth 允许您撤销会话以增强安全性。当会话被撤销后，用户会退出登录，无法再访问应用。已登录用户还可以撤销自己的会话，以便从不同设备或浏览器登出。

更多详情请参见 会话管理。

CSRF 保护

Better Auth 包含多重防护措施以防止跨站请求伪造（CSRF）攻击：

1. 避免简单请求 详情请参见 避免简单请求。Better Auth 仅允许带有非简单头部或 Content-Type 为 application/json 的请求。

2. 来源验证 每个请求的 Origin 头部都会被验证，以确认它来自您的应用或其他明确受信任的来源。来自不可信来源的请求会被拒绝。默认情况下，Better Auth 信任您应用的基础 URL，但您可以通过 trustedOrigins 配置选项指定其他受信任的来源。

3. 安全 Cookie 设置
   会话 Cookie 默认使用 SameSite=Lax 属性，防止浏览器在大多数跨站请求中发送 Cookie。您可以通过 defaultCookieAttributes 选项覆盖此行为。

4. 首次登录的 Fetch Metadata 防护 Better Auth 还使用 Fetch Metadata 头部（Sec-Fetch-Site、Sec-Fetch-Mode、Sec-Fetch-Dest）为 首次登录场景 提供额外的 CSRF 防护，此时客户端尚未拥有任何 Cookie。

   此防护适用于 登录和注册邮件路由，这些路由接受表单提交（简单请求）以支持渐进增强模式。

   当收到 没有 Cookie 的登录或注册请求时：

   • 如果浏览器指示 跨站导航（例如：Sec-Fetch-Site: cross-site 且 Sec-Fetch-Mode: navigate），Better Auth 会阻止该请求，将其视为潜在的登录 CSRF 攻击。

   • 如果请求是 同源或同站 的，Better Auth 仍会使用现有的来源验证逻辑验证 Origin/Referer。

   • 如果客户端 未发送 Fetch Metadata 头部（旧版浏览器、某些移动 WebView 或非浏览器客户端），Better Auth 将回退到 之前的行为，仅在存在 Cookie 时执行来源验证，以保持向后兼容性。

   此机制允许现代浏览器在 不依赖 CSRF 令牌或客户端端 JavaScript 的情况下，获得针对首次登录 CSRF 攻击的更强防护，并与渐进增强模式无缝协作。

   非浏览器 HTTP 客户端（移动应用、服务器对服务器）应在包含 Cookie 的请求中正确设置 Origin 或 Referer 头部，以确保无论是否支持 Fetch Metadata，都能进行正确的 CSRF 验证。

5. GET 请求不执行变更（附带额外防护） GET 请求被视为只读操作，不应更改应用状态。在必须执行变更的情况下——例如 OAuth 回调——Better Auth 会应用额外的安全措施，包括验证 nonce 和 state 参数以确保请求的真实性。

禁用安全检查

Better Auth 提供了两个独立选项，用于禁用不同方面的安全检查：

disableCSRFCheck

禁用 所有 CSRF 保护，包括：

• 存在 Cookie 时的来源头部验证
• Fetch Metadata 检查（Sec-Fetch-Site、Sec-Fetch-Mode、Sec-Fetch-Dest）
• 首次登录场景的跨站导航阻止

{
  advanced: {
    disableCSRFCheck: true
  }
}

disableOriginCheck

禁用对 trustedOrigins 的 URL 验证，包括：

• callbackURL 验证
• redirectTo 验证
• errorCallbackURL 验证
• newUserCallbackURL 验证

{
  advanced: {
    disableOriginCheck: true
  }
}

总结

OAuth 状态与 PKCE

为保障 OAuth 流程安全，Better Auth 将 OAuth 状态和 PKCE（代码交换证明密钥）存储在数据库中。状态用于防止 CSRF 攻击，PKCE 防止代码注入攻击。OAuth 流程完成后，这些值将从数据库中移除。

Cookies

当基础 URL 使用 https 时，Better Auth 默认分配安全的 Cookie。这些安全 Cookie 是加密的，仅通过安全连接传输，增加了额外的保护层。它们也默认设置 sameSite 属性为 lax，以防止跨站请求伪造攻击。同时启用了 httpOnly 属性，防止客户端 JavaScript 访问 Cookie。

对于跨子域 Cookie，您可以在配置中设置 crossSubDomainCookies 选项。该选项允许跨子域共享 Cookie，实现不同子域间的无缝认证。

自定义 Cookies

您可以自定义 Cookie 名称，以降低指纹识别攻击风险，并根据需要设置具体的 Cookie 选项以获得更细粒度的控制。详情请参见 Cookie 选项。

插件也可以设置自定义 Cookie 选项，以满足特定安全需求。如果在非浏览器环境中使用 Better Auth，插件还提供了安全管理 Cookie 的方法。

速率限制

Better Auth 内置了速率限制功能，用于防御暴力破解攻击。速率限制默认应用于所有路由，对潜在风险较高的特定路由会实施更严格的限制。

IP 地址头部

Better Auth 使用客户端 IP 地址进行速率限制和安全监控。默认情况下，它从标准的 X-Forwarded-For 头部读取 IP 地址。但您可以配置特定的受信任头部，以确保准确的 IP 地址检测并防止 IP 欺骗攻击。

您可以在 Better Auth 配置中设置 IP 地址头部：

{
  advanced: {
    ipAddress: {
      ipAddressHeaders: ['cf-connecting-ip'] // 或其他自定义头部
    }
  }
}

这确保 Better Auth 仅接受来自您可信代理头部中的 IP 地址，使攻击者更难通过伪造头部绕过速率限制或其他基于 IP 的安全措施。

受信任代理头部

如果您的应用运行在反向代理或负载均衡器之后，Better Auth 可以从入站请求的 X-Forwarded-Host 和 X-Forwarded-Proto 头部推断基础 URL。这在应用可通过多个域名（例如 example.com 和 app.example.dev）访问，且您不想在配置中硬编码单一 baseURL 时非常实用。

启用 trustedProxyHeaders 且配置中（或环境变量中）未设置 baseURL 时，Better Auth 会在每个请求中使用转发头构建基础 URL。这意味着 OAuth 回调、邮件验证链接和重定向会自动使用用户加载应用时的域名。

{
  advanced: {
    trustedProxyHeaders: true
  }
}

启用后，基础 URL 解析优先级如下：

1. 配置中的静态 baseURL（如果设置，代理头会被忽略）
2. 环境变量（BETTER_AUTH_URL、NEXT_PUBLIC_BETTER_AUTH_URL 等）
3. 当 trustedProxyHeaders 为 true 时，使用 X-Forwarded-Host + X-Forwarded-Proto 头部
4. 请求 URL 源作为最终回退

如果您正在从多个可接受的域名提供应用，通常应：

• 省略配置中的 baseURL，使其基于代理头按请求动态推断
• 设置 trustedOrigins 为允许域名白名单（见下文）
• 保持 crossSubDomainCookies 已禁用——Cookie 默认仅限主机，每个域拥有独立会话

• 省略配置中的 baseURL，使其基于代理头按请求动态推断
• 将 trustedOrigins 设为您批准域名的白名单（见下文）
• 保持 crossSubDomainCookies 未启用——默认 Cookie 仅限于主机，每个域拥有独立会话

受信任来源

受信任来源可以防止 CSRF 攻击并阻止开放重定向。您可以在 trustedOrigins 配置选项中设置受信任来源列表。不在该列表中的请求来源会被自动阻止。

基本用法

最基本的用法是指定精确的来源，下面是一个可信来源配置的示例：

{
  trustedOrigins: [
    "https://example.com",
    "https://app.example.com",
    "http://localhost:3000"
  ]
}

通配符来源

Better Auth 支持受信任来源中的通配符模式，允许通过单条规则信任多个子域：

{
  trustedOrigins: [
    "*.example.com",             // 信任 example.com 的所有子域（任意协议）
    "https://*.example.com",     // 仅信任 example.com 的 HTTPS 子域
    "http://*.dev.example.com"   // 信任 dev.example.com 的所有 HTTP 子域
  ]
}

特定协议通配符

当使用带协议前缀（如 https://）的通配符模式时：

• 协议必须完全匹配
• 域名中的 * 可以替换为任意子域
• 使用不同协议的请求将被拒绝，即使域名匹配

协议无关通配符

当使用不带协议前缀的通配符模式（如 *.example.com）时：

• 任何协议（http、https 等）都会被接受
• 域名必须匹配通配符模式

自定义协议

受信任来源还支持移动应用和浏览器扩展的自定义协议：

{
  trustedOrigins: [
    "myapp://",                               // 移动应用协议
    "chrome-extension://YOUR_EXTENSION_ID",  // 浏览器扩展
    "exp://**",                               // 信任所有 Expo 开发 URL
    "exp://10.0.0.*:*/**"                    // 信任 IP 范围 10.0.0.x 及任意端口
  ]
}

动态来源列表

您也可以通过函数动态设置受信任来源列表：

{
  trustedOrigins: async (request) => {
    const trustedOrigins = await queryTrustedDomains();
    return trustedOrigins;
  }
}

邮箱枚举保护

Better Auth 在注册和更改邮箱端点防止邮箱枚举。当启用 requireEmailVerification 或 autoSignIn 设置为 false 时，注册端点对已注册和未注册邮箱返回相同的 200 响应，遵循 OWASP 认证最佳实践。通过模拟密码哈希处理重复注册请求以减缓时间攻击。

配置细节请参见 邮箱和密码 — 邮箱枚举保护。

安全漏洞报告

如果您发现 Better Auth 的安全漏洞，请通过 security@better-auth.com 向我们报告。我们将及时处理所有报告，并对经验证的漏洞发现予以鸣谢。