Comment vous connecter avec Auth0 à l'aide de Capacitor

Pour vous connecter avec Auth0 dans une application Capacitor, créez un Native dans Auth0, enregistrez une URL de rappel de scheme personnalisé comme com.example.app://oauth/auth0, et exécutez le flux d'autorisation OpenID Connect code avec PKCE à travers un navigateur système. Avec @capgo/capacitor-social-login C'est un. initialize appel avec vos points de terminaison Auth0 et une SocialLogin.login({ provider: 'oauth2', options: { providerId: 'auth0' } }).

ce guide couvre les paramètres du tableau de bord Auth0, le client code pour iOS, Android et web, les jetons d'accès API, les jetons de rafraîchissement, la déconnexion et les erreurs auxquelles vous vous heurerez. Il est écrit pour Capacitor 8 à partir d'octobre 2026.

Comment fonctionne le flux Auth0 dans Capacitor

Auth0 héberge la page de connexion (Universal Login). Votre application ne voit jamais le mot de passe. Le flux est :

1. L'application génère un vérificateur et un défi PKCE, puis ouvre https://YOUR_TENANT/authorize dans un navigateur sécurisé.
2. L'utilisateur se connecte (mot de passe, social, clé de passe, MFA, selon vos paramètres configurés dans Auth0).
3. Auth0 redirige vers votre URL de rappel avec un jeton __CAPGO_KEEP_0__ unique. code.
4. L'application échange le code et le vérificateur PKCE à /oauth/token pour un jeton d'ID, un jeton d'accès et, facultativement, un jeton de rafraîchissement.

Le navigateur utilisé dépend de la plateforme :

Sur Android, utilisez les onglets personnalisés. Ils partagent les cookies avec Chrome, supportent les clés de passe et les gestionnaires de mots de passe, et suivent RFC 8252 (OAuth pour les applications natives), ce que Auth0 attend.

Étape 1 : Configurez l'application Auth0

1. dans Sur la page Dans le Applications > Applications > Créer une application.
2. Pick Native Sélectionnez
3. Sur et créez-la. onglet, notez le Domaine (par exemple example.eu.auth0.comet le ID du client.
4. Sous Credentials, vérifiez que le mode d'authentification est Aucun. C'est la configuration de client public utilisée avec PKCE.

URLs de rappel et de déconnexion

Remplissez ces champs Paramètres > URIs de l'application:

Séparez les valeurs avec des virgules. Utilisez votre Capacitor. appId Comme le schéma. Un schéma inverse-domain évite les collisions avec d'autres applications. Si vous envoyez également une build web, de nombreux équipes créent un schéma séparé. Application de page unique ne pas mélanger les paramètres web et mobiles pour Auth0.

jetons de rafraîchissement

Si les utilisateurs doivent rester connectés :

1. En Paramètres > Rotation de jetons de rafraîchissement, activez la rotation. Chaque rafraîchissement renvoie un nouveau jeton de rafraîchissement et invalide l'ancien.
2. Définissez une durée absolue et d'inactivité qui convient à votre produit.
3. Si vous appelez votre propre API, ouvrez Applications > API > votre API > Paramètres et activez Accès hors ligne autorisé.
4. Demandez le offline_access scope dans l'application.

API audience

Si votre backend valide les jetons d'accès Auth0, créez un API sous Applications > APIs avec un identifiant tel que https://api.example.comPasser cet identifiant à audienceSans cela, le jeton d'accès n'est valable que pour l'endpoint d'Auth0. /userinfo endpoint.

Étape 2 : Installez et configurez le plugin

bun add @capgo/capacitor-social-login
bunx cap sync

Si Auth0 est votre seul fournisseur, désactivez les SDK sociaux intégrés pour garder le fichier binaire léger :

// capacitor.config.ts
plugins: {
  SocialLogin: {
    providers: { google: false, facebook: false, apple: false, twitter: false },
  },
},

L'engine OAuth2 générique ne dépend pas de ces SDK.

Ajoutez le schéma de rappel à

Ajoutez le schéma de rappel à MainActivity In android/app/src/main/AndroidManifest.xml:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="com.example.app" android:host="oauth" />
</intent-filter>

Le modèle de Capacitor est déjà configuré android:launchMode="singleTask" sur MainActivity, which the redirect needs. Keep it.

Étape 3 : Initialiser le fournisseur Auth0

import { Capacitor } from '@capacitor/core';
import { SocialLogin } from '@capgo/capacitor-social-login';

const AUTH0_DOMAIN = 'https://example.eu.auth0.com';
const isWeb = Capacitor.getPlatform() === 'web';

export async function initAuth() {
  await SocialLogin.initialize({
    oauth2: {
      auth0: {
        appId: 'YOUR_AUTH0_CLIENT_ID',
        authorizationBaseUrl: `${AUTH0_DOMAIN}/authorize`,
        accessTokenEndpoint: `${AUTH0_DOMAIN}/oauth/token`,
        resourceUrl: `${AUTH0_DOMAIN}/userinfo`,
        redirectUrl: isWeb
          ? 'https://app.example.com/auth/callback'
          : 'com.example.app://oauth/auth0',
        scope: 'openid profile email offline_access',
        pkceEnabled: true,
        additionalParameters: {
          audience: 'https://api.example.com',
        },
        logoutUrl: `${AUTH0_DOMAIN}/oidc/logout`,
        postLogoutRedirectUrl: isWeb
          ? 'https://app.example.com/'
          : 'com.example.app://oauth/logout',
        androidUseCustomTabs: true,
      },
    },
  });
}

Vous pouvez remplacer les points de terminaison explicites par issuerUrl: AUTH0_DOMAIN. Le plugin lit ensuite /.well-known/openid-configuration. Les valeurs explicites l'emportent sur celles découvertes, ce qui est utile lorsque vous utilisez un domaine personnalisé Auth0.

Si vous passez d'Auth Connect Ionic, le plugin exporte également SocialLoginAuthConnect avec un auth0 préconfiguré qui prend domain, clientId, redirectUrl et audience. Voir le Guide de migration Auth Connect.

Étape 4 : Se connecter

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function signInWithAuth0() {
  try {
    const { result } = await SocialLogin.login({
      provider: 'oauth2',
      options: { providerId: 'auth0' },
    });

    return {
      idToken: result.idToken,
      accessToken: result.accessToken?.token,
      expiresAt: result.accessToken?.expires,
      refreshToken: result.refreshToken,
      user: result.resourceData, // JSON from /userinfo
    };
  } catch (error: any) {
    if (error?.code === 'USER_CANCELLED') return null;
    throw error;
  }
}

Options de connexion utiles :

• prompt: 'login' oblige la page de connexion même si Auth0 possède encore une cookie de session.
• loginHint: 'user@example.com' remplit automatiquement l'adresse e-mail.
• additionalParameters: { connection: 'google-oauth2' } ignore l’Universal Login et se dirige vers une connexion unique.
• additionalParameters: { screen_hint: 'signup' } ouvre l'écran d'inscription.

Callback de redirection web

En web, la flèche de popup par défaut n'a besoin de rien d'autre. Si vous utilisez flow: 'redirect'lisez le résultat sur la page de rappel :

const result = await SocialLogin.handleRedirectCallback();
if (result?.provider === 'oauth2') {
  console.log(result.result.idToken);
}

handleRedirectCallback est uniquement disponible en web et rejette sur iOS et Android.

Étape 5 : Lisez le jeton d'ID et appelez votre API

Décodez le jeton d'ID uniquement sur le client pour affichage :

const { claims } = await SocialLogin.decodeIdToken({ idToken: result.idToken! });
console.log(claims.email, claims.name, claims.sub);

decodeIdToken Ne vérifie pas la signature. Pour tout ce qui concerne la sécurité, envoyez le jeton d'accès à votre API et validez-le là-bas.

import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL('https://example.eu.auth0.com/.well-known/jwks.json'));

