SDK iOS Guardian.swift

Décrit comment installer, utiliser et configurer les options du SDK iOS Guardian.swift.

Guardian.swift vous permet d’intégrer le service multifacteur Guardian d’Auth0 à votre propre application iOS, ce qui transforme celle-ci en second facteur. Vos utilisateurs profiteront de tous les avantages de notre authentification multifacteur sans friction directement dans votre application. Pour en savoir plus, consultez Getting Started with Apple Push Notification Service.

​

Exigences

• iOS 10+ et Swift 4.1 sont requis pour utiliser Guardian.
• Pour utiliser ce SDK, vous devez configurer le service Guardian de votre locataire avec vos propres identifiants de notifications push, sinon vous ne recevrez aucune notification push. Pour en savoir plus, consultez Configurer les notifications push pour MFA.

​

Installer le SDK Guardian pour iOS

​

CocoaPods

Guardian.swift est disponible via CocoaPods. Pour l’installer, ajoutez la ligne suivante à votre Podfile :

pod 'Guardian', '~> 1.1.0'

​

Carthage

Ajoutez cette ligne à votre fichier Cartfile :

github "auth0/Guardian.swift" ~> 1.1.0

​

Activer les notifications push de Guardian

1. Accédez à Dashboard > Security > Multi-factor Auth.
2. Activez Push Notification.
3. Configurez les notifications push.

​

Utilisation

Guardian constitue le cœur du SDK. Pour utiliser le SDK, importez la bibliothèque :

import Guardian

Définissez le domaine de votre locataire. Ou utilisez le domaine personnalisé si vous en avez configuré un pour votre locataire :

let domain = "<tenant>.<region>.auth0.com"

​

Inscrire

Une inscription établit un lien entre le deuxième facteur et un compte Auth0. Lorsqu’un compte est inscrit, vous devrez fournir ce deuxième facteur pour vérifier l’identité. Si votre application n’utilise pas encore les notifications push ou si vous ne connaissez pas bien ce mécanisme, consultez Apple Push Notification Service Overview pour en savoir plus.

Pour effectuer une inscription, vous avez besoin des renseignements suivants, en plus du domaine de votre locataire :

Variable	Description
URI d’inscription	Valeur codée dans le code QR numérisé à partir du Guardian Web Widget ou dans votre ticket d’inscription reçu par courriel ou SMS.
Jeton APNS	Jeton APNS Apple pour l’appareil. Il doit s’agir d’une chaîne contenant les 64 octets (au format hexadécimal).
Paire de clés	Une paire de clés RSA (privée/publique) servant à prouver votre identité auprès d’Auth0 Guardian.

Une fois ces renseignements en main, vous pouvez inscrire votre appareil :

Guardian
        .enroll(forDomain: "{yourTenantDomain}",
                usingUri: "{enrollmentUri}",
                notificationToken: "{apnsToken}",
                signingKey: signingKey,
                verificationKey: verificationKey
                )
        .start { result in
            switch result {
            case .success(let enrolledDevice):
                // succès, les données de l'appareil inscrit sont disponibles
            case .failure(let cause):
                // échec, vérifiez la cause pour savoir ce qui s'est passé
            }
        }

En cas de succès, vous obtiendrez les informations d’inscription, qui doivent être stockées de manière sécurisée dans votre application. Ces informations comprennent l’identifiant d’inscription et le jeton de l’API Guardian associé à votre appareil, qui sert à mettre à jour ou à supprimer votre inscription.

​

Clés de signature et de vérification

Guardian.swift fournit une classe pratique pour générer une clé de signature :

let signingKey = try DataRSAPrivateKey.new()

Cette clé n’existe qu’en mémoire, mais vous pouvez obtenir sa représentation Data et la stocker de manière sécurisée, par exemple dans une SQLiteDB chiffrée :

// Stocker les données
let data = signingKey.data
// effectuer le stockage

// Charger depuis le stockage
let loadedKey = try DataRSAPrivateKey(data: data)

Mais si vous voulez simplement le stocker dans le trousseau iOS :

let signingKey = try KeychainRSAPrivateKey.new(with: "com.myapp.mytag")

L’exemple ci-dessus crée une clé et l’enregistre automatiquement sous la balise fournie. Si vous voulez la récupérer, vous pouvez utiliser la balise :

let signingKey = try KeychainRSAPrivateKey(tag: "com.myapp.mytag")

Pour la clé de vérification, il suffit de la récupérer à partir de n’importe quel SigningKey, par exemple :

let verificationKey = try signingKey.verificationKey()

