Intégration d'authentification améliorée

Vue d'ensemble

Better Auth fonctionne bien avec @capgo/capacitor-social-login Lorsque vous voulez 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'y prêtent le mieux :

• Authentification native avec Google, Apple et Facebook
• Authentification OAuth générique pour les fournisseurs comme Auth0, Okta, Keycloak et les serveurs OIDC personnalisés

Quel modèl’utiliser

Utiliser l'authentification native

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

• Google
• Apple
• Facebook

Utilisez l'authentification Better Auth OAuth générique

Laissez Better Auth gérer la redirection OAuth complète lors de l'utilisation de :

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• N'importe quel fournisseur OAuth2 ou OIDC personnalisé

Cela conserve l'échange de session sur le 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'],
});

Remarque

Pour Apple sur iOS natif, Better Auth indique que vous devez fournir appBundleIdentifier afin que l'audience du jeton Apple ID corresponde à l'identifiant de l'application 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

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

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

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

• iOS Limited Login : passez le idToken
• Flux de jeton d'accès : passez le jeton d'accès comme les deux 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 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 assistants de configuration 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 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 Better Auth sur la page de la configuration 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. Utilisez le mode en ligne Google Better Auth nécessite le idToken, donc google.mode: 'offline' n'est pas le bon choix pour cette flux de transfert de main.

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

3. Traitez différemment Facebook 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 également le flux de redirection.

Lire plus en détail

• Documentation du fournisseur Google de Better Auth
• Documentation du fournisseur Apple de Better Auth
• Documentation du fournisseur Facebook de Better Auth
• Documentation du plugin OAuth générique de Better Auth
• Fournisseurs OAuth2 et OIDC de connexion sociale

Continuez de l'intégration de Better Auth

Si vous utilisez l'intégration de Better Auth pour planifier les flux d'authentification et de compte, connectez-l’avec En utilisant @capgo/capacitor-social-login pour la capacité native dans l'utilisation de @capgo/capacitor-social-login, @capgo/capacitor-social-login pour le détail d'implémentation dans @capgo/capacitor-social-login, @capgo/capacitor-passkey pour le détail d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-native-biometric pour le détail d'implémentation dans @capgo/capacitor-native-biometric, et Authentification à deux facteurs pour le détail d'implémentation dans Authentification à deux facteurs.