L'intégration d'authentification améliorée

Présentation

Better Auth fonctionne bien avec @capgo/capacitor-social-login Lorsque vous souhaitez une connexion native sur le dispositif mais que vous voulez toujours que Better 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 :

• Transmission de jeton native pour Google, Apple et Facebook
• Authentification OAuth générique de Better Auth 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() En premier lieu, envoyez ensuite le jeton retourné à Better Auth avec authClient.signIn.social() lorsque vous utilisez :

• Google
• Apple
• Facebook

Utiliser Better Auth OAuth générique

Utilisez Better Auth pour contrôler l'ensemble de la redirection OAuth lors de l'utilisation de :

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

Cela garde l'échange de session côté 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'],
});

Note

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

Configuration de l'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 jeton reste le même.

Exemple Google

C'est la voie d'intégration la plus propre pour le signe-in mobile Google natif :

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 la 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 la idToken
• Flux d'accès-jeton : passez le jeton d'accès en tant que 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',
});

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 fournit des assistants pré-configurés pour plusieurs fournisseurs. Ces assistants sont les plus proches de l'exemple de fournisseur supplémentaire que vous voyez dans les documents du plugin de connexion 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 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 ce flux de transfert de main.

2. Réutilisez la valeur nonce d'Apple Générez-la une fois, envoyez-la à la connexion native d'Apple, puis envoyez la même valeur à Better Auth.

3. Traitez Facebook différemment en fonction de la plateforme Limited Login sur iOS vous donne un jeton d'ID. D'autres flux peuvent ne vous donner qu'un jeton d'accès.

4. N'associez pas les flux OAuth génériques à moins d'avoir une raison Si Better Auth gère la configuration du fournisseur OAuth, laissez Better Auth gérer le flux de redirection aussi.

Lecture complémentaire

• 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 Utilisez @capgo/capacitor-connexion sociale pour la capacité native dans Utilisez @capgo/capacitor-connexion sociale, Utilisez @capgo/capacitor-connexion sociale pour les détails d'implémentation dans @capgo/capacitor-login-social, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-biométrique-natif pour les détails d'implémentation dans @capgo/capacitor-biométrique-natif, et Authentification à deux facteurs pour les détails d'implémentation dans Authentification à deux facteurs.