Better Auth 1.7 RC

我们在 Better Auth 1.7 上投入了很多。这是一个重大版本，其中一部分意味着需要进行迁移工作。我们希望支持更广泛的登录流程，让系统更稳健，并推出那些需要结构性改动的安全修复。

以下是此版本带来的内容。

你的应用可以成为其他应用的登录提供方。 如果其他应用通过你的应用登录，Better Auth 现在可以处理更多 OAuth 和 OpenID Connect 规则。这包括 DPoP token、单点登出、强制重新登录、按 API 的 token 规则，以及更安全的 token 检查。

更多登录提供方可用。 Better Auth 现在支持此前表现不佳的登录配置：Amazon Cognito、使用证书登录的 Microsoft Entra ID、标准 OpenID 提供方，以及像 Clever 这样的学校登录提供方。

默认情况下更安全。 我们加强了此前不安全的流程。随着安全性越来越成为重点，我们宁愿披露安全漏洞并迅速修复，也不愿为了向后兼容而继续保留它们。

亮点

Better Auth 作为身份提供者

这是本次发布中最重要的部分。OAuth 提供程序从“只负责发放 token”成长为一个基于标准的授权服务器，其他应用可以通过它登录。

• 受保护资源： 将登录服务器后的每个 API 描述为独立资源，并为其设置独立的 token 生命周期、scopes 和 claims。token 会锁定到其签发的 API，不再能针对另一个 API 重放。这取代了扁平的 validAudiences 列表。
• DPoP 绑定 token： access token 会绑定到客户端持有的密钥，因此仅窃取 token 不足以调用 API。
• 单点登出： OIDC Back-Channel Logout 会告知用户通过你的提供方登录的每个应用，在用户从你的提供方登出时结束自身会话。
• 强制重新登录： 现在会遵守 max_age，而不是忽略它。
• 一致的 introspection： opaque token 会返回与 JWT 相同的 claims，并且独立的 API 服务可以 introspect 发放给另一个客户端的 token。
• 符合协议规范的 ID token： 自定义 claims 不再能覆盖 issuer、subject 和 audience 等保留的协议 claims。
• 自助服务客户端和机器客户端： 后端可以使用预共享 token，在没有登录用户的情况下完成注册；Client ID Metadata Documents（@better-auth/cimd）允许客户端通过托管 URL 标识自身，这也是 MCP 客户端无需提前注册即可连接的方式。像 Claude 和 Codex 这样的真实 MCP 客户端现在会保密其注册时使用的身份验证方法，默认保持 confidential，而不是被强制设为 public。
• OAuth 客户端的设备授权： 已注册的 CLI、智能电视和其他输入受限的客户端可以请求用户在浏览器中批准访问，然后将 device code 兑换为具有限定 scopes 且绑定资源的 OAuth token。
• 请求特定的用户详细信息： 客户端可以通过标准的 claims.userinfo 参数请求单独的用户 claims，并且该请求会成为用户 consent 的一部分。
• 扩展接口： extendOAuthProvider 允许配套插件添加 grant types、客户端身份验证方法、发现元数据和 claims，而无需修改核心代码。
• 协议一致性完善： 标准的 { error, error_description } 响应格式、凭据响应中的 no-store、ID token 中的 at_hash claim、form-encoded 请求，以及面向客户端的可选 refresh-retry 窗口。

旧的 oidcProvider 插件已被移除，它在 1.6 中已被弃用。请将 OpenID provider 配置迁移到 @better-auth/oauth-provider。

连接到更多身份提供商

OAuth 工作的另一半，是关于 Better Auth 作为接收登录的应用。

• 通用 OAuth 已重构，与内置社交提供商走同一路径，默认启用 PKCE，并通过发现机制自动进行发行者验证。你调用的 API 和回调 URL 都会改变。
• 身份令牌会一致地校验，并使用提供商发布的密钥，包括移动端和单页应用。自定义提供商从 verifyIdToken 方法迁移到 idToken 配置。
• 已授权的范围会被保留，在重新登录和令牌刷新时不会被覆盖，而 Google 的 includeGrantedScopes 现在也可以配置了（默认仍开启）。
• Google One Tap 会更严格地验证身份令牌，拒绝格式错误的令牌，并遵循 requireEmailVerification。
• 每次请求的登录选项（additionalParams）支持启用 Cognito 上游路由、Microsoft Entra ID 的 domain_hint，以及 Google 的离线或增量访问。证书和签名断言登录（clientAssertion、tokenEndpointAuth）支持 Entra ID 证书登录和通用的 private_key_jwt。
• 由提供商发起的登录 可通过 allowIdpInitiated: true 安全地重新开始，按提供商的邮箱验证（requireEmailVerification）会在邮箱验证完成前暂不建立会话，而 匿名账户关联 现在可在 Expo 和其他应用内浏览器中正常工作。

