OAuth

Better Auth 内置支持OAuth 2.0 和OpenID Connect。这允许你通过流行的OAuth提供商（如 Google、Facebook、GitHub 等）对用户进行身份验证。

如果你的目标提供商官方目前不支持，你可以使用通用OAuth插件进行自定义集成。

配置社交提供商

要启用社交提供商，你需要提供该提供商的 clientId 和 clientSecret。

以下是如何配置 Google 作为提供商的示例：

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
  // 其他配置...
  socialProviders: {
    google: {
      clientId: "YOUR_GOOGLE_CLIENT_ID",
      clientSecret: "YOUR_GOOGLE_CLIENT_SECRET",
    },
  },
});

其他提供商配置

scope 访问请求的范围。例如，email 或 profile。

redirectURI 提供商的自定义重定向 URI。默认情况下，它使用 /api/auth/callback/${providerName}。

disableImplicitSignUp: 禁用隐式注册。为了注册用户，在登录时需要将 requestSignUp 设置为 true。

disableSignUp: 禁用新用户注册。

disableIdTokenSignIn: 禁用使用 ID token 进行登录。默认情况下，某些提供商（如 Google 和 Apple）启用此功能。

verifyIdToken 用于验证 ID token 的自定义函数。

getUserInfo 用于从提供商获取用户信息的自定义函数。给定提供商返回的 token，此函数应返回用户信息。

overrideUserInfoOnSignIn: 一个布尔值，确定在登录时是否覆盖数据库中的用户信息。默认情况下，它设置为 false，意味着在登录期间不会覆盖用户信息。如果你希望每次用户登录时都更新用户信息，请将其设置为 true。

refreshAccessToken: 用于刷新 token 的自定义函数。此功能仅支持内置的社交提供商（Google、Facebook、GitHub 等），目前不支持通过通用 OAuth 插件配置的自定义 OAuth 提供商。对于内置提供商，如果需要，你可以提供自定义函数来刷新 token。

mapProfileToUser 用于将提供商返回的用户配置文件映射到数据库中用户对象的自定义函数。

如果你有想要从提供商的配置文件中填充的用户对象的其他字段，或者如果你想更改默认的用户对象映射方式，这很有用。

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
  // 其他配置...
  socialProviders: {
    google: {
      clientId: "YOUR_GOOGLE_CLIENT_ID",
      clientSecret: "YOUR_GOOGLE_CLIENT_SECRET",
      mapProfileToUser: (profile) => {
        return {
          firstName: profile.given_name,
          lastName: profile.family_name,
        };
      },
    },
  },
});

Better Auth 中的 OAuth 工作原理

以下是用户选择提供商进行身份验证时发生的情况：

1. 配置检查： 确保必要的提供商详细信息（如 client ID、secret）已配置。
2. 状态生成： 生成状态 token 并保存在数据库中，用于 CSRF 保护。
3. PKCE 支持： 如果适用，创建 PKCE 代码挑战和验证器以进行安全交换。
4. 授权 URL 构建： 使用 client ID、重定向 URI、状态等参数构建提供商的授权 URL。回调 URL 通常遵循模式 /api/auth/callback/${providerName}。
5. 用户重定向：
   • 如果启用了重定向，用户将被重定向到提供商的登录页面。
   • 如果禁用了重定向，则返回授权 URL 供客户端处理重定向。

登录后流程

用户完成登录过程后，提供商将他们重定向回带有代码和状态的回调 URL。Better Auth 处理其余部分：

1. Token 交换： 将代码交换为访问 token 和用户信息。
2. 用户处理：
   • 如果用户不存在，则创建新账户。
   • 如果用户存在，则登录。
   • 如果用户在多个提供商之间拥有多个账户，Better Auth 会根据你的配置链接它们。了解更多关于账户链接的信息。
3. 会话创建： 为用户创建新会话。
4. 重定向： 用户被重定向到初始请求期间指定的 URL 或 /。

如果在过程中发生任何错误，Better Auth 会处理它并将用户重定向到错误 URL（如果提供）或 callbackURL。并在查询字符串中包含错误消息 ?error=...。