Ajouter le login à votre application Ionic React avec Capacitor

Ce guide explique comment intégrer Auth0 à une application Ionic React avec Capacitor à l’aide du Auth0 React SDK.

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant IA de codage comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide d’Agent Skills.

Commencez par installer les Auth0 agent skills :

npx skills add auth0/agent-skills --skill auth0

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my Ionic React app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, installera le Auth0 React SDK et les plugins Capacitor, configurera les liens profonds et mettra en place les flux de login et de logout avec l’intégration du navigateur natif. Pour en savoir plus, consultez Auth0 agent skills.

​

Pour commencer

Ce guide de démarrage rapide montre comment ajouter l’authentification Auth0 à une application Ionic React avec Capacitor. Vous créerez une application mobile avec des fonctionnalités de login, de logout et de profil d’utilisateur à l’aide du Auth0 React SDK et de l’intégration au navigateur natif de Capacitor.

1. Créer un nouveau projet

   Créer une nouvelle application Ionic React avec Capacitor

   npx ionic start auth0-ionic-react tabs --type=react --capacitor
   

   Ouvrir le projet

   cd auth0-ionic-react
   

   Assurez-vous d’utiliser le package @ionic/cli (et non le package ionic obsolète). Si vous voyez des erreurs liées à --npm-client pendant la création du projet, mettez votre CLI à jour :

   npm uninstall -g ionic
   npm i -g @ionic/cli
   

   Si vous avez déjà une application Ionic React, assurez-vous que Capacitor est activé. Vous pouvez l’ajouter avec ionic integrations enable capacitor, puis npx cap init.

2. Installez le SDK React d’Auth0 et les plugins Capacitor

   Le template de démarrage Ionic peut générer react@19.0.0, qui n’est pas compatible avec l’Auth0 React SDK. Assurez-vous d’abord d’avoir une version de React prise en charge :

   npm install react@^19.0.1 react-dom@^19.0.1
   

   Installez ensuite le SDK Auth0 et les plugins Capacitor :

   npm install @auth0/auth0-react @capacitor/browser @capacitor/app && npx cap sync
   

   • @auth0/auth0-react : fournit des hooks et des composants React pour l’authentification Auth0
   • @capacitor/browser : ouvre la page de connexion dans le navigateur système de l’appareil (SFSafariViewController sur iOS, Chrome Custom Tabs sur Android)
   • @capacitor/app : gère les URL de rappel par lien profond lorsqu’Auth0 redirige vers votre application

   Le plugin Browser de Capacitor sur iOS utilise SFSafariViewController, qui, sur iOS 11 et versions ultérieures, ne partage pas les cookies avec Safari sur l’appareil. Cela signifie que le SSO ne fonctionnera pas sur ces appareils. Si vous avez besoin du SSO, utilisez un plugin compatible qui utilise ASWebAuthenticationSession.