新增可用的集成

这些配置在以前是不可能实现、会出错或不安全的，现在已经可以正常工作。

使用外部提供商登录你的用户

其他应用通过你进行登录

企业级 SSO

企业 SSO、SAML 和 SCIM

• 无停机轮换 SAML 证书： 签名证书现在可以是列表，因此管理员可以在旧证书旁发布新证书。管理端点会将证书作为列表返回；如果证书位于 idpMetadata 文档中，则会省略该字段。
• 默认关闭未经请求的 SAML 登录： allowIdpInitiated 现在默认为 false，因此除非通过 allowIdpInitiated: true 选择启用，否则由提供商发起的登录会被拒绝。
• 更简单的 SAML 配置： 回调 URL 会自动派生，服务提供商元数据会自动生成，多个未使用字段会被移除，并且 Single Logout 会正确结束会话。其中一个 endpoint 路径会发生变化。
• SCIM 供应域： SCIM 不再依赖 Organization 或 SSO 插件，也永远不会将已供应的身份表示为身份验证账户。使用代码定义的连接，在请求时解析由应用拥有的连接，或选择启用插件管理的连接目录。新模型不会转换 1.6 的供应状态，因此升级需要经过审核的切换，以及完整的 User 和 Group 重新供应。

Drizzle 关系 v2

Drizzle ORM v1 现已进入候选发布版，并带来了全新的 relations API。Better Auth 通过一个新的适配器入口点支持它，因此生成的 auth 关系可以与你应用自身的关系并排使用。

import { betterAuth } from "better-auth/minimal";
import { drizzleAdapter } from "@better-auth/drizzle-adapter/relations-v2"; 
import { db } from "./db";
import * as schema from "./schema";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg", schema }),
});

22 种语言的内置 i18n

@better-auth/i18n 内置了 22 种语言的翻译，并且英文回退是固定的。将其接入即可本地化 Better Auth 面向用户的消息，而无需维护你自己的翻译表。

默认安全

• 默认不信任转发代理头： 你的应用从 Host 头读取自身地址，并忽略 x-forwarded-*，除非你通过 advanced.trustedProxyHeaders: true 显式启用。nginx、Vercel、Cloudflare 和 Netlify 等平台通常无需更改。
• 原子状态，不再有竞争条件： 数据库中的“先检查，再写入”逻辑被单个原子操作取代，因此一次性令牌不能被重复使用，团队不会超过其限额，限流在高负载下也能保持有效。自定义适配器和存储后端现在需要实现必要的方法。
• Electron 需要现代 PKCE： Electron 流程现在要求使用 S256 PKCE，并且不再信任自定义 origin 头。请同时升级客户端和服务器。
• 验证码匹配完整路径： 将诸如 /sign-in 这样的部分路径替换为 /sign-in/* 或 /sign-in/**。
• 更严格的自定义协议源： 带主机的 trustedOrigins 条目，例如 myapp://callback，现在只精确匹配该主机，不再接受 myapp://callback.attacker.tld。
• 无密码登录会清除未经证实的凭据： 当账户邮箱从未被确认时，已验证的邮箱控制权优先，因此在登录前会移除未经证实的密码以及任何其他已关联账户。
• 新身份的门禁： 新的 user.validateUserInfo 钩子可以在创建用户或链接账户之前拒绝某个身份，适用于每一种注册方式。

重要变更

重大变更

行为变化

新增内容

弃用与移除

迁移到 v1.7

由于此版本包含较大的变更，我们会先以候选发布版的形式提供，因此会有一个迁移窗口。我们会继续关注反馈，并在此基础上发布稳定版 1.7。

请从 rc 标签安装它，并对你使用的任何 @better-auth/* 包也执行同样操作：

npm install better-auth@rc

在应用 1.7 schema 之前，完成 account identities、OAuth clients、SCIM 和 Device Authorization 所需的任何手动准备工作。然后，对于内置 Kysely adapter，使用 npx auth@rc migrate；或者运行 npx auth@rc generate，并通过你的 Drizzle、Prisma 或自定义迁移流程应用生成的结果。在 1.7 稳定之前，不带范围的 npx auth 仍会解析到 1.6 CLI。有关所需顺序和详细步骤，请参阅 1.7 升级指南。

贡献者

感谢所有贡献者让本次发布成为可能！