Security

本页面包含 Better Auth 的安全特性信息。

密码哈希

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

会话管理

会话过期

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

会话撤销

Better Auth 允许您撤销会话以增强安全性。当会话被撤销时，用户将被注销，并且无法再访问应用程序。已登录的用户也可以撤销自己的会话，以从不同设备或浏览器注销。

有关更多详细信息，请参阅 会话管理。

CSRF 保护

Better Auth 通过验证请求中的 Origin 标头来确保 CSRF 保护。此检查确认请求源于应用程序或受信任的来源。如果请求来自不受信任的来源，则将被阻止以防止潜在的 CSRF 攻击。默认情况下，与基本 URL 匹配的来源是受信任的，但您可以在 trustedOrigins 配置选项中设置受信任来源列表。

OAuth 状态和 PKCE

为了保护 OAuth 流程，Better Auth 在数据库中存储 OAuth 状态和 PKCE（Proof Key for Code Exchange）。状态有助于防止 CSRF 攻击，而 PKCE 保护免受代码注入威胁。一旦 OAuth 过程完成，这些值将从数据库中删除。

Cookies

当基本 URL 使用 https 时，Better Auth 默认分配安全的 cookies。这些安全的 cookies 是加密的，并且仅通过安全的连接发送，从而增加额外的保护层。它们还默认设置 sameSite 属性为 lax，以防止跨站请求伪造攻击。而且启用了 httpOnly 属性，以防止客户端 JavaScript 访问 cookie。

对于跨子域 Cookies，您可以在配置中设置 crossSubDomainCookies 选项。此选项允许 Cookies 在子域之间共享，从而在多个子域之间实现无缝认证。

自定义 Cookies

您可以自定义 cookie 名称，以最小化指纹攻击的风险，并根据需要设置特定的 cookie 选项以进行额外控制。有关更多信息，请参阅 cookie 选项。

插件也可以设置自定义 cookie 选项，以符合特定的安全需求。如果您在非浏览器环境中使用 Better Auth，插件提供在这些上下文中安全管理 Cookies 的方法。

速率限制

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 的安全措施变得更加困难。

重要：设置自定义 IP 地址标头时，请确保您的代理或负载均衡器正确配置以设置此标头，并且它不能由最终用户直接设置。

受信任来源

受信任来源防止 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"    // 浏览器扩展
  ]
}
`

## 报告漏洞

如果您在 Better Auth 中发现安全漏洞，请通过 [security@better-auth.com](mailto:security@better-auth.com) 向我们报告。我们将及时处理所有报告，并为已验证的发现提供信用。