跳过内容
Capgo - Capacitor 应用程序的实时更新 Capgo

更好的认证集成

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 Generic OAuth

使用：

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

将会话交换放在 Better Auth 一侧，避免在两个系统之间重复重定向逻辑。

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 客户端设置

Better Auth 客户端设置
import { createAuthClient } from 'better-auth/client';


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

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

Google 示例

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 示例标题

对于 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 示例

Facebook 示例标题

Better Auth 文档了两个 Facebook 传递模式：

  • iOS 有限登录：传递 idToken
  • Access-token 流：传递 access token 作为 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',
});

Generic OAuth providers with Better Auth

Section titled “Generic OAuth providers with Better Auth”

For Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID, and similar providers, Better Auth’s Generic OAuth plugin is usually the better fit than passing tokens from SocialLogin.login({ provider: 'oauth2' }).

Better Auth server

Section titled “Better Auth server”
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,
        },
      ],
    }),
  ],
});

Better Auth client

Section titled “Better Auth client”
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',
});

Provider examples for Better Auth Generic OAuth

Section titled “Provider examples for Better Auth Generic OAuth”

Better Auth ships pre-configured helpers for several providers. These are the closest match to the extra provider examples you see in the social-login plugin docs.

Auth0

Auth0
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

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

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

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 配置

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',
});

注意事项和警告

注意事项和警告

  1. 使用 Google 在线模式 Better Auth 需要 idToken, 因此 google.mode: 'offline' 不是这个手续流程的合适选择。

  2. 复用 Apple nonce 生成一次，发送给 Apple 原生登录，然后将相同的值发送给 Better Auth。

  3. 根据平台处理 Facebook 不同 iOS 的 Limited Login 给你一个 ID token。其他流程可能只给你一个访问令牌。

  4. 除非有原因，否则不要混合 Generic OAuth 流程 如果 Better Auth 拥有 OAuth 提供商配置，则让 Better Auth 拥有重定向流程

进一步阅读

标题为“进一步阅读”的部分

从更好的认证集成中继续

标题：从更好的认证集成中继续

如果您正在使用 更好的认证集成 来规划认证和帐户流程，连接它 使用 @capgo/capacitor-social-login 为在使用 @capgo/capacitor-social-login 中的原生能力 使用 @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, and Two-factor authentication for the implementation detail in Two-factor authentication.