export async function verifyAuth0AccessToken(token: string) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: 'https://example.eu.auth0.com/', // Auth0 issuers end with a slash
    audience: 'https://api.example.com',
  });
  return payload; // payload.sub is the Auth0 user ID
}

Étape 6 : Raffraîchissez le jeton d'accès

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function getValidAccessToken() {
  const { isLoggedIn } = await SocialLogin.isLoggedIn({ provider: 'oauth2', providerId: 'auth0' });

  if (!isLoggedIn) {
    // access token expired: try the stored refresh token
    try {
      await SocialLogin.refresh({ provider: 'oauth2', options: { providerId: 'auth0' } });
    } catch {
      // refresh token expired, revoked or already rotated: sign in again
      const loginResult = await signInWithAuth0();
      if (!loginResult) throw new Error('Sign-in cancelled');
    }
  }

  const { accessToken } = await SocialLogin.getAuthorizationCode({
    provider: 'oauth2',
    providerId: 'auth0',
  });
  return accessToken;
}

refresh se refuse lorsque le jeton de rafraîchissement est expiré ou révoqué. Avec la rotation activée, un jeton de rafraîchissement qui a déjà été utilisé échoue également, il faut donc toujours gérer la réjection en renvoyant l'utilisateur à la connexion.

refresh uses the refresh token the plugin saved at login. If you keep the refresh token yourself, call SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'auth0', refreshToken })Qui renvoie la réponse de jeton complet mis à jour, avec stockage du nouveau jeton de refresh à chaque rotation.

Le plugin garde sa copie de jeton dans le stockage privé de l'application. Si votre revue de sécurité demande Keychain ou Keystore, stockez le jeton de rafraîchissement avec NativeBiometric.setData({ key, value }) à partir de @capgo/capacitor-native-biometrique et passez-l’à refreshToken votre propre. Notre guide de stockage de jetons sécurisé comparaison des options.

Étape 7 : Déconnexion

await SocialLogin.logout({ provider: 'oauth2', providerId: 'auth0' });

La mise à jour supprime les jetons stockés, puis ouvre logoutUrl avec id_token_hint et post_logout_redirect_uri Auth0 efface sa cookie de session. Auth0's /oidc/logout endpoint comprend ces paramètres, et l'objectif de redirection doit être listé dans URLs autorisées de déconnexion.

On iOS and Android the end-session page opens in the system browser, so the user briefly leaves the app. If you only want a local logout, omit logoutUrl et passer prompt: 'login' Pour éviter que l'utilisateur soit reconnecté automatiquement à la prochaine connexion, configurez la session Auth0 pour être oubliée. iosPrefersEphemeralSession: true évite également les cookies partagés sur iOS, au prix de pas de SSO entre les applications.

Troubleshooting

Configurer logsEnabled: true dans la configuration du fournisseur pour imprimer les URL générées et les détails d'échange de jetons pendant la débogage.

Ship auth fixes without a store release

La modification des champs, la cible ou la gestion des erreurs est réservée à TypeScript. Capgo mises à jour en direct vous pouvez déployer ces correctifs aux utilisateurs le même jour. Les modifications natives telles qu'un nouveau filtre d'intention nécessitent toujours une nouvelle version, qui Capgo Création peut être produite dans le cloud.

Guides connexes

• Comment vous connecter avec Okta à l'aide de Capacitor
• Comment vous connecter avec Microsoft Entra ID à l'aide de Capacitor
• Comment ajouter une authentification à une application Capacitor
• Documents de fournisseurs OAuth2 et OIDC génériques