Integrazione di Autenticazione Migliorata

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:

• Passaggio di token nativo per Google, Apple e Facebook
• Better Auth OAuth generico per provider come Auth0, Okta, Keycloak e server OIDC personalizzati

Quale modello utilizzare

Utilizza il passaggio di token nativo

Utilizza SocialLogin.login() in primo luogo, quindi invia il token restituito a Better Auth con authClient.signIn.social() quando utilizzi:

• Google
• Apple
• Facebook

Usa l'autenticazione OAuth generica di Better Auth

Lascia che Better Auth gestisca l'intero flusso di redirect OAuth quando utilizzi:

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

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

Configurazione del server Better Auth

Inizia configurando 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 in modo che l'audience del token Apple ID corrisponda all'identificatore di bundle 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 di autenticazione migliore React che il tuo'app già utilizza. Il pattern di passaggio del token rimane lo stesso.

Esempio di Google

Questo è il percorso di integrazione più pulito per l'accesso di Google nativo su dispositivi mobili:

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 di Apple

Per Apple, passa lo stesso nonce sia alla richiesta di accesso nativa che al client di autenticazione migliore:

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 di Facebook

I documenti di Better Auth descrivono due modalità di passaggio Facebook:

• iOS Limited Login: passa il idToken
• Flusso di accesso-token: passa il token di accesso come sia 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',
});

Provider OAuth generici con Better Auth

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

Server di 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 di autenticazione migliore

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 l'autenticazione migliore Generic OAuth

L'autenticazione migliore fornisce aiuti preconfigurati per diversi provider. Questi sono il miglior match per gli esempi di provider aggiuntivi che si vedono nei documenti del plugin di accesso sociale.

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 di autenticazione Better Auth sulla pagina OAuth generica, quindi utilizzare 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',
});

Nota e avvertenze

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

2. Ripristina il nonce di Apple Generalo una volta, invialo al login nativo di Apple, quindi invialo lo stesso valore a Better Auth.

3. Gestisci Facebook in modo diverso a seconda della piattaforma L'accesso limitato su iOS ti fornisce un token di ID. Altri flussi possono fornire solo un token di accesso.

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

Leggi di più

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

Continua dall'integrazione Better Auth

Se stai utilizzando Autenticazione Migliorata per pianificare l'autenticazione e le flussi di account, connettilo con Utilizza @capgo/capacitor-login-social per la capacità nativa in Utilizza @capgo/capacitor-login-social Utilizza @capgo/capacitor-login-social per il dettaglio di implementazione in @capgo/capacitor-login-social Utilizza @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey Utilizza @capgo/capacitor-biometric-nativo per il dettaglio di implementazione in @capgo/capacitor-biometric-nativo Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori.