Intégration Auth0 Swift

Auth0.swift est le SDK Auth0 officiel pour les plateformes Apple (iOS, macOS, tvOS, watchOS, visionOS). Cette skill ajoute une authentification native complète aux applications Swift via Web Auth (redirection du navigateur système), stockage sécurisé des identifiants Keychain via CredentialsManager, et protection biométrique optionnelle.

Agent instruction: 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.swift/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendance au lieu de la version codée en dur ci-dessous. Version actuellement connue : 2.18.0.

Quand NE PAS utiliser

• Applications Android : Utilisez auth0-android
• Applications React Native : Utilisez auth0-react-native
• Applications Flutter : Utilisez le SDK Auth0 Flutter natif
• SPAs Web (React, Angular, Vue) : Utilisez auth0-react, auth0-angular, ou auth0-vue
• Serveurs Node.js/Express : Utilisez auth0-express

Prérequis

• iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
• Xcode 16.x
• Swift 6.0+
• Compte Auth0 — S'inscrire gratuitement
• Node.js 20+ (pour l'automatisation du script bootstrap)
• Auth0 CLI — brew install auth0/auth0-cli/auth0 (pour le script bootstrap)

Workflow Démarrage Rapide

Agent instruction: Suivez ces étapes dans l'ordre. Si vous rencontrez une erreur à une étape, tentez de la corriger jusqu'à 5 fois avant d'appeler AskUserQuestion pour demander des conseils à l'utilisateur. Cherchez toujours le code existant d'abord — s'il y a des gestionnaires login/logout existants, connectez-vous à eux plutôt que de créer de nouveaux.

Étape 1 — Installer le SDK

Agent instruction: Vérifiez le répertoire du projet pour un fichier gestionnaire de paquets existant :

• Podfile présent → CocoaPods
• Cartfile présent → Carthage
• Package.swift présent → Swift Package Manager

Si aucun n'est trouvé, posez la question via AskUserQuestion : "Quel gestionnaire de dépendances votre projet utilise-t-il — Swift Package Manager, CocoaPods, ou Carthage ?"

Swift Package Manager — projet Package.swift: Exécutez cette commande à la racine du projet pour ajouter la dépendance automatiquement, puis ajoutez "Auth0" au tableau dependencies de la cible dans Package.swift :

swift package add-dependency https://github.com/auth0/Auth0.swift --from 2.18.0

Swift Package Manager — projet Xcode (.xcodeproj, sans Package.swift): La commande CLI ne s'applique pas. Instruisez l'utilisateur à ajouter le paquet via Xcode : File → Add Package Dependencies → https://github.com/auth0/Auth0.swift → Up to Next Major Version depuis 2.18.0.

CocoaPods ou Carthage: Suivez les étapes d'installation correspondantes dans le Guide de Configuration. Ne montrez pas juste les instructions — effectuez les modifications de fichiers et exécutez les commandes.

Étape 2 — Configurer Auth0

Agent instruction:

• Si les identifiants Auth0 (domaine ET ID client) sont déjà dans la demande de l'utilisateur: Écrivez Auth0.plist directement avec ces valeurs et passez à l'Étape 3.
• Si aucun identifiant n'est fourni: Exécutez le script bootstrap — NE DEMANDEZ PAS à l'utilisateur de créer ou configurer manuellement une application Auth0. Utilisez toujours le chemin CLI.

Suivez le Guide de Configuration — Configuration Auth0 pour les vérifications préalables et la commande du script.

Étape 3 — Configurer les URLs de Callback

Agent instruction:

1. Lisez Auth0.plist pour obtenir ClientId et Domain.
2. Extrayez l'identifiant du bundle depuis project.pbxproj : recherchez PRODUCT_BUNDLE_IDENTIFIER, ignorez les valeurs contenant $( ou Tests.
3. Posez la question à l'utilisateur via AskUserQuestion : "Quel schéma d'URL de callback souhaitez-vous utiliser ?"
   • Schéma personnalisé ({bundle}://) — plus simple, fonctionne sur toutes les plateformes Apple
   • HTTPS Universal Links — recommandé pour la production; prévient le détournement de schéma d'URL

Puis suivez uniquement le chemin correspondant ci-dessous.

Chemin A — Schéma Personnalisé

Agent instruction: Enregistrez les URLs de callback en utilisant Auth0 CLI (substituez les vraies valeurs pour CLIENT_ID, BUNDLE_ID, DOMAIN) :

auth0 apps update CLIENT_ID \
  --callbacks "BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --logout-urls "BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --no-input

Puis suivez les étapes d'enregistrement du schéma d'URL dans le Guide de Configuration pour enregistrer $(PRODUCT_BUNDLE_IDENTIFIER) comme type d'URL dans Xcode.

Chemin B — HTTPS Universal Links

Agent instruction: Les quatre étapes ci-dessous sont obligatoires — ignorer ne serait-ce qu'une seule causera l'échouement silencieux de la redirection de callback après la connexion.

Étape B1 — Enregistrer les URLs de callback via Auth0 CLI: Enregistrez à la fois le schéma HTTPS et personnalisé pour que l'application fonctionne dans tous les scénarios :

auth0 apps update CLIENT_ID \
  --callbacks "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --logout-urls "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --no-input

Étape B2 — Configurer les Paramètres d'Appareil via Auth0 CLI: Extrayez DEVELOPMENT_TEAM depuis project.pbxproj (valeur de 10 caractères, par ex. ABC12DE34F). Si introuvable, posez la question via AskUserQuestion : "Quel est votre Apple Team ID ? (developer.apple.com → Account → Membership Details)"

auth0 api patch applications/CLIENT_ID \
  --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
  --no-input

Auth0 hébergera maintenant automatiquement https://DOMAIN/.well-known/apple-app-site-association — requis pour que les Universal Links fonctionnent sur l'appareil.

Étape B3 — Ajouter l'entitlement Associated Domains dans Xcode: Ajoutez com.apple.developer.associated-domains au fichier .entitlements de l'application avec les entrées applinks: et webcredentials: pour le domaine Auth0. Consultez le Guide de Configuration — Associated Domains pour le XML des entitlements complet, les étapes de capacité Xcode, et la vérification des paramètres de build.

Étape B4 — Utiliser .useHTTPS() dans le SDK:

Auth0.webAuth().useHTTPS()

Étape 4 — Implémenter l'Authentification

Agent instruction: Cherchez dans le projet @main struct (SwiftUI) ou AppDelegate/UIViewController (UIKit) pour détecter le framework d'interface. Si ambigu, posez la question via AskUserQuestion : "Votre application utilise-t-elle SwiftUI ou UIKit ?" Puis suivez uniquement le chemin correspondant ci-dessous.

SwiftUI

Agent instruction: Créez AuthenticationService.swift comme un ObservableObject, puis connectez-le au point d'entrée de l'application et à la vue racine. Cherchez la struct @main et ContentView (ou vue racine équivalente) et mettez-les à jour comme montré.

// AuthenticationService.swift
import Auth0
import Combine

class AuthenticationService: ObservableObject {
    @Published var isAuthenticated = false
    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())

    init() { isAuthenticated = credentialsManager.canRenew() }

    func login() async {
        do {
            let credentials = try await Auth0
                .webAuth()
                .useHTTPS()
                .scope("openid profile email offline_access")
                .start()
            _ = credentialsManager.store(credentials: credentials)
            await MainActor.run { isAuthenticated = true }
        } catch WebAuthError.userCancelled { }
        catch { print("Login failed: \(error)") }
    }

    func logout() async {
        do { try await Auth0.webAuth().useHTTPS().clearSession() }
        catch { print("Logout failed: \(error)") }
        _ = credentialsManager.clear()
        await MainActor.run { isAuthenticated = false }
    }
}

// @main App struct — injecter AuthenticationService comme environment object
@StateObject private var auth = AuthenticationService()
// Dans body: ContentView().environmentObject(auth)

// Root ContentView — brancher sur l'état d'authentification
@EnvironmentObject var auth: AuthenticationService
// Dans body: if auth.isAuthenticated { HomeView() } else { LoginView() }

Pour le câblage complet du cycle de vie des applications SwiftUI, consultez les Modèles d'Intégration.

UIKit

Agent instruction: Créez AuthenticationService.swift comme une classe ordinaire, puis ajoutez les appels login/logout au UIViewController pertinent. Vérifiez aussi si l'application utilise SFSafariViewController — si c'est le cas, ajoutez WebAuthentication.resume(with:) à AppDelegate/SceneDelegate (voir note ci-dessous).

// AuthenticationService.swift
import Auth0

class AuthenticationService {
    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())

    var isAuthenticated: Bool { credentialsManager.canRenew() }

    func login() async throws {
        let credentials = try await Auth0
            .webAuth()
            .useHTTPS()
            .scope("openid profile email offline_access")
            .start()
        _ = credentialsManager.store(credentials: credentials)
    }

    func logout() async throws {
        try await Auth0.webAuth().useHTTPS().clearSession()
        _ = credentialsManager.clear()
    }
}

