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. Grâce à la mémorisation des appareils, vous pouvez définir des restrictions de connexion, telles que la limite de connexion à partir d'un seul appareil. Vous pouvez également autoriser les utilisateurs à ignorer les connexions répétées sur le même appareil. Pour plus d'informations, consultez la section 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 afin de remplacer l'authentification multifactorielle (MFA), vous devez également activer l'authentification MFA pour votre groupe d'utilisateurs.

La mémorisation des appareils est un processus en deux étapes :

• Confirmer un nouvel appareil : Lancez l'authentification depuis l'appareil, puis confirmez-la auprès d'Amazon Cognito pour obtenir des identifiants uniques de l'appareil.
• Vérifier un appareil confirmé : Lancez l'authentification à partir d'un appareil confirmé pour ignorer l'étape MFA lors des tentatives de connexion suivantes.

Résolution

Remarque : Ces instructions décrivent les appels d'API Amazon Cognito à effectuer dans le code client de votre application. Si vous utilisez un SDK côté client, tel que les kits SDK mobiles AWS, le SDK gère une grande partie de l'implémentation.

Configurer les appareils mémorisés

1. Dans la console Amazon Cognito, choisissez Gérer les groupes d’utilisateurs, puis choisissez votre groupe d’utilisateurs.
2. Dans le volet de navigation, sous Paramètres généraux, sélectionnez Appareils.
3. Pour Souhaitez-vous mémoriser les appareils de vos utilisateurs, choisissez Toujours ou User Opt In. Pour plus d'informations, consultez la section Suivi et mémorisation des appareils à l'aide d'Amazon Cognito Your User Pools (langue française non garantie).
4. Pour Voulez-vous utiliser un appareil mémorisé pour supprimer le second facteur lors de l'authentification multifactorielle (MFA), choisissez Oui ou Non. Pour plus d'informations, consultez la rubrique Utilisation d'appareils mémorisés pour supprimer l'authentification multifactorielle (MFA).
   Remarque : Si ces options n'apparaissent pas, cela signifie que l’authentification multifactorielle MFA n'est pas activé. Pour configurer l’authentification multifactorielle MFA, dans le volet de navigation, sélectionnez MFA et vérifications.
5. Choisissez Enregistrer les modifications.

Faites appel à l’API SetUserMFAPreference

Dans le code client de votre application, faites appel à l'API SetUserMfapReference pour définir la préférence MFA sur true pour les méthodes MFA que vous utilisez.

Faites appel à InitiateAuth

Dans le code du client de votre application, faites appel à l'API InitiateAuth pour obtenir les clés de l'appareil. Dans cette demande d'API, incluez 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 n'est requis que si le client de votre application est configuré avec un secret client.

Utilisez cette formule pour calculer SRP_A :
SRP_A = ga (mod N)

• Utilisez g tel que défini dans le fichier AuthenticationHelper.js. Pour la définition de g, consultez AuthenticationHelper.js sur le site Web de GitHub.
• Laissez a = 128 octets aléatoires

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

Faire appel à RespondToAuthChallenge pour les défis MFA

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

Votre application doit utiliser l'API RespondToAuthChallenge pour relever ces défis. 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 la Syntaxe des demandes et la Référence d'API du kit AWS SDK de votre choix.

Stocker les clés de l'appareil

Lorsque tous les défis MFA sont résolus, Amazon Cognito répond avec DeviceGroupKey et DeviceKey unique dans le champ NewDeviceMetadatatype.

Lorsque vous utilisez 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 SDK AWS, veillez à concevoir une solution de stockage de clés similaire pour votre application.

Faire appel à ConfirmDevice

