Trousse SDK Guardian.swift pour iOS

Cette section explique comment installer et configurer les options de la trousse SDK Guardian.swift pour iOS.

Guardian.swift vous permet d’intégrer le service multifacteur Guardian d‘Auth0 dans votre propre application iOS, en le transformant en deuxième facteur. Vos utilisateurs bénéficieront de tous les avantages de notre authentification multifacteur (MFA) en toute simplicité à partir de votre application. Pour en savoir plus, consultez Premiers pas avec le service de notification poussée d’Apple.

​

Exigences

• iOS 10+ et Swift 4.1 sont nécessaires pour utiliser Guardian.
• Pour utiliser cette trousse SDK, vous devez configurer le service Guardian de votre locataire avec vos propres identifiants de notification poussée, faute de quoi vous ne recevrez aucune notification poussée. Pour en savoir plus, consultez Configurer les notifications poussées pour l’authentification multifacteur.

​

Installer la trousse SDK Guardian pour iOS

​

CocoaPods

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

pod 'Guardian', '~> 1.1.0'

​

Carthage

Ajoutez cette ligne à votre cartfile :

github "auth0/Guardian.swift" ~> 1.1.0

​

Activer les notifications poussées de Guardian

1. Allez dans Dashboard > Security (Sécurité) > Multi-factor Auth (MFA).
2. Activez la notification poussée à l’aide du bouton à bascule.
3. Configurez les notifications poussées.

​

Utilisation

Guardian est au cœur de la trousse SDK. Pour utiliser la trousse SDK, importez la bibliothèque :

import Guardian

Définissez le domaine pour votre locataire. Vous pouvez aussi utiliser le domaine personnalisé si vous en avez configuré un pour votre locataire.

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

​

Inscription

Une inscription est un lien entre le deuxième facteur et un compte Auth0. Lorsqu’un compte est inscrit, vous en avez besoin pour fournir le deuxième facteur nécessaire à la vérification de l’identité. Si votre application n’utilise pas encore les notifications poussées ou si vous ne connaissez pas ce service, consultez la section Présentation du service de notifications poussées d’Apple pour en savoir davantage.

Vous avez besoin des informations suivantes en plus de votre domaine de locataire pour vous inscrire :

Variable	Description
Enrollment URI	Valeur codée dans le code QR scanné à partir du Guardian Web Widget ou votre ticket d’inscription envoyé par courriel ou SMS.
APNS Token	Jeton APNS Apple pour l’appareil. Il doit s’agir d’une chaîne contenant les 64 octets (en format hexadécimal).
Key Pair	Une paire de clés RSA (privée/publique) utilisées pour affirmer votre identité avec Gardien Auth0.

Vous pourrez ensuite inscrire votre appareil :

