Comment ajouter l'authentification à une application Capacitor (2026)

Pour ajouter l’authentification à une application Capacitor, choisissez une source d’identité (votre propre backend, un service hébergé comme Firebase, Supabase ou Neon, un fournisseur OIDC comme Auth0, Okta ou Entra ID, ou une bibliothèque auto-hébergée comme Better Auth), utilisez des plugins natifs pour tout ce qui ouvre une page de connexion du fournisseur, vérifiez les tokens côté serveur et stockez la session obtenue dans le Keychain ou le Keystore. La biométrie et les passkeys accélèrent ensuite les connexions suivantes.

Ce guide associe chaque option courante au bon plugin et au bon flux Capacitor, avec code pour les parties communes à toutes les applications : l’appel de connexion, la vérification des tokens, le stockage de session et le déblocage biométrique. Il est à jour pour Capacitor 8, en octobre 2026. Chaque fournisseur a son propre guide pas à pas, lié ci-dessous.

Le flux d’authentification auquel aboutit toute application Capacitor

Quelle que soit le fournisseur choisi, la structure est la même :

1. Identifier l’utilisateur : feuille sociale native, page de connexion du fournisseur dans le navigateur système, prompt de passkey ou formulaire qui envoie l’e-mail et le mot de passe.
2. Obtenir une preuve: un ID token, un code d’autorisation, ou un token de session de votre serveur d’authentification.
3. Vérifier côté serveur: vérifier la signature, l’émetteur, l’audience et l’expiration, puis créer ou retrouver l’utilisateur.
4. Émettre une session: votre propre token ou les tokens du fournisseur, avec une stratégie de rafraîchissement.
5. Le stocker en toute sécurité sur l’appareil et l’attacher aux appels API.
6. Débloquer rapidement la prochaine fois avec la biométrie, et gérer la déconnexion et la suppression du compte.

Les étapes 1 et 2 varient selon le fournisseur. Les étapes 3 à 6 sont de votre responsabilité dans toutes les options, sauf avec un BaaS entièrement hébergé, où le SDK fait l’essentiel du travail.

Pourquoi les pages de connexion WebView cassent

Une app Capacitor exécute votre code web dans un WKWebView (iOS) ou un WebView Android avec une origine locale (capacitor://localhost ou https://localhost). Charger la page de connexion d’un fournisseur dans ce WebView provoque trois problèmes :

• Google renvoie disallowed_useragent et refuse d’afficher la page.
• L’application ne peut pas prouver que la page est le fournisseur légitime, c’est pourquoi la RFC 8252 recommande aux applications natives d’utiliser le navigateur système.
• Une redirection pleine page sort de votre application bundle et fait perdre l’état.

Ainsi, chaque flux ci-dessous utilise soit un SDK natif (Apple, Google, Facebook), soit une session de navigateur système (ASWebAuthenticationSession sur iOS, Chrome Custom Tabs sur Android) qui revient vers l’application via un schéma personnalisé.

Vos options en un coup d’œil

Connexion sociale native (Apple, Google, Facebook)

Un seul plugin couvre les trois grands fournisseurs grand public ainsi qu'un moteur OAuth2 générique :

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

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

await SocialLogin.initialize({
  apple: { clientId: 'com.example.app' },
  google: {
    webClientId: 'WEB_CLIENT_ID.apps.googleusercontent.com',
    iOSClientId: 'IOS_CLIENT_ID.apps.googleusercontent.com',
  },
});

const { result } = await SocialLogin.login({ provider: 'google', options: {} });
// send result.idToken to your server

Désactivez les providers que vous n'utilisez pas dans capacitor.config.ts (plugins.SocialLogin.providers) afin que leurs SDK ne soient pas compilés dans l'app. Cela supprime aussi la permission d'ID publicitaire de Facebook SDK si vous n'utilisez pas Facebook.

Chaque fournisseur a sa configuration native : Apple requiert la capability dans Xcode et un Services ID, Google requiert des empreintes SHA-1 et un scheme d'URL d'ID client inversé. Les Apple et Google guides détaillent chaque étape et les erreurs courantes.

SSO entreprise avec OAuth 2.0 et OpenID Connect

Pour Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin ou votre propre serveur OIDC, utilisez le oauth2 provider. Il exécute le flux d'autorisation code avec PKCE dans ASWebAuthenticationSession sur iOS et dans des Custom Tabs sur Android lorsque vous définissez androidUseCustomTabs: true:

await SocialLogin.initialize({
  oauth2: {
    corp: {
      issuerUrl: 'https://sso.example.com/realms/mobile', // OIDC discovery
      clientId: 'mobile-app',
      redirectUrl: 'com.example.app://oauth/corp',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      androidUseCustomTabs: true,
    },
  },
});

const { result } = await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'corp' },
});

