Better Auth 1.3

支持 SAML 的单点登录（SSO）、多团队支持、组织额外字段、性能提升等。

Better Auth 1.3 发布

我们很高兴宣布发布 Better Auth 1.3 版本。本次发布包含了许多新功能和改进。

升级请运行：

npm install better-auth@1.3

🚀 亮点

单点登录插件（SSO Plugin）

SSO 插件已拆分为独立包，现在支持 OIDC 和 SAML 2.0。

👉 阅读 SSO 文档

auth.ts

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

export const auth = betterAuth({
  plugins: [
    sso({
      oidc: {
        clientId: process.env.OIDC_CLIENT_ID!,
        clientSecret: process.env.OIDC_CLIENT_SECRET!,
      },
      saml: {
        entryPoint: "https://example.com/saml",
        issuer: "better-auth-example",
        certificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
      },
      providersLimit: async (user) => {
        const plan = await getUserPlan(user);
        return plan.name === "pro" ? 10 : 1;
      },
    }),
  ],
});

OIDC 和 MCP 插件 — 现已稳定

OIDC 和 MCP 插件均已达到生产就绪状态。

✅ 功能：

在发现和令牌端点支持刷新令牌
公共客户端支持 JWKs 和 PKCE
可信客户端
加密且哈希的客户端密钥

👉 阅读 OIDC 文档 👉 阅读 MCP 文档

auth.ts

import { mcp } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    mcp({
      loginPage: "/login",
    }),
  ],
});

Stripe 插件现已生产就绪

Stripe 插件现已稳定，基于使用量的计费很快上线。

👉 阅读 Stripe 文档

auth.ts

import { betterAuth } from "better-auth";
import { stripe } from "@better-auth/stripe";

export const auth = betterAuth({
  plugins: [
    stripe({
      // ...
    }),
  ],
});

SIWE 插件

原生支持 以太坊登录（Sign‑In with Ethereum）。

👉 阅读 SIWE 文档

auth.ts

import { siwe } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    siwe(),
  ],
});

新增社交登录提供者

新增了 Notion、Slack、Linear 和 Faceit 提供者。

auth.ts

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  socialProviders: {
    notion: { /* ... */ },
    slack: { /* ... */ },
    linear: { /* ... */ },
    faceit: { /* ... */ },
  },
});

提供用于处理 SvelteKit 服务端操作中 Cookie 的工具。

重大更改：building 和 getRequestEvent 现在必须作为参数传入。

auth.ts

import { betterAuth } from "better-auth";
import { sveltekitCookies } from "better-auth/svelte-kit";
import { getRequestEvent } from "$app/server";

export const auth = betterAuth({
  plugins: [sveltekitCookies(getRequestEvent)],
});

登录时的邮箱验证

auth.ts

export const auth = betterAuth({
  emailVerification: {
    sendOnSignIn: true, // 如果用户未验证，在登录时发送验证邮件
  },
});

多团队支持

组织插件现在支持成员属于多个团队。

重大更改： member 表中移除了 teamId 字段，新增了 teamMembers 表。

auth.ts

export const auth = betterAuth({
  plugins: [
    organization({
      // ...
    }),
  ],
});

auth-client.ts

import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/client/plugins";
import { auth } from "./auth";

export const authClient = createAuthClient({
  // 传入 auth 实例以推断额外字段
  plugins: [organizationClient({ $inferAuth: {} as typeof auth })], 
});

组织额外字段

可为 organization、member 和 invitation 模型添加自定义字段。

auth.ts

export const auth = betterAuth({
  plugins: [
    organization({
      schema: {
        organization: { additionalFields: { /* ... */ } },
        member: { additionalFields: { /* ... */ } },
        invitation: { additionalFields: { /* ... */ } },
      },
    }),
  ],
});

其他新增选项：

maximumMembersPerTeam — 设置团队成员上限
listUserInvitations — 列出用户的所有邀请

通用 OAuth 改进

新增支持额外令牌 URL 参数
OAuth 令牌加密选项

auth.ts

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      // ...
    }),
  ],
});

API 密钥

新增 requireName 选项，用于创建密钥时必须填写名称
verifyKey 现在支持异步函数

用户名

可检查用户名可用性
支持自定义规范化处理

✨ 更多功能

迁移到 Zod 4，提升类型安全和性能
CLI 支持自定义适配器的 createSchema
inferAuth 工具支持从客户端推断类型
改进文档，添加 auth 和 authClient 示例
signUp 支持 rememberMe
新增 afterEmailVerification 钩子
正确支持 freshAge 和自定义 errorURL
OAuth2 令牌现包含 refresh_token_expires_in

🐛 修复与改进

插件

Expo：修复类型路径导入
SSO：修复 SAML 重定向及类型检查
Dropbox：支持令牌访问类型
Stripe：
- 阻止重复客户
- 允许升级未完成订阅
管理后台：
- 修复钩子中缺失的 ctx
- 删除无效用户 ID 时返回正确错误

OAuth 与提供者

修复重复注册 OAuth 问题
改进 Google/Microsoft 的权限处理
修复通用 OAuth 中的错误 URL 格式
Facebook：改进受限令牌 JWT 的检测
Twitter：改进邮箱验证逻辑

核心认证

排除当前用户进行用户名唯一性检查
signInUsername 支持 callbackURL
允许无邮箱账号关联
修复 /get-session 响应中缺失的 null 类型
全局 onSuccess 钩子正常工作
JWT：支持 JWKS 中的备选算法
origin-check支持通配符可信源

CLI、数据库与适配器

CLI：改进 Drizzle 架构格式化
MongoAdapter：支持 create-adapter
模式生成尊重 useNumberId
Postgres：改进 varchar 规范化及类型比较
Drizzle CLI：启用 useNumberId 时使用 serial 作为主键

邮件与 OTP

OTP 现已加密
修复 onEmailVerification 不触发问题
关闭注册时报正确错误
手机号重置清理验证值

双因素认证

修复默认 OTP 周期
URI 生成无须启用 2FA
修复 OTP URI 分隔符不匹配

杂项

未找到成员时删除组织
API 密钥限流返回正确错误码
OpenAPI 展示额外字段
修复 MySQL 外键约束生成
多项账号关联改进
OIDC offline_access 不再强制 prompt=consent
修复令牌校验时的错误 base64 编码

大量改进使体验更流畅、更快速、更可靠。 👉 查看完整变更日志