Integrazione di Better Auth

Panoramica

Better Auth funziona bene con @capgo/capacitor-social-login quando desideri l'accesso nativo al dispositivo ma vuoi ancora che Better Auth crei e gestisca la sessione sul tuo backend.

Questa pagina si concentra sui due modelli di integrazione che si adattano meglio:

• Token di proprietà nativa per Google, Apple e Facebook
• Autenticazione generica OAuth per provider come Auth0, Okta, Keycloak e server OIDC personalizzati

Qual è il pattern da utilizzare

Usa il token di proprietà nativa

Usa SocialLogin.login() prima, poi invia il token restituito a Better Auth con authClient.signIn.social() quando si utilizza:

• Google
• Apple
• Facebook

Usa Better Auth Generic OAuth

Lascia a Better Auth il controllo completo del flusso di redirect OAuth quando si utilizza:

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• Qualsiasi provider OAuth2 o OIDC personalizzato

Che mantiene l'interscambio di sessione sul lato di Better Auth e evita la duplicazione della logica di redirect tra due sistemi.

Configurazione del server Better Auth

Configura Better Auth con i provider social che desideri supportare:

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

Nota

Per Apple su iOS nativo, Better Auth documenta che dovresti fornire appBundleIdentifier così che l'audience del token Apple ID corrisponda all'identificatore del pacchetto utilizzato da iOS.

Configurazione del client Better Auth

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

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

Se utilizzi React, utilizza il pacchetto client Better Auth React che il tuo app già utilizza. Il pattern di passaggio del token rimane lo stesso.

Esempio di Google

Ecco il percorso di integrazione più pulito per l'accesso Google nativo su 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',
});

Esempio Apple

Per Apple, passa lo stesso nonce sia alla richiesta di accesso nativo che a 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',
});

Esempio Facebook

I documenti di Better Auth descrivono due modi di Facebook per il passaggio di mano:

• IOS Limited Login: passa il idToken
• Flusso di accesso-token: passa il token di accesso sia come token e accessToken

Funziona con la forma della risposta da @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',
});

Fornitori OAuth generici con Better Auth

Per Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID e fornitori simili, il plugin OAuth generico di Better Auth è spesso la scelta migliore rispetto a passare i token da SocialLogin.login({ provider: 'oauth2' }).

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

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

Esempi di provider per OAuth generico di Better Auth

Better Auth fornisce aiuti preconfigurati per diversi provider. Questi sono il miglior match per gli esempi di provider aggiuntivi che si trovano nelle documentazioni del plugin social-login.

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 con configurazione OAuth generica manuale

GitHub non dispone di un aiuto Better Auth sulla pagina OAuth generica, quindi utilizza la configurazione manuale:

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

Note e avvertenze

1. Usa il modo online di Google Better Auth ha bisogno del idToken, quindi google.mode: 'offline' non è il fit giusto per questo flusso di handoff.

2. Ripeti il nonce di Apple Generalo una volta, invialo a Apple native login, poi invia lo stesso valore a Better Auth.

3. Tratta Facebook in modo diverso a seconda della piattaforma Login limitato su iOS ti dà un token di ID. Altri flussi possono fornirti solo un token di accesso.

4. Non mescolare i flussi OAuth generici a meno che non hai una ragione Se Better Auth gestisce la configurazione del provider OAuth, lascia che Better Auth gestisca anche il flusso di reindirizzamento.

Ulteriori letture

• Documentazione del provider Google di Better Auth
• Documentazione del provider Apple di Better Auth
• Documentazione del provider Facebook di Better Auth
• Documentazione del plugin OAuth generico di Better Auth
• Fornitori OAuth2 e OIDC di Social Login

Continua con l'integrazione di Better Auth

Se stai utilizzando L'integrazione di Better Auth per pianificare l'autenticazione e le flussi di account, connettilo con Utilizza @capgo/capacitor-social-login per la capacità nativa in Utilizzare @capgo/capacitor-login sociale, @capgo/capacitor-login sociale per il dettaglio di implementazione in @capgo/capacitor-login sociale, @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-autenticazione biometrica nativa per il dettaglio di implementazione in @capgo/capacitor-autenticazione biometrica nativa, e Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori.