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 multifactoriel Guardian d’Auth0 à votre propre application iOS, pour qu’elle serve elle-même de second facteur. Vos utilisateurs profiteront de tous les avantages de notre authentification multifactorielle fluide directement dans votre application. Pour en savoir plus, consultez Bien démarrer avec 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 tenant avec vos propres identifiants de notifications push, sinon vous ne recevrez aucune notification push. Pour en savoir plus, consultez Configurer les notifications push pour la MFA.

​

Installer le SDK Guardian pour iOS

​

CocoaPods

Guardian.swift est disponible par l’entremise de 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 push de Guardian

1. Accédez à Dashboard > Sécurité > Multi-factor Auth.
2. Activez la bascule Notification push.
3. Configurer les notifications push.

​

Utilisation

Guardian est au cœur du SDK. Pour utiliser le SDK, procédez à l’importation de la bibliothèque :

import Guardian

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

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

​

Inscription

Une inscription établit un lien entre le deuxième facteur et un compte Auth0. Lorsqu’un compte est inscrit, vous devrez fournir le deuxième facteur requis pour vérifier l’identité. Si votre application n’utilise pas encore les notifications push ou que 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 tenant :

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

Une fois que vous avez ces renseignements, 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):
                // réussite, les données de l'appareil d'inscription sont disponibles
            case .failure(let cause):
                // quelque chose a échoué, vérifiez la cause pour savoir ce qui s'est mal passé
            }
        }

En cas de réussite, vous obtiendrez les renseignements d’inscription, qui doivent être stockés de manière sécurisée dans votre application. Ces renseignements comprennent l’identifiant d’inscription ainsi que le jeton de l’API Guardian associé à votre appareil pour 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 en obtenir la représentation Data et la stocker de façon sécuritaire, 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 le tag fourni. Si vous voulez la récupérer, vous pouvez utiliser ce tag :

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

Pour la clé de vérification, il suffit de l’obtenir à partir de n’importe quelle SigningKey, par exemple :

let verificationKey = try signingKey.verificationKey()

​

Autoriser les requêtes de connexion

Une fois l’inscription effectuée, vous recevrez une notification push chaque fois que l’utilisateur devra valider son identité avec MFA. Guardian fournit une méthode pour analyser les données reçues d’APNs et renvoyer 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 autoriser la requête d’authentification à l’aide de la méthode allow. Vous aurez aussi besoin de certaines informations provenant de 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 que vous avez ces informations, 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 est l’ID local de l’appareil; par défaut, lors de l’inscription, il s’agit de UIDevice.current.identifierForVendor. Ensuite, faites simplement la requête suivante :

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

​

Rejeter les requêtes de connexion

Pour rejeter une requête 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 n'a pas fonctionné
            }
        }

​

Désinscription

Si vous souhaitez supprimer une inscription, par exemple pour désactiver 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:
                // réussite, l'inscription a été supprimée
            case .failure(let cause):
                // quelque chose a échoué, vérifiez la cause pour savoir ce qui s'est mal passé
            }
        }

​

Configurer l’inscription OTP sur mobile uniquement

Vous pouvez activer les mots de passe à usage unique (OTP) comme facteur MFA à l’aide du Auth0 Dashboard ou de la Management API. Cette option ne nécessite pas de QR code 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. Accédez ensuite à son onglet Details et utilisez la section Multi-Factor Authentication pour envoyer une invitation à l’inscription.

​

Connecter une ressource

Vous pouvez connecter une ressource à l’aide de l’Auth0 Dashboard ou du Guardian SDK.

Utiliser Auth0 Dashboard

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

   

2. Saisissez le code que vous avez copié dans 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’écran de connexion Auth0, entrez 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 votre utilisateur.

​

Connectez-vous avec votre application

Une fois le facteur configuré, l’utilisateur peut se connecter à l’aide de votre application. Commencez par choisir l’application Guardian comme méthode d’authentification.

Ensuite, entrez le code à usage unique dans l’écran de connexion pour vérifier votre identité.