​

Autoriser les demandes de connexion

Une fois l’inscription configurée, vous recevrez une notification push chaque fois que l’utilisateur devra valider son identité avec la MFA. Guardian fournit une méthode pour analyser les données reçues d’APNs et retourner une instance Notification prête à l’emploi.

if let notification = Guardian.notification(from: notificationPayload) {
    // nous avons reçu une notification push Guardian
}

Une fois que vous avez l’instance de notification, vous pouvez facilement approuver la demande d’authentification à l’aide de la méthode allow. Vous aurez aussi besoin de certaines informations sur l’appareil inscrit que vous avez obtenues précédemment. Si vous avez plus d’une inscription, vous devrez trouver celle qui a le même id que la notification (la propriété enrollmentId).

Une fois ces informations en main, le paramètre device peut être n’importe quel élément qui implémente le protocole AuthenticatedDevice :

struct Authenticator: Guardian.AuthenticationDevice {
    let signingKey: SigningKey
    let localIdentifier: String
}

L’identifiant local correspond à l’identifiant local de l’appareil; par défaut, lors de l’inscription, il s’agit de UIDevice.current.identifierForVendor. Appelez ensuite simplement :

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .allow(notification: notification)
        .start { result in
            switch result {
            case .success:
                // la demande d'authentification a été autorisée avec succès
            case .failure(let cause):
                // une erreur s'est produite, vérifiez cause pour voir ce qui s'est passé
            }
        }

​

Refuser des demandes de connexion

Pour refuser une demande d’authentification, appelez plutôt reject. Vous pouvez aussi envoyer un motif de rejet facultatif. Le motif de rejet apparaîtra dans les journaux de Guardian.

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .reject(notification: notification)
        // ou reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // la demande d'authentification a été rejetée avec succès
            case .failure(let cause):
                // une erreur s'est produite, vérifiez la cause pour savoir ce qui s'est passé
            }
        }

​

Annuler l’inscription

Si vous souhaitez supprimer une inscription, par exemple pour désactiver la MFA, vous pouvez envoyer la requête suivante :

Guardian
        .api(forDomain: "{yourTenantDomain}")
        .device(forEnrollmentId: "{userEnrollmentId}", token: "{enrollmentDeviceToken}")
        .delete()
        .start { result in
            switch result {
            case .success:
                // succès, l'inscription a été supprimée
            case .failure(let cause):
                // échec, vérifiez cause pour savoir ce qui s'est passé
            }
        }

​

Configurer l’inscription à l’OTP sur mobile uniquement

Vous pouvez activer les mots de passe à usage unique (OTP) comme facteur MFA à l’aide de Auth0 Dashboard ou de la Management API. Cette option ne nécessite pas de code QR et permet aux utilisateurs de s’inscrire manuellement.

Pour inviter un utilisateur à s’inscrire, accédez à Auth0 Dashboard > User Management > Users et sélectionnez un utilisateur. Ensuite, ouvrez l’onglet Details et utilisez la section Multi-Factor Authentication pour envoyer une invitation à l’inscription.

​

Connecter une ressource

Vous pouvez connecter une ressource en utilisant Auth0 Dashboard ou le SDK Guardian.

Utilisez Auth0 Dashboard

1. Accédez à l’invite de connexion Auth0 et copiez le code fourni ou une clé semblable codée en base32 obtenue d’une autre source. À l’étape suivante, saisissez ce code dans une application d’authentification.

   

2. Ajoutez le code que vous avez copié à une application d’authentification, comme Guardian.

Utiliser le SDK

1. Importez la bibliothèque Guardian.

   import Guardian
   

2. Créez un générateur de code.

   let codeGenerator = try Guardian.totp(
   
      base32Secret: enrollmentCode,  // Code d’inscription saisi par l’utilisateur
   
      algorithm: .sha1			// Algorithme utilisé par TOTP
   
   )
   

3. Obtenez le code généré.

   codeGenerator.code()
   

​

Entrez le code à usage unique

Dans l’invite de connexion Auth0, saisissez le code que vous avez généré à l’étape précédente.

Après avoir sélectionné Continuer, un message s’affiche pour indiquer que votre application a été ajoutée comme facteur d’authentification pour l’utilisateur.

​

Connectez-vous avec votre application

Une fois l’inscription du facteur terminée, votre utilisateur peut se connecter à l’aide de votre application. Choisissez d’abord l’application Guardian comme méthode d’authentification.

Ensuite, saisissez le code à usage unique à l’invite de connexion pour vérifier votre identité.