Ajouter la connexion à votre application Ionic React avec Capacitor

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

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant de programmation IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide des agent skills.

Commencez par installer les agent skills d’Auth0 :

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-ionic-react

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 informations d’identification, installera le SDK Auth0 React et les plugins Capacitor, configurera les liens profonds et mettra en place les flux de connexion et de déconnexion avec intégration au navigateur natif. Pour en savoir plus, consultez les agent skills d’Auth0.

​

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 connexion, de déconnexion et de profil utilisateur à l’aide du SDK React d’Auth0 et de l’intégration au navigateur natif de Capacitor.

1. Créer un nouveau projet

   Créez une nouvelle application Ionic React avec Capacitor

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

   Ouvrez le projet

   cd auth0-ionic-react
   

   Assurez-vous d’utiliser le paquet @ionic/cli (et non le paquet ionic, désormais obsolète). Si vous voyez des erreurs concernant --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 exécuter npx cap init.

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

   Le modèle de départ Ionic peut générer react@19.0.0, qui n’est pas compatible avec le SDK React d’Auth0. Assurez-vous d’abord d’utiliser 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 plug-ins 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 avec 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 retours par lien profond lorsque Auth0 redirige vers votre application

   Le plugin Browser de Capacitor sur iOS utilise SFSafariViewController, qui, sur iOS 11+, 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 s’appuie sur ASWebAuthenticationSession.

3. Configurez votre application Auth0

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

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

   Tout au long de ce guide de démarrage rapide, YOUR_PACKAGE_ID correspond à l’identifiant de package de votre application. Il s’agit de la valeur du champ appId dans votre fichier capacitor.config.ts (par ex. io.ionic.starter). Consultez le schéma de configuration de Capacitor pour en savoir plus.

   Configuration rapide (recommandée)

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

   Après avoir créé l’application, accédez à ses Settings dans le tableau de bord Auth0 et mettez à jour les Allowed Callback URLs et les Allowed Logout URLs en remplaçant YOUR_PACKAGE_ID par l’ID de package réel de votre application 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 réglé sur Native et que la méthode d’authentification du point de terminaison de jeton est réglée sur None.

   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
   
   # Créer une application native Auth0
   auth0 apps create \
     --name "Ionic React App" \
     --type native \
     --callbacks "YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback" \
     --logout-urls "YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback" \
     --origins "capacitor://localhost,http://localhost"
   

   Cette commande va :

   1. Vérifier si vous êtes déjà authentifié et vous inviter à vous connecter au besoin
   2. Créer une application native Auth0
   3. Afficher le Domain et le Client ID — copiez-les dans un fichier .env à la racine de votre projet

   Créez un fichier .env avec les valeurs affichées par la CLI :

   Tableau de bord

   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 tableau de bord Auth0
   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 des détails de l’application
   5. Remplacez YOUR_AUTH0_APP_DOMAIN et YOUR_AUTH0_APP_CLIENT_ID dans le fichier .env par les valeurs Domain et Client ID du tableau de bord
   6. Définissez Token Endpoint Authentication Method sur None

   Enfin, dans l’onglet Settings de la page des détails de votre application, configurez les URL suivantes (remplacez YOUR_PACKAGE_ID par votre appId dans capacitor.config.ts) :

   URL de rappel autorisées :

   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
   

   Les URL de rappel autorisées 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’authentification. Sans URL correspondante, le processus de connexion échouera et les utilisateurs seront bloqués sur une page d’erreur Auth0 au lieu d’accéder à votre application.

   Les URL de déconnexion autorisées sont essentielles pour offrir une expérience utilisateur fluide lors de la déconnexion. Sans URL correspondante, les utilisateurs ne seront pas redirigés vers votre application après s’être déconnectés et resteront plutôt sur une page générique d’Auth0.

   Les origines autorisées (capacitor://localhost pour iOS et http://localhost pour Android) sont requises pour que votre application native puisse communiquer avec l’API Auth0.

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

4. Configurer l’Auth0Provider

   Ouvrez src/main.tsx et enveloppez le composant App dans 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 : Obligatoire pour Ionic sur Android et iOS. Les navigateurs mobiles bloquent les témoins tiers; le SDK utilise donc des jetons d’actualisation au lieu d’une authentification silencieuse basée sur des iframes.
   • useRefreshTokensFallback : Doit être défini à false pour empêcher le SDK de tenter une authentification silencieuse basée sur des iframes, qui n’est pas offerte sur mobile.
   • authorizationParams.redirect_uri : Utilise l’identifiant de votre package comme schéma d’URL personnalisé afin que le système d’exploitation puisse rediriger le rappel Auth0 vers votre application.

   Pour conserver l’authentification après la fermeture et la réouverture de l’application, il peut être utile de définir cacheLocation sur localstorage, mais sachez qu’il existe des risques à stocker des jetons dans localstorage. Avec Capacitor, localstorage doit être considéré comme transitoire — le système d’exploitation peut l’effacer sans préavis. Consultez les directives de Capacitor sur le stockage.

   Nous recommandons de ne pas utiliser le plugin Preferences de Capacitor pour stocker des jetons, car il s’appuie 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 des implémentations de cache personnalisées si vous avez besoin d’un mécanisme de stockage plus sécuritaire et persistant.

5. Créer les gestionnaires de connexion, de déconnexion, de profil et de rappel

   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 plugiciel Browser de Capacitor pour ouvrir les pages de connexion et de déconnexion d’Auth0 dans le 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 via 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 le navigateur par défaut de l’appareil. En configurant openUrl pour utiliser Browser.open, le processus d’authentification reste dans le contexte de votre application, ce qui améliore l’expérience utilisateur.

6. Exécutez votre application

   Testez d’abord dans le navigateur

   ionic serve
   

   Lors de l’exécution dans le navigateur avec ionic serve, la redirection du 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 faire des tests dans le navigateur, remplacez temporairement redirect_uri par http://localhost:8100 dans src/main.tsx et ajoutez http://localhost:8100 aux Allowed Callback URLs et aux Allowed Logout URLs de votre application Auth0 dans le tableau de bord. N’oubliez pas de rétablir ce changement avant de créer la version native.

   Pour l’exécuter 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 exécuter l’application dessus. Cette opération n’est requise qu’une seule fois par plateforme. Ensuite, npx cap sync copie vos ressources Web compilées et met à jour les plugins natifs.

Point de contrôle

Vous devriez maintenant disposer d’une connexion Auth0 entièrement fonctionnelle dans votre application Ionic. Sur un appareil, appuyer sur « Log in » ouvre la page de connexion universelle d’Auth0 dans le navigateur système et, 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 URI de rappel d’Auth0 fonctionnent sur les appareils, enregistrez l’identifiant 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 <activity> principal 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 la valeur réelle de appId 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.

Protection des routes avec Ionic Router

Utilisez l’état d’authentification d’Auth0 pour protéger certaines routes dans 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 rappel 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 page de connexion d’Auth0 lorsqu’ils tentent d’accéder à une route protégée.

Appeler des API protégées

Configurez votre Auth0Provider de façon à inclure une audience d’API, puis 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>

Ensuite, effectuez des appels authentifiés à l’API à partir de 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}>Appeler l’API protégée</IonButton>
      {result && (
        <IonText>
          <pre>{result}</pre>
        </IonText>
      )}
    </div>
  );
};

export default ApiCall;