Intégration auth0-net-ios

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

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

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

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

Prérequis

• .NET 8.0 SDK ou version ultérieure (.NET 9 également supporté — utilisez le framework cible net9.0-ios)
• JetBrains Rider ou VS Code avec C# Dev Kit (avec la charge de travail iOS)
• macOS avec Xcode 15+
• Cible de déploiement iOS 14.0+
• Compte Auth0 avec une application Native configurée
• Node.js 20+ (pour la configuration automatisée Auth0 CLI)

Quand NE PAS l'utiliser

Flux de démarrage rapide

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

1. Identifiez la version .NET dans 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 s'ils sont trouvés (réutilisez les éléments UI existants comme les boutons de connexion plutôt que d'en créer des doublons)
3. Notez l'identifiant de bundle du projet à partir de Info.plist ou .csproj
4. Recherchez toute utilisation existante d'Auth0Client ou Auth0ClientOptions pour éviter une configuration en doublon

1. Installez le SDK : dotnet add package Auth0.OidcClient.iOS
2. Configurez Auth0 : Consultez le Guide de configuration pour une configuration automatique ou manuelle.
3. Intégrez l'authentification : Ajoutez l'instanciation d'Auth0Client, enregistrez le schéma URL dans Info.plist, et connectez la connexion/déconnexion aux actions UI.
4. Gérez le callback : Implémentez OpenUrl dans AppDelegate et appelez ActivityMediator.Instance.Send(url.AbsoluteString).
5. Générez et vérifiez : dotnet build

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

• Le SDK iOS ne nécessite PAS de passer un contexte Activity — juste new Auth0Client(options).
• Définissez toujours Scope = "openid profile email offline_access" — la portée offline_access est requise pour recevoir les tokens de rafraîchissement, permettant le renouvellement silencieux des tokens d'accès sans re-demander à l'utilisateur.
• L'URL de callback est automatiquement dérivée de l'identifiant de bundle : {BundleId}://{domain}/ios/{BundleId}/callback.
• L'identifiant de bundle doit être enregistré en tant que schéma URL dans Info.plist.
• L'AppDelegate doit gérer OpenUrl et appeler ActivityMediator.Instance.Send(url.AbsoluteString).
• Stockez les tokens de manière sécurisée : Après une connexion réussie, persistez l'AccessToken et le RefreshToken en utilisant le Keychain iOS (via le framework Security ou un wrapper comme KeychainAccess). Ne stockez jamais les tokens dans UserDefaults ou uniquement dans des variables en mémoire.

Après la rédaction de la configuration et du code, vérifiez que la génération réussit :

dotnet build

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

WebAuth — Comment fonctionne l'authentification

Le SDK utilise ASWebAuthenticationSession (le navigateur système sécurisé). Quand LoginAsync() est appelée :

1. Le SDK construit l'URL /authorize avec les paramètres PKCE (vérificateur de code + challenge)
2. ASWebAuthenticationSession ouvre la page de connexion Auth0
3. L'utilisateur s'authentifie (formulaire de connexion, connexions sociales, MFA, etc.)
4. Auth0 redirige vers l'URL de callback native : {BundleId}://{domain}/ios/{BundleId}/callback
5. iOS intercepte le schéma URL et le remet à AppDelegate.OpenUrl
6. ActivityMediator.Instance.Send(url.AbsoluteString) complète l'échange de tokens
7. Le SDK retourne LoginResult avec le token d'accès, le token ID, le token de rafraîchissement et les revendications de l'utilisateur

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 iOS utilise l'identifiant de bundle comme schéma. Le format est :

YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback

Où YOUR_BUNDLE_IDENTIFIER est l'identifiant de bundle pour votre application, tel que com.mycompany.myapplication. Par exemple : com.mycompany.myapp://tenant.us.auth0.com/ios/com.mycompany.myapp/callback.

