更好的认证集成

GitHub

概述

Better Auth 与 @capgo/capacitor-social-login 当您希望在设备上实现原生登录，但仍希望 Better Auth 在后端创建和管理会话时，Better Auth 就会发挥作用。

本页面重点介绍以下两种最佳集成模式：

原生令牌传递（Google、Apple 和 Facebook）
Better Auth 通用 OAuth（Auth0、Okta、Keycloak 和自定义 OIDC 服务器）

当您想知道使用哪种模式时

使用原生令牌传递

使用 SocialLogin.login() 首先，然后将返回的令牌发送到Better Auth中 authClient.signIn.social() 当您使用：

Google
Apple
Facebook

使用Better Auth Generic OAuth

当您使用时，让Better Auth拥有完整的OAuth重定向流：

Auth0
Okta
Keycloak
GitHub
OneLogin
任何自定义 OAuth2 或 OIDC 提供商

保持会话交换在 Better Auth 方面，并避免在两个系统之间重复重定向逻辑。

Better Auth 服务器设置

首先配置 Better Auth 以支持您要支持的社交提供商：

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
  baseURL: process.env.BETTER_AUTH_URL,
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID as string,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET as string,
    },
    apple: {
      clientId: process.env.APPLE_CLIENT_ID as string,
      clientSecret: process.env.APPLE_CLIENT_SECRET as string,
      appBundleIdentifier: process.env.APPLE_APP_BUNDLE_IDENTIFIER as string,
    },
    facebook: {
      clientId: process.env.FACEBOOK_CLIENT_ID as string,
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET as string,
    },
  },
  trustedOrigins: ['https://appleid.apple.com'],
});

Better Auth 客户端设置

import { createAuthClient } from 'better-auth/client';

export const authClient = createAuthClient({
  baseURL: 'https://auth.example.com',
});

如果您使用 React，则使用 Better Auth React 客户端包中的应用程序。令牌传递模式保持不变。

Google 示例

这是原生移动 Google 登录的最干净的集成路径：

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const googleResult = await SocialLogin.login({
  provider: 'google',
  options: {
    scopes: ['profile', 'email'],
  },
});

if (googleResult.result.responseType !== 'online' || !googleResult.result.idToken) {
  throw new Error('Google online mode with idToken is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'google',
  idToken: {
    token: googleResult.result.idToken,
    accessToken: googleResult.result.accessToken?.token,
  },
  callbackURL: '/dashboard',
});

Apple 示例

对于 Apple，向两者传递相同的 nonce：native 登录请求和 Better Auth：

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const nonce = crypto.randomUUID();

const appleResult = await SocialLogin.login({
  provider: 'apple',
  options: {
    scopes: ['email', 'name'],
    nonce,
  },
});

if (!appleResult.result.idToken) {
  throw new Error('Apple idToken is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'apple',
  idToken: {
    token: appleResult.result.idToken,
    nonce,
    accessToken: appleResult.result.accessToken?.token,
  },
  callbackURL: '/dashboard',
});

Facebook 示例

Better Auth 文档记录了两种 Facebook 手动模式：

iOS 有限登录：传递 idToken
访问令牌流：将访问令牌作为 token 和 accessToken

这与 @capgo/capacitor-social-login:

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const facebookResult = await SocialLogin.login({
  provider: 'facebook',
  options: {
    permissions: ['email', 'public_profile'],
  },
});

const betterAuthToken = facebookResult.result.idToken
  ? {
      token: facebookResult.result.idToken,
    }
  : facebookResult.result.accessToken?.token
    ? {
        token: facebookResult.result.accessToken.token,
        accessToken: facebookResult.result.accessToken.token,
      }
    : null;

if (!betterAuthToken) {
  throw new Error('Facebook idToken or access token is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'facebook',
  idToken: betterAuthToken,
  callbackURL: '/dashboard',
});

通用 OAuth 提供商与 Better Auth

对于 Auth0、Okta、Keycloak、GitHub、Microsoft Entra ID 和类似提供商，Better Auth 的 Generic OAuth 插件通常比从 SocialLogin.login({ provider: 'oauth2' }).

