Bessere Authentifizierungsintegration

Übersicht

Better Auth funktioniert gut mit @capgo/capacitor-social-login Wenn Sie native Anmeldung auf dem Gerät möchten, aber dennoch möchten, dass Better Auth die Sitzung auf Ihrem Backend erstellt und verwaltet.

Diese Seite konzentriert sich auf die zwei Integrationsschemata, die am besten passen:

• Native Token-Übergabe für Google, Apple und Facebook
• Bessere Authentifizierung Allgemeine OAuth für Anbieter wie Auth0, Okta, Keycloak und benutzerdefinierte OIDC-Server

Welche Muster verwenden

Native Token-Übergabe verwenden

Verwenden Sie SocialLogin.login() erst, dann senden Sie das zurückgegebene Token an Better Auth mit authClient.signIn.social() bei Verwendung von:

• Google
• Apple
• Facebook

Verwenden Sie Better Auth Generic OAuth

Lassen Sie Better Auth den gesamten OAuth-Redirect-Fluss übernehmen, wenn Sie verwenden:

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• Jeder benutzerdefinierte OAuth2- oder OIDC-Anbieter

Das hält die Sitzungsübergabe auf der Better Auth-Seite und vermeidet die Duplizierung der Redirect-Logik zwischen zwei Systemen.

Better Auth-Server-Einstellungen

Beginnen Sie mit der Konfiguration von Better Auth mit den sozialen Providern, die Sie unterstützen möchten:

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

Hinweis

Für Apple auf nativem iOS dokumentiert Better Auth, dass Sie so appBundleIdentifier den Zielgruppe für den Apple ID-Token so einrichten sollten, dass sie dem Bundle-Bezeichner entspricht, der von iOS verwendet wird.

Better Auth-Kundenkonfiguration

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

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

Wenn Sie React verwenden, verwenden Sie das Better Auth-React-Kundenpaket, das Ihre App bereits verwendet. Der Token-Übergabepattern bleibt gleich.

Google-Beispiel

Dies ist der sauberste Integrationsweg für native mobile Google-Anmeldung:

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-Beispiel

Für Apple muss der gleiche Wert für die nicht widerrufliche Zusage sowohl für die native Anmeldeanfrage als auch für Better Auth übergeben werden:

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-Beispiel

Better Auth dokumentiert zwei Facebook-Handover-Modi:

• iOS Limited Login: übergeben Sie den idToken
• Zugriffstoken-Fluss: übergeben Sie den Zugriffstoken sowohl als token und accessToken

Dies funktioniert mit der Antwortform von @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',
});

Allgemeine OAuth-Anbieter mit Better Auth

Für Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID und ähnliche Anbieter ist der Generic OAuth-Plugin von Better Auth in der Regel besser geeignet als das Weitergeben von Tokens von SocialLogin.login({ provider: 'oauth2' }).

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-Klient

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

Beispielanbieter für Better Auth Generic OAuth

Better Auth liefert vorinstallierte Hilfsfunktionen für mehrere Anbieter. Diese sind die genaueste Übereinstimmung mit den zusätzlichen Beispielanbietern, die Sie in den Dokumenten der social-login-Plugin-Beispiele sehen.

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

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 mit manueller Generic OAuth-Konfiguration

GitHub hat auf der Generic OAuth-Seite keinen Better Auth-Helfer, daher wird manuelle Konfiguration verwendet:

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

Hinweise und Einschränkungen

1. Verwenden Sie den Google-Online-Modus Better Auth benötigt das idToken, also google.mode: 'offline' ist nicht der richtige Fit für diesen Handover-Flow.

2. Wiederholen Sie den Apple-Nonce Erstellen Sie ihn einmal, senden Sie ihn an Apple Native Login, dann senden Sie denselben Wert an Better Auth.

3. Behandeln Sie Facebook unterschiedlich je nach Plattform Limited Login auf iOS gibt Ihnen einen ID-Token. Andere Flüsse mögen nur einen Zugriffstoken geben.

4. Mischen Sie keine allgemeinen OAuth-Flüsse, es sei denn Sie haben einen Grund Wenn Better Auth die OAuth-Anbieterkonfiguration besitzt, übernehmen Sie auch den Redirect-Flow.

Weitere Informationen

• Dokumentation des Google-Anbieters von Better Auth
• Dokumentation des Apple-Anbieters von Better Auth
• Dokumentation des Facebook-Anbieters von Better Auth
• Dokumentation des allgemeinen OAuth-Plugins von Better Auth
• Soziale Anmeldung: OAuth2- und OIDC-Anbieter

Weitermachen von der Integration von Better Auth

Wenn Sie die Verwendung von Better Auth Integration zum Planen der Authentifizierung und der Kontenflüsse verbinden, verbinden Sie es mit Verwendung von @capgo/capacitor-soziale-Anmeldung Für die native Fähigkeit in @capgo/capacitor-social-login, @capgo/capacitor-social-login Für die Implementierungsdetail in @capgo/capacitor-social-login, @capgo/capacitor-passkey Für die Implementierungsdetail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric Für die Implementierungsdetail in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung Für die Implementierungsdetail in Zwei-Faktor-Authentifizierung.