Avec DeviceGroupKey et DeviceKey, utilisez le protocole Secure Remote Password (SRP) pour créer un secret. Cela 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 le nom que vous donnez à l'appareil. (Les kits SDK AWS Mobile utilisent User Agent.)
• **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 tel que défini dans le fichier AuthenticationHelper.js. Pour la définition de g, consultez AuthenticationHelper.js sur le site Web de GitHub.
• Laissez FULL_PASSWORD = SHA256_HASH(DeviceGroupKey + username + ":" + RANDOM_PASSWORD)
• Laissez RANDOM_PASSWORD = 40 octets aléatoires, encodés en base64
• Utilisez N tel que défini dans le fichier AuthenticationHelper.js. Pour la définition de N, consultez AuthenticationHelper.js sur le site Web de GitHub.

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

(Facultatif) Call 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 User Opt In, vous devez inclure un appel d'API UpdateDeviceStatus.

Remarque : Si vous utilisez le SDK Amazon Cognito Identity pour JavaScript, vous devez plutôt appeler SetDeviceStatusRemembered ou SetDeviceStatusNotRemembered. Pour plus d'informations sur l'utilisation du SDK Amazon Cognito Identity pour JavaScript, consultez la section Utilisation sur le site Web de GitHub.

Lorsque vous offrez aux utilisateurs de votre application la possibilité de mémoriser leur appareil, la confirmation de l'appareil apparaît dans votre groupe d'utilisateurs comme « non mémorisée ». Vous devez demander à l'utilisateur s'il souhaite que l'appareil soit mémorisé, puis utiliser l'API UpdateDeviceStatus pour envoyer leur choix.

Remarque : Lorsque le consentement est obligatoire, l'utilisateur doit donner son accord pour que l'appareil puisse être mémorisé et que le défi MFA puisse être masqué.

Appeler InitiateAuth avec la clé de l'appareil

Dans le code du client de votre application, appelez l'API InitiateAuth pour vérifier un appareil mémorisé. Dans cet appel, incluez la clé du périphérique 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 la Syntaxe des demandes et la Référence d'API du kit SDK AWS de votre choix.

Appeler RespondToAuthChallenge pour DEVICE_SRP _AUTH

Une fois que le client de votre application a effectué l'appel d'API InitiateAuth avec une clé d'appareil valide, votre groupe d'utilisateurs Amazon Cognito renvoie le défi PASSWORD\ _VERIFIER. Vous devez inclure DEVICE_KEY dans la réponse au défi. Ensuite, vous recevez le défi 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 identifiant client valide.
• **ChallengeResponses :**Incluez USERNAME, DEVICE\ _KEY et SRP_A dans ces réponses.
  Remarque : Pour SRP\ _A, utilisez la formule mentionnée plus haut dans ces instructions.

Après cet appel d'API, Amazon Cognito répond avec un autre défi : DEVICE_PASSWORD_VERIFIER. Dans la réponse, vous obtenez également les valeurs de ChallengeParameters SECRET_BLOCK et SRP_B. Vous avez besoin des valeurs SECRET\ _BLOCK et SRP\ _B pour relever le défi.

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

Appeler RespondToAuthChallenge pour DEVICE_PASSWORD\ _VERIFIER

Pour répondre au défi DEVICE\ _PASSWORD_VERIFIER, appelez l'API RespondToAuthChallenge et incluez les paramètres de demande suivants :

• **ChallengeName :Utilisez ** DEVICE_PASSWORD_VERIFIER.
• ClientId : Utilisez un identifiant client valide.
• **ChallengeResponses :**Incluez USERNAME, PASSWORD_CLAIM_SECRET_BLOCK, TIMESTAMP, PASSWORD_CLAIM_SIGNATURE et DEVICE_KEY.

Définissez les réponses au défi comme suit :

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

Obtenez des jetons Web JSON à partir de votre groupe d'utilisateurs

Une fois que vous avez répondu avec succès au dernier défi, votre groupe d'utilisateurs Amazon Cognito renvoie des jetons Web JSON dans AuthenticationResult :

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

Informations connexes

Flux d'authentification de groupe d'utilisateurs

Référence des groupes d'utilisateurs (AWS Management Console)

CognitoUser.js sur le site de GitHub