Intégration auth0-maui

Ajoutez l'authentification Auth0 aux applications .NET MAUI ciblant iOS, Android, macOS et Windows. Cette skill intègre le package NuGet Auth0.OidcClient.MAUI qui utilise le navigateur système via le WebAuthenticator de MAUI pour des flux de connexion et déconnexion sécurisés basés sur OIDC avec PKCE.

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

gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("maui-")) | .tag_name | ltrimstr("maui-")] | .[0]'

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

Prérequis

• .NET 8.0 SDK ou ultérieur
• Visual Studio 2022 (17.8+) avec workload MAUI, ou JetBrains Rider avec support MAUI
• Pour iOS : macOS avec Xcode 15+
• Pour Android : Android SDK API 33+ (net8.0) ou API 34+ (net9.0)
• Pour Windows : Windows 10 (10.0.19041.0)+
• Compte Auth0 avec une application Native configurée
• Node.js 20+ (pour la configuration automatisée d'Auth0 CLI)

Quand NE PAS utiliser

Flux de démarrage rapide

Instruction agent : Avant de commencer, examinez le projet de l'utilisateur :

1. Identifiez la version .NET du fichier .csproj (TargetFrameworks)
2. Vérifiez les implémentations d'authentification existantes — recherchez les gestionnaires de connexion/déconnexion existants et connectez-vous à eux s'ils existent
3. Notez l'espace de noms et les conventions de répertoire du projet
4. Cherchez l'utilisation existante de Auth0Client ou Auth0ClientOptions pour éviter la duplication de configuration

1. Installer le SDK : dotnet add package Auth0.OidcClient.MAUI
2. Configurer Auth0 : Consultez le Guide de configuration pour une configuration automatique ou manuelle.
3. Intégrer l'authentification : Ajoutez l'instantiation de Auth0Client et connectez la connexion/déconnexion aux actions de l'interface.
   • IMPORTANT : Définissez toujours Scope = "openid profile email offline_access" — l'étendue offline_access est requise pour recevoir un refresh token pour le renouvellement de token silencieux.
4. Persister les tokens avec SecureStorage : Après la connexion, stockez le refresh token en utilisant await SecureStorage.Default.SetAsync("refresh_token", loginResult.RefreshToken). Au démarrage de l'application, restaurez la session avec RefreshTokenAsync. Effacez à la déconnexion avec SecureStorage.Default.Remove("refresh_token").
5. Enregistrer le schéma d'URL : Configurez la gestion des callbacks spécifique à la plateforme :
   • Android : Créez WebAuthenticatorActivity avec IntentFilter pour votre schéma personnalisé (p. ex., myapp)
   • Windows (deux étapes requises) : (1) Ajoutez <uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension> à Platforms/Windows/Package.appxmanifest, ET (2) appelez Activator.Default.CheckRedirectionActivation() dans Platforms/Windows/App.xaml.cs
   • iOS/macOS : Aucune configuration supplémentaire requise
6. Créer et vérifier : dotnet build

Instruction agent : Lors de l'écriture de la configuration d'Auth0Client :

• TOUJOURS inclure offline_access dans la chaîne Scope — sans cela, aucun refresh token n'est retourné et l'utilisateur doit se réauthentifier à chaque expiration du token d'accès.
• TOUJOURS implémenter la persistance des tokens en utilisant SecureStorage.Default.SetAsync("refresh_token", ...) après la connexion et SecureStorage.Default.GetAsync("refresh_token") au démarrage de l'application pour restaurer les sessions silencieusement.
• Effacez les tokens stockés à la déconnexion avec SecureStorage.Default.Remove("refresh_token").
• TOUJOURS créer/mettre à jour Platforms/Windows/Package.appxmanifest pour enregistrer le protocole de schéma d'URL personnalisé. Sans cela, Windows n'interceptera pas l'URL de callback après l'authentification. Ajoutez une <uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension> dans l'élément <Extensions> du nœud <Application>.
• TOUJOURS ajouter CheckRedirectionActivation() dans Platforms/Windows/App.xaml.cs comme première ligne du constructeur, avant InitializeComponent().

Après l'écriture de la configuration et du code, vérifiez que la création réussit :

dotnet build

Si la création échoue, tentez de corriger le problème. Après 5-6 tentatives échouées, demandez à l'utilisateur de l'aide.

Configuration de l'URL de callback

Le SDK MAUI utilise un schéma d'URL personnalisé pour les callbacks. Le modèle par défaut est :

myapp://callback

Contrairement aux autres SDKs natifs Auth0 qui utilisent des modèles https://{domain}/{platform}/{bundleId}/callback ou {bundleId}.auth0://{domain}/ios/{bundleId}/callback, MAUI utilise une approche de schéma personnalisé plus simple. Vous pouvez personnaliser le schéma (p. ex., com.mycompany.myapp://callback). Quel que soit le schéma choisi, il doit :

1. Être enregistré dans le tableau de bord Auth0 sous Allowed Callback URLs et Allowed Logout URLs
2. Être configuré dans le gestionnaire de callback spécifique à la plateforme (Android IntentFilter, Windows Package.appxmanifest)
3. Être défini dans Auth0ClientOptions.RedirectUri et Auth0ClientOptions.PostLogoutRedirectUri

Remarque : Pour les applications de production, utilisez un schéma de domaine inverse (p. ex., com.yourcompany.yourapp://callback) pour réduire le risque d'usurpation de schéma d'URL.

Terminé quand

• [ ] Package Auth0.OidcClient.MAUI installé
• [ ] Auth0Client configuré avec Domain, ClientId et Scope incluant offline_access
• [ ] Schéma d'URL enregistré sur Android (WebAuthenticatorCallbackActivity) et Windows (Package.appxmanifest)
• [ ] URL de callback (myapp://callback) ajoutée aux Allowed Callback URLs et Allowed Logout URLs du tableau de bord Auth0
• [ ] Flux de connexion/déconnexion fonctionnant
• [ ] Refresh token persisté via SecureStorage.Default.SetAsync après la connexion
• [ ] Restauration de session implémentée via SecureStorage.Default.GetAsync + RefreshTokenAsync au démarrage de l'application
• [ ] Création réussie sans erreurs
• [ ] Testé sur appareil physique ou émulateur/simulateur

Documentation détaillée

• Guide de configuration — Configuration du tenant Auth0, installation du SDK, configuration des callbacks spécifiques à la plateforme
• Modèles d'intégration — Flux de connexion/déconnexion, renouvellement de token, profil utilisateur, gestion des erreurs, modèles MVVM
• Référence API et test — Référence complète de Auth0ClientOptions, claims, liste de contrôle de test, dépannage

Erreurs courantes

Notes de test

Instruction agent : Rappelez à l'utilisateur de tester sur un appareil physique en plus des émulateurs/simulateurs. Certains comportements de WebAuthenticator (intégration du navigateur système, interception du schéma d'URL) peuvent différer sur les appareils physiques par rapport aux émulateurs. Testez le flux complet connexion → callback → token sur du matériel réel avant le lancement.

Liste de contrôle de test :

• Flux de connexion : Le navigateur système s'ouvre → authentification → retour à l'application
• Flux de déconnexion : Le navigateur s'ouvre → session effacée → retour à l'application
• Renouvellement de token : RefreshTokenAsync avec refresh token stocké fonctionne
• Annulation : L'utilisateur annule la connexion → l'application traite UserCancel correctement
• Appareil physique : Testez sur un vrai appareil iOS/Android (pas seulement le simulateur)
• Hors ligne : Vérifiez que le renouvellement de token fonctionne lors du redémarrage de l'application
• Multi-plateforme : Testez sur au moins une plateforme mobile (iOS ou Android) et Windows

Skills connexes

• auth0-aspnetcore-authentication — Applications web ASP.NET Core côté serveur
• auth0-aspnetcore-api — ASP.NET Core Web API avec validation JWT
• auth0-android — Applications Android natives Kotlin
• auth0-swift — Applications iOS/macOS Swift
• auth0-react-native — Applications mobiles React Native
• auth0-net-android-ios — .NET Android/iOS (non-MAUI)

Référence rapide

using Auth0.OidcClient;

// Initialiser le client
var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    RedirectUri = "myapp://callback",
    PostLogoutRedirectUri = "myapp://callback",
    Scope = "openid profile email offline_access"
});

