Cookies

Cookies 用于存储数据，如会话令牌、会话数据、OAuth 状态等。所有 Cookies 都使用在身份验证选项中提供的 secret 密钥或 BETTER_AUTH_SECRET 环境变量进行签名。

【Cookies are used to store data such as session tokens, session data, OAuth state, and more. All cookies are signed using the secret key provided in the auth options or the BETTER_AUTH_SECRET environment variable.】

【Cookie Prefix】

默认情况下，Better Auth 的 cookie 使用格式 ${prefix}.${cookie_name}。默认前缀是 "better-auth"。你可以通过在身份验证选项的 advanced 对象中设置 cookiePrefix 来更改前缀。

【By default, Better Auth cookies follow the format ${prefix}.${cookie_name}. The default prefix is "better-auth". You can change the prefix by setting cookiePrefix in the advanced object of the auth options.】

auth.ts
import { betterAuth } from "better-auth"

export const auth = betterAuth({
    advanced: {
        cookiePrefix: "my-app"
    }
})

自定义曲奇

【Custom Cookies】

当服务器处于生产模式时，所有 cookie 都是 httpOnly 和 secure 的。

【All cookies are httpOnly and secure when the server is running in production mode.】

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

【If you want to set custom cookie names and attributes, you can do so by setting cookieOptions in the advanced object of the auth options.】

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

【By default, Better Auth uses the following cookies:】

  • session_token 用于存储会话令牌
  • 如果启用了 cookie 缓存，则使用 session_data 存储会话数据
  • dont_remember 在 rememberMe 被禁用时不存储标志

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

【Plugins may also use cookies to store data. For example, the Two Factor Authentication plugin uses the two_factor cookie to store the two-factor authentication state.】

auth.ts
import { betterAuth } from "better-auth"

export const auth = betterAuth({
    advanced: {
        cookies: {
            session_token: {
                name: "custom_session_token",
                attributes: {
                    // Set custom cookie attributes
                }
            },
        }
    }
})

跨子域 Cookie

【Cross Subdomain Cookies】

有时你可能需要在子域之间共享 Cookie。例如，如果你在 auth.example.com 上进行了身份验证，你可能还希望在 app.example.com 上访问相同的会话。

【Sometimes you may need to share cookies across subdomains. For example, if you authenticate on auth.example.com, you may also want to access the same session on app.example.com.】

domain 属性控制哪些域可以访问 cookie。将其设置为根域（例如 example.com）可以让所有子域都能访问该 cookie。为保证安全，请遵循以下指南：

  1. 只有在必要时才启用跨子域名的 Cookie
  2. 将域设置为所需的最具体范围（例如使用 app.example.com 而不是 .example.com）
  3. 要小心不受信任的子域，它们可能会访问这些 Cookie
  4. 考虑为不受信任的服务使用不同的域名（例如 status.company.com 与 app.company.com）
auth.ts
import { betterAuth } from "better-auth"

export const auth = betterAuth({
    advanced: {
        crossSubDomainCookies: {
            enabled: true,
            domain: "app.example.com", // your domain
        },
    },
    trustedOrigins: [
        'https://example.com',
        'https://app1.example.com',
        'https://app2.example.com',
    ],
})

安全 Cookie

【Secure Cookies】

默认情况下，只有当服务器处于生产模式时，Cookie 才是安全的。你可以通过在身份验证选项的 advanced 对象中将 useSecureCookies 设置为 true，强制 Cookie 始终保持安全。

【By default, cookies are secure only when the server is running in production mode. You can force cookies to be always secure by setting useSecureCookies to true in the advanced object in the auth options.】

auth.ts
import { betterAuth } from "better-auth"

export const auth = betterAuth({
    advanced: {
        useSecureCookies: true
    }
})
Edit on GitHub

Previous Page

客户端

Next Page

数据库

On this page