Better Auth Integration

Übersicht

Better Auth funktioniert hervorragend mit @capgo/capacitor-social-login wenn du natives Sign-in auf dem Gerät nutzen möchtest, aber Better Auth die Session auf deinem Backend erstellen und verwalten soll.

Diese Seite konzentriert sich auf die zwei am besten geeigneten Integrationsmuster:

• Nativer Token-Handoff für Google, Apple und Facebook
• Better Auth Generic OAuth für Provider wie Auth0, Okta, Keycloak und eigene OIDC-Server

Welches Muster du nutzen solltest

Nativen Token-Handoff nutzen

Nutzt SocialLogin.login() zuerst, dann senden Sie den zurückgegebenen Token an Better Auth mit authClient.signIn.social() wenn Sie Folgendes nutzen:

• Google
• Apple
• Facebook

Better Auth Generic OAuth nutzen

Lass Better Auth den kompletten OAuth-Redirect-Flow übernehmen, wenn du Folgendes nutzt:

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

Dadurch bleibt der Session-Exchange auf der Better Auth-Seite und die Redirect-Logik muss nicht zwischen zwei Systemen dupliziert werden.

Better Auth Server-Setup

Konfiguriere Better Auth zunächst mit den Social-Providern, die du unterstützen möchtest:

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 unter nativem iOS dokumentiert Better Auth, dass du Folgendes angeben solltest: appBundleIdentifier damit die Apple ID Token Audience mit der von iOS verwendeten Bundle Identifier übereinstimmt.

Better Auth Client-Setup

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

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

Wenn du React nutzt, verwende das Better Auth React Client-Paket, das deine App bereits nutzt. Das Pattern für den Token-Handoff bleibt gleich.

Google-Beispiel

Dies ist der sauberste Integrationsweg für das native Google Sign-in auf Mobile:

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

Bei Apple übergib denselben Nonce sowohl an den nativen Login-Request als auch an 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-Beispiel

Better Auth unterstützt zwei Facebook-Handoff-Modi:

• iOS Limited Login: Übergabe des idToken
• Access-token Flow: Übergabe des Access-Tokens als token und accessToken

Dies funktioniert mit dem Response-Format 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',
});

Generic OAuth-Provider mit Better Auth

Für Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID und ähnliche Provider ist das Generic OAuth-Plugin von Better Auth meist besser geeignet als die Token-Übergabe 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 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-Beispiele für Better Auth Generic OAuth

Better Auth bringt vorkonfigurierte Helper für mehrere Provider mit. Diese entsprechen am ehesten den zusätzlichen Provider-Beispielen aus der Dokumentation des social-login Plugins.

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 bietet auf der Generic OAuth-Seite keinen Better Auth Helper an; verwende daher die manuelle Konfiguration:

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. Google im Online-Modus verwenden Better Auth benötigt den idToken, also google.mode: 'offline' nicht die richtige Wahl für diesen Handoff-Flow.

2. Apple Nonce wiederverwenden Einmal generieren, an den Apple Native Login senden und denselben Wert an Better Auth übergeben.

3. Facebook-Handling nach Plattform unterscheiden Limited Login auf iOS liefert einen ID Token. Andere Flows liefern eventuell nur einen Access Token.

4. Verwende keine generischen OAuth-Flows, sofern es keinen triftigen Grund gibt Wenn Better Auth die OAuth-Provider-Konfiguration verwaltet, sollte Better Auth auch den Redirect-Flow steuern.

Weiterlesen

• Better Auth Google Provider Docs
• Better Auth Apple Provider Docs
• Better Auth Facebook Provider Docs
• Better Auth Generic OAuth Plugin Docs
• Social Login OAuth2- und OIDC-Provider

Weiter mit der Better Auth Integration

Wenn du es nutzt Better Auth Integration Um Authentifizierungs- und Account-Flows zu planen, verbinde es mit @capgo/capacitor-social-login verwenden für die native Funktion bei der Verwendung von @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-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails zur Zwei-Faktor-Authentifizierung.