Intégration d'authentification améliorée

Vue d'ensemble

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 backend.

Cette page se concentre sur les deux modèles d'intégration qui s'y adaptent 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() En premier lieu, 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 l'ensemble de la redirection OAuth 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 soutenir :

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, Better Auth documente que vous devez fournir appBundleIdentifier afin 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

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

Better Auth documente deux modes de transfert Facebook :

• Flux de connexion limitée iOS : passez le idToken
• Flux 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 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 assistants de configuration prêts à l'emploi pour plusieurs fournisseurs. Ces assistants sont les plus proches des 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 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 ce 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'accès. 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 Social Login

Continuez avec l'intégration de Better Auth

Si vous utilisez l'intégration de Better Auth pour planifier les flux d'authentification et de comptes, 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.