Intégration Auth0 Ionic Angular (Capacitor)

Ajoutez l'authentification à une application Ionic Angular en utilisant le SDK @auth0/auth0-angular avec les plugins Capacitor pour iOS et Android natifs. Cette compétence couvre la connexion, la déconnexion, l'affichage du profil utilisateur et la gestion sécurisée des tokens via le navigateur système (SFSafariViewController sur iOS, Chrome Custom Tabs sur Android) via le plugin Browser de Capacitor.

Instruction agent : Avant de fournir les instructions de configuration du SDK, récupérez la dernière version en exécutant :

gh api repos/auth0/auth0-angular/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendance au lieu de toute version en dur ci-dessous.

Prérequis

• Node.js 20+ et npm 10+
• Ionic CLI (npm install -g @ionic/cli)
• Capacitor 5+ configuré dans le projet
• Auth0 CLI (pour la configuration automatique) : brew install auth0/auth0-cli/auth0
• Un compte Auth0 (la version gratuite fonctionne)

Quand NE PAS utiliser

Workflow de démarrage rapide

Instruction agent : Suivez ces étapes dans l'ordre. Toujours utiliser AskUserQuestion pour laisser le développeur choisir entre la configuration automatique et la configuration manuelle avant de continuer — même si les identifiants sont déjà fournis dans le prompt.

SÉCURITÉ — Ne jamais afficher les identifiants : Après avoir obtenu les identifiants Auth0 (domaine, ID client) via la CLI ou depuis un fichier, NE JAMAIS les afficher, les imprimer ou les afficher dans votre sortie texte. Écrivez-les directement dans le fichier de configuration (src/environments/environment.ts) silencieusement. NE PRODUISEZ PAS de sortie comme « Domaine : xxx » ou « ID client : yyy ». À la place, confirmez que le fichier de configuration a été écrit et indiquez à l'utilisateur où le trouver.

Réutilisation UI : Avant de créer de nouveaux composants login/logout, recherchez dans le projet existant les gestionnaires ou boutons login/logout. S'ils existent, connectez Auth0 à l'interface utilisateur existante plutôt que de créer des composants en double.

Étape 1 : Installer les dépendances

npm install @auth0/auth0-angular @capacitor/browser @capacitor/app

Étape 2 : Configurer Auth0

Instruction agent : Toujours présenter le choix de configuration en utilisant AskUserQuestion — même si l'utilisateur a déjà fourni des identifiants :

AskUserQuestion:
  question: "Comment souhaitez-vous configurer Auth0 pour votre application Ionic Angular ?"
  options:
    - label: "Configuration automatique (recommandée)"
      description: "Utilise la CLI Auth0 pour créer une application Native, configurer les URL de rappel et stocker les identifiants dans votre projet automatiquement."
    - label: "Configuration manuelle"
      description: "Vous fournissez un fichier .env avec votre domaine Auth0 et votre ID client, et l'agent le lit et écrit la configuration du projet pour vous."

Suivez le chemin choisi dans le Guide de configuration qui contient les instructions détaillées étape par étape pour les deux options.

Paramètres du tableau de bord Auth0 (type d'application Native) :

Remplacez PACKAGE_ID par votre appId de capacitor.config.ts (par exemple, com.example.myapp) et YOUR_DOMAIN par votre domaine Auth0.

Remarque : Pour la configuration automatique, ces URL sont configurées automatiquement par la CLI Auth0. Pour la configuration manuelle, l'utilisateur doit les configurer dans le tableau de bord Auth0.

Remarque : Pour le développement web local (ionic serve), ajoutez également http://localhost:8100 aux URL de rappel autorisées, URL de déconnexion autorisées et origines web autorisées.

Étape 3 : Configurer le SDK

Dans src/app/app.module.ts (NgModule) ou src/app/app.config.ts (standalone) :

La fonction provideAuth0() (ou AuthModule.forRoot()) est l'équivalent Angular de Auth0Provider — elle agit comme le provider/wrapper qui enveloppe l'app et rend AuthService disponible partout. Pour le développement web local avec ionic serve, l'URL de callback est http://localhost:8100.

Standalone (Angular 17+) :

import { ApplicationConfig } from '@angular/core';
import { provideAuth0 } from '@auth0/auth0-angular';

// Remplacez par votre appId de capacitor.config.ts et votre domaine Auth0
const appId = 'com.example.myapp';
const domain = 'YOUR_AUTH0_DOMAIN';
const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;

export const appConfig: ApplicationConfig = {
  providers: [
    provideAuth0({
      domain,
      clientId: 'YOUR_AUTH0_CLIENT_ID',
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri: callbackUri,
      },
    }),
  ],
};

NgModule (Angular 16 et versions antérieures) :

import { AuthModule } from '@auth0/auth0-angular';

const appId = 'com.example.myapp';
const domain = 'YOUR_AUTH0_DOMAIN';
const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;

