Intégration d'authentification améliorée

Aperçu

Mieux Auth fonctionne bien avec @capgo/capacitor-social-login lorsque vous voulez une connexion native sur le dispositif mais que vous voulez toujours que Mieux Auth crée et gère la session sur votre serveur backend.

Cette page se concentre sur les deux modèles d'intégration qui s'intègrent le mieux :

• Transfert de jeton native pour Google, Apple et Facebook
• Mieux Auth OAuth générique pour les fournisseurs comme Auth0, Okta, Keycloak et les serveurs OIDC personnalisés

Quel modèle utiliser

Utiliser la transmission de jeton native

Utiliser SocialLogin.login() Tout d’abord, envoyez ensuite le jeton retourné à Better Auth avec authClient.signIn.social() lorsque vous utilisez :

• Google
• Apple
• Facebook

Utiliser Better Auth OAuth générique

Lorsque vous utilisez :

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• Tout fournisseur OAuth2 ou OIDC personnalisé

Cela garde l'échange de session du côté de Better Auth et évite la duplication de la logique de redirection entre deux systèmes.

Configuration du serveur Better Auth

Commencez par configurer Better Auth avec les fournisseurs sociaux que vous souhaitez supporter :

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

Remarque

Pour Apple sur iOS natif, Better Auth indique que vous devez fournir appBundleIdentifier de sorte que l'audience du jeton Apple ID corresponde à l'identifiant de bundle utilisé par iOS.

Configuration du client Better Auth

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

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

Si vous utilisez React, utilisez le package client Better Auth React que votre application utilise déjà. Le modèle de transfert de jetons reste le même.

Exemple Google

C'est la voie d'intégration la plus propre pour la connexion Google native sur les appareils mobiles :

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

Exemple d'Apple

Pour Apple, passez le même nonce à la fois à la demande de connexion native et à 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',
});

Exemple de Facebook

Les documents de Better Auth décrivent deux modes de transfert Facebook :

• iOS Limited Login : passez le idToken
• Flux d'accès-jeton : passez l'access token comme token et accessToken

Cela fonctionne avec la forme de réponse de @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',
});

Les fournisseurs OAuth génériques avec Better Auth

Pour Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID et des fournisseurs similaires, le plugin OAuth générique de Better Auth est généralement le meilleur choix plutôt que de passer des jetons à partir de SocialLogin.login({ provider: 'oauth2' }).

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

Exemples de fournisseurs pour Better Auth OAuth générique

Better Auth embarque des aides pré-configurées pour plusieurs fournisseurs. Ces sont les plus proches correspondances aux exemples de fournisseurs supplémentaires que vous voyez dans les documents du 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 avec une configuration OAuth générique manuelle

GitHub n'a pas d'assistant d'authentification Better Auth sur la page OAuth générique, utilisez donc une configuration manuelle :

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

Remarques et avertissements

1. Utiliser le mode en ligne de Google Better Auth a besoin de idToken, donc google.mode: 'offline' n'est pas le bon choix pour cette flux de transfert de main.

2. Reprendre la valeur nonce d'Apple Générer une fois, l'envoyer à Apple native login, puis envoyer la même valeur à Better Auth.

3. Gérer Facebook différemment en fonction de la plateforme Le login limité sur iOS vous donne un jeton d'ID. D'autres flux peuvent ne donner que des jetons d'accès.

4. Ne mêlez pas les flux OAuth génériques à moins d'avoir une raison Si Better Auth possède la configuration du fournisseur OAuth, laissez Better Auth posséder le flux de redirection aussi.

Lire plus loin

• Documentation du fournisseur Google de Better Auth
• Méthode d'authentification Apple meilleure documentation
• Méthode d'authentification Facebook meilleure documentation
• Méthode d'authentification OAuth générique meilleure documentation
• Fournisseurs de connexion sociale OAuth2 et OIDC

Continuez de l'intégration de l'authentification meilleure

Si vous utilisez Intégration de l'authentification meilleure pour planifier les flux d'authentification et de compte, connectez-la avec Utilisation de @capgo/capacitor-connexion sociale pour la capacité native dans Utilisation de @capgo/capacitor-connexion sociale, Utilisation de @capgo/capacitor-connexion sociale Détails d'implémentation dans @capgo/capacitor-connexion-à-un-compte-social, @capgo/capacitor-passkey Détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-authentification-biometrique-native Détails d'implémentation dans @capgo/capacitor-authentification-biometrique-native, et Authentification à deux facteurs Détails d'implémentation dans Authentification à deux facteurs.