Remarque : Certains SDK Auth0 natifs utilisent https://{domain}/ios/{bundleId}/callback ou {bundleId}.auth0://{domain}/ios/{bundleId}/callback comme format d'URL de callback. Le SDK .NET iOS utilise directement l'identifiant de bundle comme schéma URL.

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 (URLs de callback autorisées) et Allowed Logout URLs (URLs de déconnexion autorisées)
2. Enregistrée en tant que schéma URL dans Info.plist sous CFBundleURLSchemes

Fait quand

• [ ] Package Auth0.OidcClient.iOS installé (dernière version stable)
• [ ] Auth0Client configuré avec Domain, ClientId, et Scope = "openid profile email offline_access"
• [ ] Schéma URL enregistré dans Info.plist correspondant à l'identifiant de bundle
• [ ] AppDelegate.OpenUrl implémenté avec ActivityMediator.Instance.Send(url.AbsoluteString)
• [ ] URL de callback ajoutée aux URLs de callback autorisées du tableau de bord Auth0 et aux URLs de déconnexion autorisées
• [ ] Tokens stockés de manière sécurisée en utilisant le Keychain iOS (Security framework avec SecKeyChain.Add)
• [ ] Flux de connexion/déconnexion fonctionnant
• [ ] La génération réussit sans erreurs

Documentation détaillée

• Guide de configuration — Configuration du tenant Auth0, installation du SDK, configuration du schéma URL Info.plist
• Modèles 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 d'Auth0ClientOptions, revendications, liste de contrôle des tests, dépannage

Erreurs courantes

Notes de test

Instruction agent : Rappelez à l'utilisateur de tester sur un appareil physique en plus des simulateurs. Certains comportements de WebAuth/ASWebAuthenticationSession peuvent différer sur les appareils physiques par rapport aux simulateurs. Testez le flux complet de connexion → callback → token sur du matériel réel avant de livrer.

Test sur appareil physique :

• Flux de connexion : ASWebAuthenticationSession s'ouvre → authentification → retour à l'application
• Callback : OpenUrl se déclenche dans AppDelegate avec l'URL correcte
• Flux de déconnexion : Le navigateur s'ouvre → la session est effacée → retour à l'application
• Annulation : L'utilisateur ferme la feuille → l'application gère UserCancel correctement

Skills connexes

• auth0-maui — Applications .NET MAUI multi-plateforme (iOS + Android + Windows)
• auth0-net-android — Applications .NET Android uniquement
• auth0-swift — Applications iOS Swift uniquement
• auth0-aspnetcore-authentication — Applications web côté serveur ASP.NET Core
• auth0-aspnetcore-api — API Web 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"
});

var loginResult = await client.LoginAsync();
BrowserResultType browserResult = await client.LogoutAsync();

Instruction agent : Incluez toujours offline_access dans la portée pour activer les tokens de rafraîchissement. Cela permet à l'application de rafraîchir silencieusement les tokens d'accès sans forcer l'utilisateur à se réauthentifier.

Instruction agent : Après la connexion, persistez toujours les tokens vers le Keychain iOS en utilisant le framework Security (SecKeyChain.Add avec SecAccessible.WhenUnlockedThisDeviceOnly). Ne stockez jamais les tokens dans UserDefaults ou laissez-les uniquement en mémoire. Effacez les tokens à la déconnexion. Consultez Modèles d'intégration pour la classe d'aide complète SecureTokenStorage.

Configuration de plateforme requise

Ces deux éléments sont requis pour que le callback fonctionne — consultez le Guide de configuration pour le code complet :

1. Info.plist : Ajoutez une entrée CFBundleURLSchemes correspondant à l'identifiant de bundle
2. AppDelegate : Remplacez OpenUrl et appelez ActivityMediator.Instance.Send(url.AbsoluteString)

Pour la connexion avec des paramètres supplémentaires, la gestion d'erreurs, le rafraîchissement des tokens, l'accès aux revendications utilisateur et des exemples complets de ViewController, consultez Modèles d'intégration.

Références

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