Guardian
        .enroll(forDomain: "{yourTenantDomain}",
                usingUri: "{enrollmentUri}",
                notificationToken: "{apnsToken}",
                signingKey: signingKey,
                verificationKey: verificationKey
                )
        .start { result in
            switch result {
            case .success(let enrolledDevice):
                // success, we have the enrollment device data available
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

Vous obtiendrez ensuite les informations d’inscription, qui devraient être stockées en toute sécurité dans votre application. Elles comprennent l’identifiant de l’inscription, et le jeton de l’API Guardian associée à votre appareil pour la mise à jour ou la suppression de votre inscription.

​

Clés de signature et de vérification

Guardian.swift fournit une classe de commodité pour générer une clé de connexion :

let signingKey = try DataRSAPrivateKey.new()

Cette clé n’existe qu’en mémoire, mais vous pouvez obtenir sa représentation Data et la stocker en toute sécurité, par exemple dans une SQLiteDB chiffrée.

// Store data
let data = signingKey.data
// perform the storage

// Load from Storage
let loadedKey = try DataRSAPrivateKey(data: data)

Si vous voulez simplement la stocker dans le trousseau d’iOS :

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

Dans l’exemple ci-dessus, une clé est créée et stockée automatiquement sous la balise fournie. Si vous souhaitez la récupérer, vous pouvez utiliser la balise :

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

Quant à la clé de vérification, vous pouvez l’obtenir à partir de n’importe quelle SigningKey. Par exemple :

let verificationKey = try signingKey.verificationKey()

​

Autoriser les demandes de connexion

Une fois l’inscription configurée, vous recevrez une notification poussée chaque fois que l’utilisateur devra valider son identité avec l’authentification multifacteur. Guardian fournit une méthode pour analyser les données reçues des noms de point d’accès et renvoyer une instance de notification prête à l’emploi.

if let notification = Guardian.notification(from: notificationPayload) {
    // we have received a Guardian push notification
}

Une fois que vous avez l’instance de notification, vous pouvez facilement autoriser la demande d’authentification en utilisant la méthode allow. Vous aurez également 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).

Lorsque vous disposez de ces informations, le paramètre device met en œuvre le protocole AuthenticatedDevice :

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

L’identifiant local est celui de l’appareil, se trouvant par défaut dans l’inscription UIDevice.current.identifierForVendor. Il ne vous reste plus qu’à faire l’appel suivant :

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .allow(notification: notification)
        .start { result in
            switch result {
            case .success:
                // the auth request was successfuly allowed
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

​

Rejeter les demandes de connexion

Pour refuser une demande d’authentification, appelez reject. Vous pouvez également envoyer un motif de rejet (facultatif). Celui-ci apparaîtra dans les journaux de Guardian.

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .reject(notification: notification)
        // or reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // the auth request was successfuly rejected
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

​

Désinscription

Si vous souhaitez supprimer une inscription, par exemple si vous voulez désactiver l’authentification multifacteur, vous pouvez effectuer la demande suivante :

Guardian
        .api(forDomain: "{yourTenantDomain}")
        .device(forEnrollmentId: "{userEnrollmentId}", token: "{enrollmentDeviceToken}")
        .delete()
        .start { result in
            switch result {
            case .success:
                // success, the enrollment was deleted
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

​

Configurer une inscription avec un mot de passe à usage unique pour les appareils mobiles

Vous pouvez autoriser les mots de passe à usage unique (OTP) en tant que facteur MFA en utilisant l’Auth0 Dashboard ou 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, aller dans Auth0 Dashboard > Gestion des utilisateurs > Utilisateurs, et sélectionnez un utilisateur. Accédez ensuite à l’onglet Détails et utilisez la section Authentification multifacteur (MFA) pour envoyer une invitation d’inscription.

​

Connecter une ressource

Vous pouvez connecter une ressource à partir du Auth0 Dashboard ou de la trousse SDK Guardian.

Utilisation de Auth0 Dashboard

1. Accédez à l’invite de connexion Auth0 et copiez le code fourni ou une clé base32 similaire provenant d’une autre source. À l’étape suivante, vous saisirez ce code dans une application d’authentification.

   

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

Utiliser la trousse SDK

1. Importez la bibliothèque de Guardian.

   import Guardian
   

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

   let codeGenerator = try Guardian.totp(
   
      base32Secret: enrollmentCode,  // Enrollment code entered by user
   
      algorithm: .sha1			// Algorithm used by TOTP
   
   )
   

3. Récupérez le code généré.

   codeGenerator.code()
   

​

Saisir le code à usage unique

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

En sélectionnant Continue (Continuer), un message s’affiche indiquant que votre application a été ajoutée en tant que facteur d’authentification pour votre utilisateur.

​

Se connecter avec votre application

Une fois le facteur inscrit, votre utilisateur peut se connecter à l’aide de votre application. Tout d’abord, choisissez l’application Guardian comme méthode d’authentification.

Saisissez ensuite le code à usage unique dans l’invite de connexion pour vérifier votre identité.