@NgModule({
  imports: [
    AuthModule.forRoot({
      domain,
      clientId: 'YOUR_AUTH0_CLIENT_ID',
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri: callbackUri,
      },
    }),
  ],
})
export class AppModule {}

Étape 4 : Gérer les callbacks de deep link (AppComponent)

Enregistrez le listener appUrlOpen à la racine de l'app pour qu'il persiste lors de la navigation :

import { Component, NgZone, OnInit } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { Browser } from '@capacitor/browser';
import { App as CapApp } from '@capacitor/app';
import { mergeMap } from 'rxjs/operators';

@Component({
  selector: 'app-root',
  template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`,
})
export class AppComponent implements OnInit {
  constructor(
    private auth: AuthService,
    private ngZone: NgZone
  ) {}

  ngOnInit() {
    CapApp.addListener('appUrlOpen', ({ url }) => {
      this.ngZone.run(() => {
        if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
          this.auth
            .handleRedirectCallback(url)
            .pipe(mergeMap(() => Browser.close()))
            .subscribe();
        }
      });
    });
  }
}

Étape 5 : Implémenter la connexion

import { Component } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { Browser } from '@capacitor/browser';

@Component({
  selector: 'app-login',
  template: `<ion-button (click)="login()">Se connecter</ion-button>`,
})
export class LoginPage {
  constructor(public auth: AuthService) {}

  login() {
    this.auth
      .loginWithRedirect({
        async openUrl(url: string) {
          await Browser.open({ url, windowName: '_self' });
        },
      })
      .subscribe();
  }
}

Étape 6 : Implémenter la déconnexion

import { Component } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { Browser } from '@capacitor/browser';

@Component({
  selector: 'app-logout-button',
  template: `<ion-button (click)="logout()">Se déconnecter</ion-button>`,
})
export class LogoutButtonComponent {
  constructor(public auth: AuthService) {}

  logout() {
    this.auth
      .logout({
        logoutParams: {
          returnTo: `YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback`,
        },
        async openUrl(url: string) {
          await Browser.open({ url, windowName: '_self' });
        },
      })
      .subscribe();
  }
}

Étape 7 : Afficher le profil utilisateur

import { Component } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { AsyncPipe } from '@angular/common';

@Component({
  selector: 'app-profile',
  template: `
    <div *ngIf="auth.user$ | async as user">
      <img [src]="user.picture" [alt]="user.name" />
      <h2>{{ user.name }}</h2>
      <p>{{ user.email }}</p>
    </div>
  `,
})
export class ProfileComponent {
  constructor(public auth: AuthService) {}
}

Étape 8 : Compiler et tester

Instruction agent : Après avoir écrit tout le code, vérifiez que la compilation réussit :

npm run build
npx cap sync

Si la compilation échoue, enquêtez sur les erreurs et corrigez-les (jusqu'à 5-6 itérations). Si elle échoue toujours, utilisez AskUserQuestion pour demander de l'aide à l'utilisateur.

Documentation détaillée

• Guide de configuration — Configuration Auth0, configuration CLI Auth0, configuration de plateforme Capacitor, deep linking
• Modèles d'intégration — Flux login/logout, gestion des tokens, profil utilisateur, gestion des erreurs, cycle de vie Capacitor
• Référence API et tests — API AuthService, options de configuration, référence des claims, checklist de test

Erreurs courantes

Méthode WebAuth

Ionic avec Capacitor utilise la méthode Web Auth pour l'authentification :

1. L'utilisateur appuie sur Se connecter → l'app appelle loginWithRedirect avec un openUrl personnalisé qui utilise Browser.open()
2. Le plugin Browser de Capacitor ouvre la page Auth0 Universal Login dans le navigateur système (SFSafariViewController / Chrome Custom Tabs)
3. L'utilisateur s'authentifie → Auth0 redirige vers le callback du schéma d'URL personnalisé
4. L'OS achemine le deep link vers votre app → l'événement appUrlOpen se déclenche
5. handleRedirectCallback(url) traite l'échange de code d'authentification à l'intérieur de ngZone.run()
6. Browser.close() ferme le navigateur système
7. auth.isAuthenticated$ émet true, et auth.user$ émet le profil utilisateur

Compétences connexes

• auth0-ionic-react — Ionic React avec Capacitor
• auth0-ionic-vue — Ionic Vue avec Capacitor
• auth0-angular — Angular SPA (navigateur uniquement)
• auth0-swift — iOS natif (Swift)
• auth0-android — Android natif (Kotlin)

Référence rapide

Références

• Auth0 Angular SDK — GitHub
• Auth0 Ionic Angular Quickstart
• Auth0 Angular SDK — Référence API
• Plugin Capacitor Browser
• Plugin Capacitor App — Deep Links
• Framework Ionic — Angular