Intégration d'Auth Better

Résumé

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

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

Quel modèl’utiliser

Utiliser la transmission de jeton native

Utiliser SocialLogin.login() En premier lieu, puis envoyez ensuite le jeton retourné à Better Auth avec authClient.signIn.social() lorsque vous utilisez :

• Google
• Apple
• Facebook

Utiliser l'authentification améliorée OAuth générique

Quand vous utilisez Better Auth, laissez-le gérer la redirection OAuth complète :

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

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

Configuration de l'authentification 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 indique que vous devez fournir appBundleIdentifier L'audience du jeton Apple ID correspond à l'identifiant de bundle utilisé par iOS.

Configuration de l'authentification client Better Auth

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

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

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

exemple de Google

Cette est la voie d'intégration la plus propre pour le signe d'authentification 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 :

• Connexion limitée iOS : transmettez le idToken
• Flux de jeton d'accès : transmettez 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 fournisseurs similaires, le plugin OAuth générique de Better Auth est généralement le choix mieux adapté 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 OAuth générique de Better Auth

Better Auth embarque des assistants préconfigurés pour plusieurs fournisseurs. Ces assistants sont la meilleure correspondance 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 Better Auth sur la page Generic OAuth, 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 a besoin de idTokendonc 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 d'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 sauf si vous avez 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

• Méthode d'authentification Améliorée Google
• Méthode d'authentification Améliorée Apple
• Méthode d'authentification Améliorée Facebook
• Méthode d'authentification OAuth générique du plugin
• Fournisseurs OAuth2 et OIDC de connexion sociale

Continuez de l'intégration d'Auth Better

Si vous utilisez L'intégration de la Méthode d'authentification Améliorée pour planifier les flux d'authentification et de compte, connectez-l’avec En utilisant @capgo/capacitor-social-login pour la capacité native dans En utilisant @capgo/capacitor-social-login, @capgo/capacitor-connexion sociale pour les détails d'implémentation dans @capgo/capacitor-connexion sociale, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-authentification native pour les détails d'implémentation dans @capgo/capacitor-authentification native, et L'authentification à deux facteurs pour les détails d'implémentation dans L'authentification à deux facteurs.