Intégration auth0-net-android

Ajoutez l'authentification Auth0 aux applications .NET Android. Cette skill intègre le package NuGet Auth0.OidcClient.AndroidX qui utilise Chrome Custom Tabs pour des flux de connexion et déconnexion OIDC sécurisés avec PKCE.

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

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

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

Prérequis

• .NET 8.0 SDK ou version ultérieure
• Visual Studio 2022 (17.8+) avec la charge de travail .NET Android, ou JetBrains Rider
• Android SDK API 21+ (minimum), API 34+ recommandé pour net9.0-android
• Compte Auth0 avec une application Native configurée
• Node.js 20+ (pour la configuration automatisée via Auth0 CLI)

Quand NE PAS utiliser

Flux de démarrage rapide

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

1. Identifiez la version .NET depuis le fichier .csproj (TargetFramework)
2. Vérifiez les implémentations d'authentification existantes — recherchez les gestionnaires de connexion/déconnexion existants et intégrez-vous à eux si trouvés (réutilisez les éléments d'interface existants comme les boutons de connexion plutôt que de créer des doublons)
3. Notez l'espace de noms du projet et le nom du package depuis le .csproj ou AndroidManifest.xml
4. Cherchez les utilisations existantes de Auth0Client ou Auth0ClientOptions pour éviter une configuration dupliquée

1. Installez le SDK : dotnet add package Auth0.OidcClient.AndroidX
2. Configurez Auth0 : Voir le Guide de configuration pour une configuration automatique ou manuelle.
3. Intégrez l'authentification : Ajoutez l'instantiation de Auth0Client, configurez l'IntentFilter sur votre Activity, et connectez la connexion/déconnexion aux actions de l'interface.
4. Gérez le callback : Surchargez OnNewIntent et appelez ActivityMediator.Instance.Send(intent.DataString) pour finaliser le flux d'authentification.
5. Compilez et vérifiez : dotnet build

Instruction d'agent : Lors de la rédaction de la configuration Auth0Client :