3. Configurez votre Auth0 App

   Ensuite, vous devez créer une nouvelle application sur votre tenant Auth0 et ajouter les variables d’environnement à votre projet.

   Vous avez trois options pour configurer votre application Auth0 : utiliser l’outil Quick Setup (recommandé), exécuter une commande CLI ou configurer manuellement via le tableau de bord.

   Dans ce guide Quickstart, YOUR_PACKAGE_ID correspond à l’ID du package de votre application. Il s’agit du champ appId dans votre fichier capacitor.config.ts (p. ex. io.ionic.starter). Consultez le schéma de configuration de Capacitor pour en savoir plus.

   Configuration rapide (recommandée)

   Créez une Auth0 App et copiez le fichier .env prérempli avec les bonnes valeurs de configuration.

   Après avoir créé l’application, allez dans ses Settings dans le Auth0 Dashboard et mettez à jour les Allowed Callback URLs et les Allowed Logout URLs pour remplacer YOUR_PACKAGE_ID par votre véritable ID de package et YOUR_AUTH0_DOMAIN par votre domaine Auth0 :

   YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
   

   Assurez-vous également que le Type d’application est défini sur Native et que la Méthode d’authentification du point de terminaison de jeton est définie sur Aucune.

   CLI

   Exécutez la commande suivante à la racine de votre projet pour créer une application Auth0 et générer un fichier .env :

   Mac

   # Installer Auth0 CLI (si ce n’est pas déjà fait)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Configurer l’application Auth0 et générer le fichier .env
   auth0 qs setup --app --type native --framework ionic-react --build-tool vite --name "My Ionic React App"
   

   Cette commande :

   1. Vérifie si vous êtes authentifié(e) (et vous invite à vous connecter au besoin)
   2. Crée une application Auth0 Native
   3. Génère un fichier .env avec VITE_AUTH0_DOMAIN et VITE_AUTH0_CLIENT_ID

   Créez un fichier .env avec les valeurs affichées par l’Auth0 CLI :

   Dashboard

   Avant de commencer, créez un fichier .env à la racine de votre projet

   .env

   VITE_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
   VITE_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
   

   1. Accédez au Auth0 Dashboard
   2. Cliquez sur Applications > Applications > Create Application
   3. Dans la fenêtre contextuelle, saisissez un nom pour votre application, sélectionnez Native comme type d’application, puis cliquez sur Create
   4. Ouvrez l’onglet Settings dans la page Application Details
   5. Remplacez YOUR_AUTH0_APP_DOMAIN et YOUR_AUTH0_APP_CLIENT_ID dans le fichier .env par les valeurs Domain et Client ID du dashboard
   6. Réglez Token Endpoint Authentication Method sur None

   Enfin, dans l’onglet Settings de la page Application Details, configurez les URL suivantes (remplacez YOUR_PACKAGE_ID par votre appId dans capacitor.config.ts) :

   Allowed Callback URLs:

   YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
   

   URLs de déconnexion autorisées :

   YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
   

   Origines autorisées :

   capacitor://localhost, http://localhost
   

   Allowed Callback URLs constituent une mesure de sécurité essentielle pour garantir que les utilisateurs sont redirigés en toute sécurité vers votre application après l’authentication. Sans URL correspondante, le processus de login échouera et les utilisateurs verront une page d’erreur Auth0 au lieu d’accéder à votre application.

   Allowed Logout URLs sont essentielles pour offrir une expérience utilisateur fluide au moment de la déconnexion. Sans URL correspondante, les utilisateurs ne seront pas redirigés vers votre application après la déconnexion et resteront plutôt sur une page Auth0 générique.

   Allowed Origins (capacitor://localhost pour iOS et http://localhost pour Android) sont requises pour que votre application native puisse communiquer avec l’Auth0 API.

   Assurez-vous que votre fichier .env existe : cat .env (Mac/Linux) ou type .env (Windows)

4. Configurer Auth0Provider

   Ouvrez src/main.tsx et entourez le composant App avec Auth0Provider. Les paramètres propres aux appareils mobiles useRefreshTokens et useRefreshTokensFallback sont requis pour les applications Ionic sur iOS et Android.

   src/main.tsx

   import React from 'react';
   import { createRoot } from 'react-dom/client';
   import App from './App';
   import { Auth0Provider } from '@auth0/auth0-react';
   
   // Doit correspondre à l'appId dans votre capacitor.config.ts
   const appId = 'io.ionic.starter';
   
   createRoot(document.getElementById('root')!).render(
     <React.StrictMode>
       <Auth0Provider
         domain={import.meta.env.VITE_AUTH0_DOMAIN}
         clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
         useRefreshTokens={true}
         useRefreshTokensFallback={false}
         authorizationParams={{
           redirect_uri: `${appId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${appId}/callback`
         }}
       >
         <App />
       </Auth0Provider>
     </React.StrictMode>
   );
   

   • useRefreshTokens : Requis pour Ionic sur Android et iOS. Les navigateurs mobiles bloquent les cookies tiers; le SDK utilise donc des jetons d’actualisation au lieu de l’authentification silencieuse basée sur des iframe.
   • useRefreshTokensFallback : Doit être false pour empêcher le SDK de tenter une authentification silencieuse basée sur des iframe, qui n’est pas offerte sur mobile.
   • authorizationParams.redirect_uri : Utilise l’ID de votre package comme schéma d’URL personnalisé afin que le système d’exploitation puisse rediriger le callback Auth0 vers votre application.

   Pour conserver l’authentification après avoir fermé puis rouvert l’application, vous pouvez définir cacheLocation à localstorage, mais sachez qu’il existe des risques liés au stockage de jetons dans localstorage. Sur Capacitor, localstorage doit être considéré comme transitoire — le système d’exploitation peut l’effacer de façon inattendue. Consultez les recommandations de Capacitor sur le stockage.

   Nous recommandons de ne pas utiliser le Plugin Preferences de Capacitor pour stocker des jetons, car il repose sur UserDefaults (iOS) et SharedPreferences (Android), qui ne sont pas chiffrés et pourraient être synchronisés dans le nuage. Le SDK prend en charge les implémentations de cache personnalisées si vous avez besoin d’un mécanisme de stockage plus sécuritaire et persistant.

5. Créer un gestionnaire de Login, Logout, profil et callback

   Créer des fichiers

   Mac/Linux

   touch src/LoginButton.tsx && touch src/LogoutButton.tsx && touch src/Profile.tsx
   

   Et ajoutez les extraits de code suivants

   Le rappel openUrl dans LoginButton et LogoutButton utilise le plugin Browser de Capacitor pour ouvrir les pages de login et de logout Auth0 dans le composant de navigateur système de l’appareil, plutôt que de quitter complètement l’application.

   Le composant App écoute l’événement appUrlOpen, qui se déclenche lorsqu’Auth0 redirige vers votre application en utilisant le schéma d’URL personnalisé. Il appelle handleRedirectCallback pour échanger le code d’autorisation contre des jetons, puis ferme le navigateur.

   Par défaut, la méthode loginWithRedirect du SDK utilise window.location.href pour rediriger vers la page de connexion, ce qui ouvre l’application de navigateur par défaut de l’appareil. En configurant openUrl pour utiliser Browser.open, vous gardez le flux d’authentification dans le contexte de votre application, pour une meilleure expérience utilisateur.

6. Lancez votre application

   Testez d’abord dans le navigateur

   ionic serve
   

   Lors de l’exécution dans le navigateur avec ionic serve, la redirection par schéma d’URL personnalisé (io.ionic.starter://...) ne fonctionnera pas, car les navigateurs ne prennent pas en charge les schémas d’URL personnalisés. Pour effectuer des tests dans le navigateur, remplacez temporairement redirect_uri par http://localhost:8100 dans src/main.tsx, puis ajoutez http://localhost:8100 à Allowed Callback URLs et à Allowed Logout URLs de votre application Auth0 dans le Dashboard. N’oubliez pas de rétablir cette modification avant de compiler pour Native.

   Pour exécuter l’application sur un appareil ou un simulateur, ajoutez d’abord les plateformes natives :

   npx cap add ios
   npx cap add android
   

   Ensuite, compilez, synchronisez et exécutez :

   iOS

   ionic build && npx cap sync && npx cap run ios
   

   Vous devez ajouter les plateformes natives avec npx cap add avant de pouvoir les lancer. Cette étape ne doit être effectuée qu’une seule fois par plateforme. Ensuite, npx cap sync copie vos assets Web compilés et met à jour les plug-ins natifs.

Checkpoint

Vous devriez maintenant avoir un login Auth0 entièrement fonctionnel dans votre application Ionic. Sur un appareil, un appui sur « Se connecter » ouvre la page de connexion Universal Login d’Auth0 dans le navigateur système, puis, après l’authentification, vous êtes redirigé vers votre application, où le profil de l’utilisateur s’affiche.

---

​

Utilisation avancée

Configuration d’un schéma d’URL personnalisé (iOS et Android)

Pour que les callbacks Auth0 fonctionnent sur les appareils, enregistrez l’ID de votre package comme schéma d’URL personnalisé sur chaque plateforme.

iOS — ajoutez ceci à ios/App/App/Info.plist :

ios/App/App/Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>io.ionic.starter</string>
    </array>
  </dict>
</array>

Android — ajoutez un intent-filter dans l’élément principal <activity> de android/app/src/main/AndroidManifest.xml :

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="io.ionic.starter" />
</intent-filter>

Remplacez io.ionic.starter par votre appId réel dans capacitor.config.ts.

Pour en savoir plus, consultez Defining a Custom URL Scheme pour iOS, ou Create Deep Links to App Content pour Android.

Protéger les routes avec Ionic Router

Utilisez l’état d’authentification d’Auth0 pour protéger certaines routes de votre application Ionic :

src/App.tsx

import { useAuth0, withAuthenticationRequired } from '@auth0/auth0-react';
import { IonReactRouter } from '@ionic/react-router';
import { IonRouterOutlet } from '@ionic/react';
import { Route, Redirect } from 'react-router-dom';
import HomePage from './pages/Home';
import DashboardPage from './pages/Dashboard';

const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <div className="ion-padding">Loading...</div>,
  });
  return <Route {...args} render={() => <Component />} />;
};