// Connexion — ouvre le navigateur système
var loginResult = await client.LoginAsync();
if (!loginResult.IsError)
{
    var user = loginResult.User;
    var accessToken = loginResult.AccessToken;
    var idToken = loginResult.IdentityToken;
    var refreshToken = loginResult.RefreshToken;

    // Accéder aux claims de l'utilisateur
    var name = user.FindFirst("name")?.Value;
    var email = user.FindFirst("email")?.Value;

    // Persister le refresh token de manière sécurisée pour la restauration de session
    if (!string.IsNullOrEmpty(refreshToken))
        await SecureStorage.Default.SetAsync("refresh_token", refreshToken);
}

// Déconnexion — efface la session Auth0 et les tokens stockés
await client.LogoutAsync();
SecureStorage.Default.Remove("refresh_token");

// Restaurer la session au démarrage de l'application (aucune interaction utilisateur requise)
var savedToken = await SecureStorage.Default.GetAsync("refresh_token");
if (!string.IsNullOrEmpty(savedToken))
{
    var refreshResult = await client.RefreshTokenAsync(savedToken);
    if (!refreshResult.IsError)
    {
        var newAccessToken = refreshResult.AccessToken;
        // Mettre à jour le token stocké s'il a été pivoté
        if (!string.IsNullOrEmpty(refreshResult.RefreshToken))
            await SecureStorage.Default.SetAsync("refresh_token", refreshResult.RefreshToken);
    }
    else
    {
        // L'actualisation a échoué — effacez et exigez une nouvelle connexion
        SecureStorage.Default.Remove("refresh_token");
    }
}

// Obtenir les informations utilisateur depuis l'endpoint /userinfo
var userInfo = await client.GetUserInfoAsync(accessToken);

// Connexion avec paramètres supplémentaires (organization, audience, connection)
var orgLogin = await client.LoginAsync(new { organization = "org_abc123" });
var apiLogin = await client.LoginAsync(new { audience = "https://my-api.example.com" });

Activité de callback Android (requise)

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "myapp";
}

Configuration de plateforme Windows (requise — les deux étapes)

Étape 1 : Enregistrer le protocole dans Platforms/Windows/Package.appxmanifest :

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="myapp"/>
  </uap:Extension>
</Extensions>

Étape 2 : Gérer la redirection dans Platforms/Windows/App.xaml.cs :

// Dans Platforms/Windows/App.xaml.cs
public App()
{
    if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
        return;
    this.InitializeComponent();
}

Références

• Démarrage rapide Auth0 MAUI
• Dépôt GitHub
• Package NuGet
• Documentation de l'API du SDK
• Documentation Auth0 Native App