• Passez this (l'Activity) comme deuxième argument au constructeur Auth0Client.
• Définissez toujours Scope = "openid profile email offline_access" — la portée offline_access est nécessaire pour recevoir les tokens de rafraîchissement, permettant le renouvellement silencieux des tokens sans redemander à l'utilisateur.
• Le format de l'URL de callback est YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback — tout en minuscules.
• Le DataScheme dans l'IntentFilter doit être en minuscules ou Android ne recevra pas les callbacks.
• Définez LaunchMode = LaunchMode.SingleTask sur l'Activity pour éviter les instances dupliquées. N'utilisez PAS SingleTop — cela ne gère pas correctement la redirection de callback et créera des instances d'Activity dupliquées.
• L'Activity doit soit étendre Auth0ClientActivity SOIT surcharger manuellement OnNewIntent et appeler ActivityMediator.Instance.Send(intent.DataString).
• Stockez les tokens de manière sécurisée : Après une connexion réussie, persistez AccessToken et RefreshToken en utilisant SecureStorage (MAUI/Essentials) ou EncryptedSharedPreferences (AndroidX Security — nécessite dotnet add package Xamarin.AndroidX.Security.SecurityCrypto). Ne stockez jamais les tokens dans SharedPreferences en clair ou uniquement dans des variables en mémoire.

Après avoir écrit la configuration et le code, vérifiez que la compilation réussit :

dotnet build

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

WebAuth — Fonctionnement de l'authentification

Le SDK utilise le motif WebAuth via Chrome Custom Tabs (le navigateur système). Quand LoginAsync() est appelé, le SDK :

1. Construit l'URL /authorize avec les paramètres PKCE
2. Ouvre Chrome Custom Tabs avec l'URL d'autorisation
3. Après authentification, Auth0 redirige vers l'URL de callback native
4. Le système Android fait correspondre le schéma d'URL et le fournit à votre Activity via OnNewIntent
5. ActivityMediator finalise l'échange de tokens

C'est le flux standard OAuth 2.0 Authorization Code avec PKCE, recommandé pour les applications mobiles natives.

Configuration de l'URL de callback

L'URL de callback native pour .NET Android utilise le nom du package comme schéma. Le format est :

YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback

Où YOUR_ANDROID_PACKAGE_NAME est le nom du package pour votre application, tel que com.mycompany.myapplication. Par exemple : com.mycompany.myapp://tenant.us.auth0.com/android/com.mycompany.myapp/callback.

Remarque : Certains SDK natifs Auth0 utilisent https://{domain}/android/{package}/callback comme format d'URL de callback. Le SDK .NET Android utilise le nom du package comme schéma d'URL à la place.

Assurez-vous que l'URL de callback est en minuscules.

Cette URL doit être :

1. Enregistrée dans le tableau de bord Auth0 sous Allowed Callback URLs et Allowed Logout URLs
2. Appairée par les attributs IntentFilter (DataScheme, DataHost, DataPathPrefix) sur votre Activity

Fait quand

• [ ] Package Auth0.OidcClient.AndroidX installé (dernière version stable)
• [ ] Auth0Client configuré avec Domain, ClientId et Scope = "openid profile email offline_access"
• [ ] IntentFilter configuré sur Activity avec DataScheme, DataHost, DataPathPrefix corrects
• [ ] LaunchMode = LaunchMode.SingleTask défini sur l'Activity
• [ ] OnNewIntent géré avec ActivityMediator.Instance.Send(intent.DataString)
• [ ] URL de callback ajoutée aux Allowed Callback URLs et Allowed Logout URLs du tableau de bord Auth0
• [ ] Tokens stockés de manière sécurisée (SecureStorage ou EncryptedSharedPreferences)
• [ ] Flux de connexion/déconnexion fonctionnel
• [ ] La compilation réussit sans erreurs

Documentation détaillée

• Guide de configuration — Configuration du tenant Auth0, installation du SDK, configuration d'IntentFilter
• Motifs d'intégration — Flux de connexion/déconnexion, accès aux tokens, profil utilisateur, gestion d'erreurs
• Référence API & Tests — Référence complète Auth0ClientOptions, claims, liste de vérification des tests, dépannage

Erreurs courantes

Notes de test

Instruction d'agent : Rappelez à l'utilisateur de tester sur un appareil physique en plus des émulateurs. Certains comportements WebAuth (Chrome Custom Tabs, interception de schéma d'URL) peuvent différer sur les appareils physiques par rapport aux émulateurs. Testez le flux complet connexion → callback → tokens sur du matériel réel avant de livrer.

Test sur appareil physique :

• Flux de connexion : Chrome Custom Tab s'ouvre → authentification → retour à l'application
• Callback : OnNewIntent se déclenche avec les données d'intention correctes
• Flux de déconnexion : Navigateur s'ouvre → session effacée → retour à l'application
• Annulation : L'utilisateur appuie sur retour → l'application gère UserCancel correctement

Skills connexes

• auth0-maui — Applications .NET MAUI multi-plateforme (iOS + Android + Windows)
• auth0-net-ios — Applications .NET iOS uniquement
• auth0-android — Applications Android natives en Kotlin
• auth0-aspnetcore-authentication — Applications web serveur ASP.NET Core
• auth0-aspnetcore-api — Web API ASP.NET Core avec validation JWT

Référence rapide

using Auth0.OidcClient;

var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    Scope = "openid profile email offline_access"
}, this);

Connexion

var loginResult = await client.LoginAsync();

Gestion des erreurs

var loginResult = await client.LoginAsync();

if (loginResult.IsError)
{
    Debug.WriteLine($"An error occurred during login: {loginResult.Error}");
}

Tokens d'accès

var loginResult = await client.LoginAsync();

if (!loginResult.IsError)
{
    Debug.WriteLine($"Authentication successful.");
}

Informations utilisateur

if (!loginResult.IsError)
{
    Debug.WriteLine($"name: {loginResult.User.FindFirst(c => c.Type == "name")?.Value}");
    Debug.WriteLine($"email: {loginResult.User.FindFirst(c => c.Type == "email")?.Value}");
}

Lister tous les claims

if (!loginResult.IsError)
{
    foreach (var claim in loginResult.User.Claims)
    {
        Debug.WriteLine($"{claim.Type} = {claim.Value}");
    }
}

Déconnexion

BrowserResultType browserResult = await client.LogoutAsync();

Activity avec IntentFilter (Requis)

[Activity(Label = "AndroidSample", MainLauncher = true, Icon = "@drawable/icon",
    LaunchMode = LaunchMode.SingleTask)]
[IntentFilter(
    new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = "YOUR_ANDROID_PACKAGE_NAME",
    DataHost = "YOUR_AUTH0_DOMAIN",
    DataPathPrefix = "/android/YOUR_ANDROID_PACKAGE_NAME/callback")]
public class MainActivity : Activity
{
    // Code omitted
}

Gestion du callback dans OnNewIntent (Requis)

protected override async void OnNewIntent(Intent intent)
{
    base.OnNewIntent(intent);

    Auth0.OidcClient.ActivityMediator.Instance.Send(intent.DataString);
}

Références

• Démarrage rapide .NET Android & iOS
• Dépôt GitHub
• Package NuGet — Auth0.OidcClient.AndroidX
• Documentation API du SDK