安全性

本页面包含有关 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 流程完成后，这些值会从数据库中移除。

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

对于跨子域 Cookie，您可以在配置中设置 crossSubDomainCookies 选项。该选项允许 Cookie 在子域之间共享，从而实现跨多个子域的无缝身份验证。

您可以自定义 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 的安全措施。

重要提示：设置自定义 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 向我们报告。我们会及时处理所有报告，并对经过验证的发现给予致谢。

Edit on GitHub

Previous Page

资源

Next Page

遥测

On this page