Bessere Auth-Integration

Overview

Überschrift "Übersicht" @capgo/capacitor-social-login Wenn Sie eine native Anmeldung auf dem Gerät wünschen, möchten Sie trotzdem, dass Better Auth die Sitzung auf Ihrem Backend erstellt und verwaltet.

Dieser Seite wird die zwei Integrationsmuster vorgestellt, die am besten passen.

• Nativer Token-Übergabe für Google, Apple und Facebook
• Bessere Auth Generic OAuth für Anbieter wie Auth0, Okta, Keycloak und benutzerdefinierte OIDC-Server

Welche Muster verwenden

Native Token-Übergabe verwenden

Use SocialLogin.login() erst, dann senden Sie das zurückgegebene Token an die Bessere Auth mit authClient.signIn.social() wenn Sie verwenden:

• Google
• Apple
• Facebook

Bessere Auth Generic OAuth verwenden

Lassen Sie Better Auth den gesamten OAuth-Redirect-Flow steuern, wenn Sie verwenden:

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

Dadurch bleibt die Sitzungsübergabe auf der Better Auth-Seite und es wird die Duplizierung von Redirect-Logik zwischen zwei Systemen vermieden.

Better Auth-Server-Einstellungen

Beginnen Sie mit der Konfiguration von Better Auth mit den sozialen Anbietern, 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'],
});

Anmerkung

Für Apple auf nativem iOS legt Better Auth fest, dass Sie appBundleIdentifier so die Zielgruppe für den Apple ID-Token die von iOS verwendete Bundle-Identifikationsnummer entspricht.

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 Client-Paket, das Ihre App bereits verwendet. Der Token-Übergabemuster 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 Nonce 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',
});

Oauth-Anbieter mit Better Auth

Für Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID und ähnliche Anbieter ist der Oauth-Plugin von Better Auth in der Regel besser geeignet als das Weitergeben von Token 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',
});

Beispiele für Oauth-Anbieter mit Better Auth

Better Auth liefert vor konfigurierte Hilfsfunktionen für mehrere Anbieter. Diese sind die nächste Übereinstimmung zu den zusätzlichen Anbieterbeispielen, die Sie in den Dokumenten der social-login-Plugin-Plugin 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 verfügt auf der Generic OAuth-Seite nicht über einen 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. Benutzen Sie den Google-Online-Modus Better Auth benötigt das idToken, also google.mode: 'offline' ist nicht der richtige Ansatz für diesen Handover-Flow.

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

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

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

Weitere Informationen

• Google-Anbieterdokumente von Better Auth
• Apple-Anbieterdokumente von Better Auth
• Facebook-Anbieterdokumente von Better Auth
• Dokumente zum allgemeinen OAuth-Plugin von Better Auth
• Dokumente zu OAuth2- und OIDC-Anbietern von Social Login

Fortsetzung von der Integration von Better Auth

Wenn Sie Better Auth Integration verwenden Bessere Auth-Integration um die Authentifizierung und die Kontenflüsse zu planen, verbinden Sie es mit Verwenden Sie @capgo/capacitor-social-login zum native Capability in Verwenden Sie @capgo/capacitor-social-login, @capgo/capacitor-Social-Login für die Implementierungsdetails in @capgo/capacitor-social-login @capgo/capacitor-Passkey für die Implementierungsdetails in @capgo/capacitor-passkey @capgo/capacitor-native-biometrisch für die Implementierungsdetails in @capgo/capacitor-native-biometric und Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung