Comment utiliser les appareils mémorisés dans mon groupe d'utilisateurs Amazon Cognito ?

Brève description

Amazon Cognito peut suivre et mémoriser les appareils que les utilisateurs d'un groupe d'utilisateurs utilisent pour se connecter. En activant la mémorisation des appareils, vous pouvez définir des restrictions de connexion (par exemple, pour limiter la connexion depuis un seul appareil). Ou bien vous pouvez également éviter aux utilisateurs de se reconnecter à chaque ouverture de session sur le même appareil. Pour plus d'informations, consultez Définition des paramètres de suivi des appareils d'un groupe d'utilisateurs.

Remarque : Vous devez utiliser le flux d'authentification USER_SRP_AUTH pour utiliser la fonctionnalité de suivi des appareils. Pour utiliser des appareils mémorisés en remplacement de l'authentification multifactorielle (MFA), vous devez également activer MFA pour votre groupe d'utilisateurs.

La mémorisation des dispositifs se divise en deux parties :

• Confirmation d'un nouvel appareil. Lancez l'authentification à partir de l'appareil, puis confirmez-la avec Amazon Cognito afin d'obtenir des identifiants de dispositif uniques.
• Vérification d'un appareil confirmé. Lancez l'authentification à partir d'un appareil confirmé pour ignorer l'étape de l'authentification multi-facteurs (MFA) lors des tentatives de connexion suivantes.

Résolution

Remarque : les instructions suivantes décrivent généralement les appels d'API Amazon Cognito à effectuer dans le code du client de votre application. Si vous utilisez un kit SDK côté client, tel que les kits AWS Mobile SDK pour Android ou iOS, celui-ci gère alors une grande partie de l'implémentation.

Configuration des appareils mémorisés

1. Dans la console Amazon Cognito, sélectionnez Manage user pools (Gérer les groupes d'utilisateurs), puis choisissez votre groupe d'utilisateurs.
2. Dans le volet de navigation de gauche, choisissez Devices (Appareils) sous General settings (Paramètres généraux).
3. À la question Souhaitez-vous mémoriser les appareils de votre utilisateur ?, choisissez Toujours ou Consentement de l'utilisateur. Pour plus d'informations, consultez Suivi et rappel des appareils à l'aide de vos groupes d'utilisateurs Amazon Cognito.
4. À la question Souhaitez-vous utiliser un appareil mémorisé pour supprimer le deuxième facteur lors de l'authentification multi-facteurs (MFA) ?, choisissez Oui ou Non. Pour plus d'informations, consultez Utilisation d'appareils mémorisés pour supprimer l'authentification multifactorielle (MFA).
   Remarque : si ces options n'apparaissent pas, cela signifie que l'authentification MFA n'est pas activée. Pour configurer l'authentification MFA, sélectionnez Authentification MFA et vérifications dans le volet de navigation de gauche.
5. Sélectionnez Save changes (Enregistrer les modifications).

Appel de SetUserMFAPreference

Dans le code du client d'application, appelez l'API SetUserMFAPreference afin de définir la préférence MFA sur true pour les méthodes MFA que vous utilisez.

Appel InitiateAuth

Dans le code du client d'application, appelez l'API InitiateAuth pour obtenir les clés des appareils. Dans cette demande d'API, veillez à inclure les paramètres de demande suivants :

• AuthFlow. Utilisez USER_SRP_AUTH.
• AuthParameters. Incluez les paramètres d'authentification USERNAME, SRP_A et SECRET_HASH.
  Remarque : SECRET_HASH est obligatoire uniquement si le client de votre application est configuré avec une clé secrète de client.

Calculez SRP_A à l'aide de cette formule :

SRP_A = ga (mod N)

• Utilisez g comme défini dans AuthenticationHelper.js sur le référentiel GitHub AWS Amplify (JavaScript).
• Laissez a = 128 octets aléatoires

Pour plus d'informations, consultez Syntaxe des demandes et Référence d'API du kit SDK AWS de votre choix.

Appeler RespondToAuthChallenge pour les stimulations MFA

Une fois que votre client d'application a effectué l'appel d'API InitiateAuth, votre groupe d'utilisateurs Amazon Cognito renvoie un ensemble de défis MFA basés sur les méthodes MFA que vous avez activées.

Votre application doit répondre à ces stimulations à l'aide de l'API RespondToAuthChallenge. Par exemple, si vous avez activé l'authentification MFA par SMS dans votre groupe d'utilisateurs, incluez le paramètre ChallengeName avec la valeur SMS_MFA. Pour plus d'informations, consultez Syntaxe des demandes et Référence d'API du kit SDK AWS de votre choix.

Stocker les clés de l'appareil

Lorsque toutes les demandes d'authentification MFA sont résolues, Amazon Cognito répond avec une clé DeviceGroupKey et une clé DeviceKey unique dans le champ NewDeviceMetadataType.

Lorsque vous utilisez le kit SDK AWS Mobile pour Android, iOS ou JavaScript dans le navigateur, l'application déplace automatiquement ces clés vers le stockage local de l'appareil. Si vous utilisez un autre kit SDK AWS, veillez à concevoir une solution de stockage de clés similaire pour votre application.

Appeler ConfirmDevice

Avec les clés DeviceGroupKey et DeviceKey, créez un secret à l'aide du protocole SRP (Secure Remote Password), qui génère un salt et un vérificateur de mot de passe. Transmettez-les à Amazon Cognito dans un appel d'API ConfirmDevice qui inclut les paramètres de demande suivants :

• AccessToken. Utilisez un jeton d'accès valide pour l'utilisateur.
• DeviceKey. Utilisez la clé unique de l'appareil, renvoyée par Amazon Cognito.
• DeviceName. Utilisez un nom que vous donnez à l'appareil. (Les kits SDK AWS Mobile utilisent l'agent utilisateur.)
• DeviceSecretVerifierConfig. Incluez Salt (16 octets aléatoires, codés en base64) et PasswordVerifier.

Pour PasswordVerifier, utilisez la formule suivante :

PasswordVerifier = g( SHA256_HASH(salt + FULL_PASSWORD) ) (mod N)

• Utilisez g comme défini dans AuthenticationHelper.js sur le référentiel GitHub AWS Amplify (JavaScript).
• Laissez FULL_PASSWORD = SHA256_HASH(DeviceGroupKey + username + ":" + RANDOM_PASSWORD)
• Laissez RANDOM_PASSWORD = 40 octets aléatoires codés en base64
• Utilisez N comme défini dans AuthenticationHelper.js sur le référentiel GitHub AWS Amplify (JavaScript).

Pour plus d'informations, consultez Syntaxe des demandes et Référence d'API du kit SDK AWS de votre choix.

(Facultatif) Appeler UpdateDeviceStatus

Lorsque vous configurez des appareils mémorisés dans votre groupe d'utilisateurs, vous pouvez ignorer cette étape si vous choisissez Toujours. Si vous choisissez Consentement de l'utilisateur, vous devez inclure un appel d'API UpdateDeviceStatus.

Remarque : si vous utilisez le kit SDK Amazon Cognito Identity pour JavaScript, vous devez alors plutôt appeler setDeviceStatusRemembered ou setDeviceStatusNotRemembered. Pour plus d'informations, consultez Usage dans le fichier README du kit SDK sur GitHub.

Lorsque vous donnez à un utilisateur de votre application la possibilité de mémoriser son appareil, cela signifie que l'appareil le suit dans votre groupe d'utilisateurs comme « non mémorisé ». Vous devez demander à l'utilisateur s'il souhaite que l’appareil soit mémorisé, puis envoyer son choix à l'aide de l'API UpdateDeviceStatus.

Remarque : lorsque le consentement est obligatoire, l'utilisateur doit donner son accord avant de pouvoir mémoriser l'appareil et de masquer la stimulation MFA.

Appeler InitiateAuth avec la clé de l'appareil