const App: React.FC = () => {
  // ... gestionnaire de callback de l’étape précédente

  return (
    <IonApp>
      <IonReactRouter>
        <IonRouterOutlet>
          <Route exact path="/home" component={HomePage} />
          <ProtectedRoute exact path="/dashboard" component={DashboardPage} />
          <Route exact path="/">
            <Redirect to="/home" />
          </Route>
        </IonRouterOutlet>
      </IonReactRouter>
    </IonApp>
  );
};

Le HOC withAuthenticationRequired redirige automatiquement les utilisateurs non authentifiés vers la Auth0 login page lorsqu’ils essaient d’accéder à une route protégée.

Appeler des API protégées

Configurez votre Auth0Provider pour inclure une audience d’API et utilisez la méthode getAccessTokenSilently pour obtenir des jetons d’accès pour votre backend :

src/main.tsx

<Auth0Provider
  domain={import.meta.env.VITE_AUTH0_DOMAIN}
  clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
  useRefreshTokens={true}
  useRefreshTokensFallback={false}
  authorizationParams={{
    redirect_uri: `${appId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${appId}/callback`,
    audience: "YOUR_API_IDENTIFIER"
  }}
>
  <App />
</Auth0Provider>

Faites ensuite des appels d’API authentifiés depuis vos composants :

src/ApiCall.tsx

import { useState } from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { IonButton, IonText } from '@ionic/react';

const ApiCall: React.FC = () => {
  const { getAccessTokenSilently } = useAuth0();
  const [result, setResult] = useState<string | null>(null);

  const callApi = async () => {
    try {
      const token = await getAccessTokenSilently();

      const response = await fetch('https://your-api.example.com/protected', {
        headers: {
          Authorization: `Bearer ${token}`
        }
      });

      const data = await response.json();
      setResult(JSON.stringify(data, null, 2));
    } catch (error) {
      console.error('API call failed:', error);
    }
  };

  return (
    <div className="ion-padding">
      <IonButton onClick={callApi}>Call Protected API</IonButton>
      {result && (
        <IonText>
          <pre>{result}</pre>
        </IonText>
      )}
    </div>
  );
};

export default ApiCall;