Better Auth 服务器

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'keycloak',
          discoveryUrl: 'https://sso.example.com/realms/mobile/.well-known/openid-configuration',
          clientId: process.env.KEYCLOAK_CLIENT_ID as string,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
        },
      ],
    }),
  ],
});

简化 OAuth 提供商与 Better Auth

import { createAuthClient } from 'better-auth/client';
import { genericOAuthClient } from 'better-auth/client/plugins';

export const authClient = createAuthClient({
  baseURL: 'https://auth.example.com',
  plugins: [genericOAuthClient()],
});

await authClient.signIn.oauth2({
  providerId: 'keycloak',
  callbackURL: '/dashboard',
});

Better Auth 提前配置了多个提供商的帮助程序。这些是与社交登录插件文档中看到的额外提供商示例最接近的匹配。

Better Auth 服务器

Better Auth 客户端

import { betterAuth } from 'better-auth';
import { auth0, genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        auth0({
          providerId: 'auth0',
          domain: 'dev-example.eu.auth0.com',
          clientId: process.env.AUTH0_CLIENT_ID as string,
          clientSecret: process.env.AUTH0_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'auth0',
  callbackURL: '/dashboard',
});

Microsoft Entra ID

import { betterAuth } from 'better-auth';
import { genericOAuth, microsoftEntraId } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        microsoftEntraId({
          providerId: 'entra',
          tenantId: 'common',
          clientId: process.env.AZURE_CLIENT_ID as string,
          clientSecret: process.env.AZURE_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'User.Read'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'entra',
  callbackURL: '/dashboard',
});

Okta

import { betterAuth } from 'better-auth';
import { genericOAuth, okta } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        okta({
          providerId: 'okta',
          issuer: 'https://dev-12345.okta.com/oauth2/default',
          clientId: process.env.OKTA_CLIENT_ID as string,
          clientSecret: process.env.OKTA_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'okta',
  callbackURL: '/dashboard',
});

Keycloak

import { betterAuth } from 'better-auth';
import { genericOAuth, keycloak } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        keycloak({
          providerId: 'keycloak',
          issuer: 'https://sso.example.com/realms/mobile',
          clientId: process.env.KEYCLOAK_CLIENT_ID as string,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'keycloak',
  callbackURL: '/dashboard',
});

GitHub 使用手动通用 OAuth 配置

GitHub 在通用 OAuth 页面上没有 Better Auth 助手，因此使用手动配置：

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'github',
          clientId: process.env.GITHUB_CLIENT_ID as string,
          clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
          authorizationUrl: 'https://github.com/login/oauth/authorize',
          tokenUrl: 'https://github.com/login/oauth/access_token',
          userInfoUrl: 'https://api.github.com/user',
          scopes: ['read:user', 'user:email'],
          pkce: true,
        },
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'github',
  callbackURL: '/dashboard',
});

注意事项和警告

使用 Google 在线模式 Better Auth 需要 idToken, 所以 google.mode: 'offline' 不是这个手续流程的合适选择。
重新使用 Apple nonce 生成一次，发送给 Apple 原生登录，然后将相同的值发送到 Better Auth。
根据平台不同，处理 Facebook 的方式也不同 在 iOS 上，Limited Login 可以给出 ID token。其他流程可能只给出访问令牌。
除非有特殊原因，不要混合 Generic OAuth 流程 如果 Better Auth 拥有 OAuth 提供商配置，则让 Better Auth 拥有重定向流程

进一步阅读

从更好的认证集成继续

如果您正在使用 更好的认证集成 来规划认证和帐户流程，连接它使用 @capgo/capacitor-social-login 为使用 @capgo/capacitor-social-login 的原生能力使用 @capgo/capacitor-social-login 为 @capgo/capacitor-social-login 的实现细节 @capgo/capacitor-passkey 关于@capgo/capacitor-passkey的实现细节 @capgo/capacitor-native-biometric 关于@capgo/capacitor-native-biometric的实现细节，以及双因素认证关于双因素认证的实现细节