// Dans votre UIViewController
private let auth = AuthenticationService()

@IBAction func loginTapped(_ sender: UIButton) {
    Task {
        do {
            try await auth.login()
            await MainActor.run { navigateToHome() }
        } catch WebAuthError.userCancelled { }
        catch { print("Login failed: \(error)") }
    }
}

@IBAction func logoutTapped(_ sender: UIButton) {
    Task {
        do { try await auth.logout() }
        catch { print("Logout failed: \(error)") }
        await MainActor.run { navigateToLogin() }
    }
}

Note — SFSafariViewController uniquement: Si l'application utilise .provider(WebAuthentication.safariProvider()) au lieu de la session ASWebAuthenticationSession par défaut, ajoutez WebAuthentication.resume(with: url) à AppDelegate.application(_:open:url:options:) et SceneDelegate.scene(_:openURLContexts:). Consultez les Modèles d'Intégration pour le code exact.

Étape 5 — Vérifier la Build

Agent instruction: Exécutez une build pour vérifier que l'intégration se compile sans erreurs :

xcodebuild build -scheme YOUR_SCHEME -destination "platform=iOS Simulator,name=iPhone 16"

Si la build échoue, examinez les messages d'erreur et corrigez jusqu'à 5 fois avant de demander à l'utilisateur.

Documentation Détaillée

• Guide de Configuration — Configuration du Tableau de Bord Auth0, script bootstrap, configuration manuelle, enregistrement du schéma d'URL, installation CocoaPods/SPM/Carthage
• Modèles d'Intégration — Web Auth login/logout, CredentialsManager, protection biométrique, MFA, organisations, gestion d'erreurs, modèles SwiftUI/UIKit
• Référence API & Tests — Référence API complète, options de configuration, référence des claims, liste de contrôle de test, dépannage

Erreurs Courantes

Références

• Auth0.swift GitHub
• Quickstart iOS/macOS
• Documentation API Auth0.swift
• Tableau de Bord Auth0
• EXAMPLES.md