Dans le code du client d'application, appelez l'API InitiateAuth pour vérifier un appareil mémorisé. Dans cet appel, incluez la clé de l'appareil dans les paramètres de demande comme suit :

• AuthFlow. Utilisez USER_SRP_AUTH.
• AuthParameters. Incluez les paramètres d'authentification USERNAME, SRP_A et DEVICE_KEY.

Pour plus d'informations, consultez Syntaxe des demandes et Référence d'API du kit SDK AWS de votre choix.

Appeler RespondToAuthChallenge pour DEVICE_SRP_AUTH

Une fois que le client d'application a passé l'appel d'API InitiateAuth avec une clé d'appareil valide, votre groupe d'utilisateurs Amazon Cognito renvoie la stimulation PASSWORD_VERIFIER. Vous devez inclure DEVICE_KEY dans la réponse à la stimulation. Ensuite, vous recevez la stimulation DEVICE_SRP_AUTH. Pour répondre, appelez l'API RespondToAuthChallenge et incluez les paramètres de demande suivants :

• ChallengeName. Utilisez DEVICE_SRP_AUTH.
• ClientId. Utilisez un ID client d'application valide.
• ChallengeResponses. Incluez USERNAME, DEVICE_KEY et SRP_A dans ces réponses.
  Remarque : pour SRP_A, utilisez la formule mentionnée précédemment dans ces instructions.

Après cet appel d'API, Amazon Cognito répond avec une autre stimulation : DEVICE_PASSWORD_VERIFIER. Dans la réponse, vous obtenez également les valeurs de ChallengeParameters SECRET_BLOCK et SRP_B, dont vous avez besoin pour répondre à la demande de stimulation.

Pour plus d'informations, consultez Syntaxe des demandes et Référence d'API du kit SDK AWS de votre choix.

Appeler RespondToAuthChallenge pour DEVICE_PASSWORD_VERIFIER

Pour répondre à la demande DEVICE_PASSWORD_VERIFIER appelez l'API RespondToAuthChallenge et incluez les paramètres de demande suivants :

• ChallengeName. Utilisez DEVICE_PASSWORD_VERIFIER.
• ClientId. Utilisez un ID client d'application valide.
• ChallengeResponses. Incluez USERNAME, PASSWORD_CLAIM_SECRET_BLOCK, TIMESTAMP, PASSWORD_CLAIM_SIGNATURE et DEVICE_KEY.

Définissez les réponses à la stimulation comme suit :

• Pour PASSWORD_CLAIM_SECRET_BLOCK, utilisez la valeur de SECRET_BLOCK.
• Pour TIMESTAMP, incluez l'heure actuelle. (Par exemple, Tue Sep 25 00:09:40 UTC 2018.)
• Laissez PASSWORD_CLAIM_SIGNATURE = SHA256_HMAC(K_USER, DeviceGroupKey + DeviceKey + PASSWORD_CLAIM_SECRET_BLOCK + TIMESTAMP), codé en base64
• Laissez K_USER = SHA256_HASH(S_USER)
• Soit S_USER = [(SRP_B - [k * [(g x) (mod N)]]) (a+ ux)] (mode N)
• Laissez x = SHA256_HASH(salt + FULL_PASSWORD)
• Laissez u = SHA256_HASH(SRP_A + SRP_B)
• Laissez k = SHA256_HASH(N + g)

Obtenir des jetons web JSON à partir de votre groupe d'utilisateurs

Après avoir répondu à la dernière stimulation, votre groupe d'utilisateurs Amazon Cognito renvoie des jetons web JSON dans le champ AuthenticationResult :

{ 
    "AuthenticationResult": { 
        "AccessToken": "...", 
        "ExpiresIn": 3600, 
        "IdToken": "...", 
        "RefreshToken": "...", 
        "TokenType": "Bearer" 
    }, 
    "ChallengeParameters": {} 
}

---

Informations connexes

Flux d'authentification du groupe d'utilisateurs

Référence relative aux groupes d'utilisateurs (Console de gestion AWS)

CognitoUser.js (référentiel GitHub AWS Amplify)