Vous pouvez enregistrer plusieurs providers dans la même map et en choisir un avec providerId, ce qui permet aux apps B2B multi-tenant de laisser chaque client utiliser son propre IdP. Le plugin gère aussi le refresh (SocialLogin.refresh, déconnexion avec id_token_hint, et un wrapper compatible Ionic Auth Connect (SocialLoginAuthConnect), pour les équipes qui migrent depuis Auth Connect. Tutoriels par fournisseur : Auth0, Okta, Entra ID. Pour le contexte sur le protocole, voir 5 étapes pour implémenter OAuth2 dans les apps Capacitor.

Backends hébergés : Firebase, Supabase et Neon

Si vos données sont déjà sur Firebase, Supabase ou Neon, utilisez leur auth pour que les règles de sécurité et la sécurité au niveau des lignes fonctionnent sans code supplémentaire.

• Supabase: obtenez un ID token avec le plugin Social Login et appelez supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase le vérifie et renvoie une session. Configuration complète : Supabase avec Capacitor Social Login.
• Neon: Neon Auth est un Better Auth géré qui vit sur votre branche Neon. @capgo/capacitor-neon authentifie les utilisateurs nativement avec e-mail et mot de passe, OTP par e-mail, ou Google, GitHub et Vercel OAuth dans le navigateur système. Il renvoie un JWT pour le Neon Data API, so row-level security applies. Full setup: Documentation du plugin Neon.
• Firebase: utilisez soit @capgo/capacitor-firebase-authentication, qui encapsule les SDK natifs Firebase Auth, ou obtenez un ID token avec Social Login et créez une référence Firebase à partir de celui-ci dans le SDK JS. Consultez la Docs Firebase Google login.

Auto-hébergé : Better Auth

Better Auth est une bibliothèque d'auth TypeScript open source qui stocke les utilisateurs dans votre propre base de données. Elle fonctionne dans Capacitor une fois que vous avez approuvé les origines de l'app et êtes passé aux bearer tokens, car les cookies cross-site ne sont pas fiables dans WKWebView. Le social login passe par le plugin natif et un transfert d'ID token. Étape par étape : Comment utiliser Better Auth dans les apps Capacitor.

Passkeys

Les passkeys remplacent les mots de passe par une paire de clés stockée dans iCloud Keychain ou Google Password Manager. Elles nécessitent que votre app soit associée au domaine de votre site web (apple-app-site-association sur iOS, assetlinks.json sur Android) et à un serveur WebAuthn.

@capgo/capacitor-passkey vous permet de conserver les code WebAuthn standard. Configurez la relying party dans capacitor.config.ts, appelez le shim une fois au démarrage, et navigator.credentials.create() et .get() sont routés vers les API natives de passkey :

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();

// existing WebAuthn code keeps working
const assertion = await navigator.credentials.get({
  publicKey: requestOptionsFromServer,
});

Des bibliothèques comme Better Auth, ou des fournisseurs hébergés comme Auth0 et Okta, peuvent servir de serveur WebAuthn. Voir la page du plugin passkey.

E-mail et mot de passe avec votre propre backend

Aucun plugin n'est nécessaire, il s'agit simplement de fetch. Le travail se fait côté serveur : hachage avec Argon2id ou bcrypt, limitation du nombre de tentatives de connexion, envoi d'e-mails de vérification et de réinitialisation, et gestion de la suppression de compte. Ouvrez les liens de réinitialisation et de vérification dans l'app via Universal Links et App Links, pour que le lien s'ouvre au bon endroit sur le téléphone. À moins d'avoir une raison de tout gérer vous-même, une bibliothèque comme Better Auth ou un service hébergé offre les mêmes fonctionnalités avec moins de risques.

Vérifiez toujours les tokens sur le serveur

Les vérifications côté client peuvent être contournées. Quel que soit le fournisseur, le serveur doit vérifier le token avant de créer une session :

import { createRemoteJWKSet, jwtVerify } from 'jose';

type IssuerConfig = {
  jwks: ReturnType<typeof createRemoteJWKSet>;
  issuer: string | string[];
  audience: string[];
};

const issuers: Record<'google' | 'apple', IssuerConfig> = {
  google: {
    jwks: createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs')),
    issuer: ['https://accounts.google.com', 'accounts.google.com'],
    audience: ['WEB_CLIENT_ID.apps.googleusercontent.com', 'IOS_CLIENT_ID.apps.googleusercontent.com'],
  },
  apple: {
    jwks: createRemoteJWKSet(new URL('https://appleid.apple.com/auth/keys')),
    issuer: 'https://appleid.apple.com',
    audience: ['com.example.app', 'com.example.app.signin'],
  },
};

export async function verifyIdToken(provider: 'google' | 'apple', idToken: string) {
  const cfg = issuers[provider];
  const { payload } = await jwtVerify(idToken, cfg.jwks, {
    issuer: cfg.issuer,
    audience: cfg.audience,
  });
  return payload; // use payload.sub as the stable provider user ID
}

Identifiez les utilisateurs sur l'identifiant du fournisseur sub (plus le nom du provider), pas via l'e-mail. Ne liez les comptes par e-mail que lorsque le provider le marque comme vérifié («email_verified: true). Les tokens Limited Login de Meta n'incluent pas cette claim.

Stockez la session de manière sécurisée

localStorage et les préférences de Capacitor sont des fichiers simples. Stockez les tokens persistants dans le Keychain (iOS) ou dans un stockage chiffré par Keystore (Android). @capgo/capacitor-native-biometric est simple setData, getData et deleteData méthodes à cet effet :

bun add @capgo/capacitor-native-biometric
bunx cap sync

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

export const sessionStore = {
  async save(token: string) {
    await NativeBiometric.setData({ key: 'session.token', value: token });
  },
  async load(): Promise<string | null> {
    try {
      const { value } = await NativeBiometric.getData({ key: 'session.token' });
      return value;
    } catch {
      return null;
    }
  },
  async clear() {
    await NativeBiometric.deleteData({ key: 'session.token' }).catch(() => {});
  },
};

Gardez les access tokens à durée de vie courte et rafraîchissez-les via un refresh token ou une session serveur. Notre guide sur le stockage sécurisé des tokens aborde la rotation et la révocation plus en détail.

Biométrie : déverrouiller, pas identifier

Face ID et l’empreinte digitale prouvent seulement que la personne qui tient le téléphone peut le déverrouiller. Utilisez-les pour conditionner l’accès à une session stockée :

import { AccessControl, NativeBiometric } from '@capgo/capacitor-native-biometric';

// after a real login, offer biometric unlock
await NativeBiometric.setData({
  key: 'session.refresh',
  value: refreshToken,
  accessControl: AccessControl.BIOMETRY_ANY,
});

// next app start
const { value } = await NativeBiometric.getSecureData({
  key: 'session.refresh',
  reason: 'Unlock your account',
});
// exchange `value` with your server for a fresh access token

Avec accessControl une fois configuré, le système d’exploitation ne restitue la valeur qu’après une vérification biométrique réussie : la protection est donc assurée par le Keychain ou le Keystore, et non par JavaScript. Combinez-l’avec une expiration de session côté serveur et, pour les applications à haut risque, avec la détection de root et de jailbreak. Plus d’infos dans L'authentification biométrique dans les apps Capacitor.

Choisir une méthode

Règles App Store et Play Store qui affectent le login

• Apple 4.8 Services de connexion: la connexion tierce comme système de compte principal exige une option équivalente axée sur la confidentialité. Sign in with Apple répond à cette exigence.
• Apple 5.1.1(v): la création de compte impose la suppression du compte dans l’application, et les tokens Sign in with Apple doivent être révoqués. Voir conformité à la suppression de compte.
• Suppression de compte Google Play: les applications avec comptes doivent proposer la suppression dans l’application et via un lien web déclaré dans Play Console.
• Accès pour les reviewers: give reviewers a working demo account. If login is SSO only, provide a test tenant user.
• Xcode 26: App Store Connect exige depuis avril 2026 des builds réalisés avec Xcode 26 et l’iOS 26 SDK, pensez donc à mettre à jour avant de soumettre une release qui ajoute de nouvelles fonctionnalités d’authentification.

Déployer des changements d'auth en toute sécurité

Les bugs d’authentification bloquent tous les utilisateurs, il faut donc les corriger rapidement. Les modifications natives (entitlements, URL schemes, intent filters) nécessitent un build store. Tout ce qui est en TypeScript, comme la configuration du provider, les scopes, la gestion des erreurs et l’UI, peut être poussé avec les live updates Capgo et rollback si quelque chose casse. Build Capgo génère les binaires iOS et Android signés dans le cloud lorsque vous avez besoin d’une nouvelle release native.

Prochaines étapes

Choisissez votre provider et suivez le guide correspondant :

• Se connecter avec Apple
• Se connecter avec Google
• Auth0
• Okta
• Microsoft Entra ID
• Better Auth
• Documentation du plugin Social Login