Cookies

Cookies用于存储会话令牌、OAuth 状态等数据。所有的 cookies 都使用认证选项中提供的 secret 密钥进行签名。

Better Auth 的 cookies 默认遵循 ${prefix}.${cookie_name} 格式。前缀默认为 "better-auth"。你可以通过在认证选项的 advanced 对象中设置 cookiePrefix 来更改前缀。

auth.ts
import { betterAuth } from "better-auth"
 
export const auth = betterAuth({
    advanced: {
        cookiePrefix: "my-app"
    }
})

自定义 Cookies

在生产环境下，所有 cookies 都设置为 httpOnly 和 secure。

如果你想设置自定义的 cookie 名称和属性，可以通过在认证选项的 advanced 对象中设置 cookieOptions 来实现。

默认情况下，Better Auth 使用以下 cookies：

  • session_token 用于存储会话令牌
  • session_data 用于在启用 cookie 缓存时存储会话数据
  • dont_remember 用于在禁用"记住我"功能时存储 dont_remember 标志

插件也可能使用 cookies 来存储数据。例如，双因素认证插件使用 two_factor cookie 来存储双因素认证状态。

auth.ts
import { betterAuth } from "better-auth"
 
export const auth = betterAuth({
    advanced: {
        cookies: {
            session_token: {
                name: "custom_session_token",
                attributes: {
                    // 设置自定义 cookie 属性
                }
            },
        }
    }
})

跨子域名 Cookies

有时你可能需要在子域名之间共享 cookies。例如，如果你有 app.example.com 和 example.com，当你在 example.com 上进行认证时，你可能希望在 app.example.com 上访问相同的会话。

默认情况下，cookies 不会在子域名之间共享。但是，如果你需要在不同子域名之间访问相同的会话，你可以通过在认证选项的 advanced 对象中配置 crossSubDomainCookies 和 defaultCookieAttributes 来启用跨子域名 cookies。

domain 属性前面的点号可以扩大 cookie 的作用范围，使其超出你的主域名，从而在所有子域名中都可以访问。
auth.ts
import { betterAuth } from "better-auth"
 
export const auth = betterAuth({
    advanced: {
        crossSubDomainCookies: {
            enabled: true,
            domain: ".example.com", // 带前导点号的域名
        },
        defaultCookieAttributes: {
            secure: true,
            httpOnly: true,
            sameSite: "none",  // 允许在子域名之间进行基于 CORS 的 cookie 共享
            partitioned: true, // 新的浏览器标准将要求外部 cookies 必须设置此项
        },
    },
    trustedOrigins: [
        'https://example.com',
        'https://app1.example.com',
        'https://app2.example.com',
    ],
})
将 cookie 的 sameSite 属性设置为 none 会使你容易受到 CSRF 攻击。为了降低风险，请使用授权源数组配置 trustedOrigins。

安全 Cookies

默认情况下，cookies只在生产环境下是安全的（使用httpOnly 和 secure）。你可以通过在认证选项的 advanced 对象中将 useSecureCookies 设置为 true 来强制 cookies 始终保持安全。

auth.ts
import { betterAuth } from "better-auth"
 
export const auth = betterAuth({
    advanced: {
        useSecureCookies: true
    }
})

客户端库

Better Auth 的身份认证客户端库

数据库

了解如何在Better Auth中使用数据库

On this page