Cette page explique comment configurer l'authentification multifacteur (MFA) qui vous permet de vérifier l'identité de vos utilisateurs en envoyant un code de validation par e-mail. Cette fonctionnalité vous permet de vérifier que vos utilisateurs sont bien propriétaires de l'adresse e-mail associée à leur compte. La MFA peut vous aider à protéger vos utilisateurs contre les attaques par credential stuffing et piratages de compte (ATO, Account Takeovers).
La MFA est disponible pour les clés basées sur des scores, mais pas pour les clés à cases à cocher.
Comprendre le processus de configuration de la MFA
La fonctionnalité MFA de reCAPTCHA Enterprise est mise en œuvre en plus du workflow reCAPTCHA Enterprise standard.
Dans les grandes lignes, le workflow MFA est le suivant:
- Instrumentez le workflow critique sur votre site Web.
- Créez une évaluation à l'aide du jeton renvoyé par l'appel
execute()et des paramètres MFA pour obtenir unrequestTokenMFA. - Déclenchez un défi MFA avec le
requestTokenen fonction du canal que vous souhaitez utiliser (seuls les e-mails sont acceptés). - Validez le code saisi par l'utilisateur final sur votre site Web.
- Créez une évaluation à l'aide du jeton renvoyé dans la requête de validation.
Avant de commencer
L'authentification multifacteur est accessible après un examen de sécurité. Contactez notre équipe commerciale pour intégrer cette fonctionnalité sur votre site. Fournissez les informations d'intégration suivantes à l'équipe commerciale:
- Numéro de projet Google Cloud
- Clés reCAPTCHA à intégrer
- RPS moyennes (e-mails par seconde)
- Pic de RPS (messages e-mail par seconde)
- Pour les adresses e-mail MFA, l'adresse de l'expéditeur et les adresses e-mail ou domaines dont vous avez besoin lors des tests
Pour activer la fonctionnalité de validation de l'adresse e-mail de l&#MFA;authentification multifacteur, procédez comme suit:
Dans la console Google Cloud, accédez à la page reCAPTCHA Enterprise.
Vérifiez que le nom de votre projet apparaît dans le sélecteur de ressources.
Si vous ne voyez pas le nom de votre projet, cliquez sur le sélecteur de ressources, puis sélectionnez votre projet.
Cliquez sur Paramètres.
Dans le volet Authentification multifacteur, cliquez sur Configurer.
Dans la boîte de dialogue Configure MFA (Configurer la MFA), procédez comme suit:
- Pour activer la validation par e-mail, cliquez sur le bouton Activer l'adresse e-mail.
- Dans le champ Nom de l'expéditeur, saisissez votre nom.
Dans le champ Adresse e-mail de l'expéditeur, saisissez votre adresse e-mail.
Cliquez sur Enregistrer.
Configurez reCAPTCHA Enterprise sur votre site Web à l'aide de clés basées sur des scores.
Instrumentez le workflow essentiel sur votre site Web
Transmettez les informations nécessaires à reCAPTCHA Enterprise via la fonction execute() pour l'évaluation des risques. La fonction execute() renvoie une promesse qui est résolue à la génération du jeton.
Ajoutez un paramètre twofactor supplémentaire à votre fonction execute(), comme indiqué dans l'exemple de code suivant :
grecaptcha.enterprise.execute(KEY_ID, {
action: 'login',
twofactor: true
}).then(token => {
// Handle the generated token.
});
Remplacez KEY_ID par la clé basée sur des scores que vous avez créée pour votre site Web.
Créer une évaluation
Avec le jeton généré par la fonction execute(), créez une évaluation à l'aide des bibliothèques clientes reCAPTCHA Enterprise ou de l'API REST depuis votre backend.
Ce document explique comment créer une évaluation pour la MFA à l'aide de l'API REST. Pour savoir comment créer une évaluation à l'aide de bibliothèques clientes, consultez Créer des évaluations pour des sites Web.
Avant de créer une évaluation, procédez comme suit:
Configurez l'authentification auprès de reCAPTCHA Enterprise.
La méthode d'authentification que vous choisissez dépend de l'environnement dans lequel reCAPTCHA Enterprise est configuré. Le tableau suivant vous aide à choisir la méthode d'authentification appropriée et l'interface compatible pour configurer l'authentification:
Environnement Interface Méthode d'authentification Google Cloud - REST
- Bibliothèques clientes
Utilisez les comptes de service associés. Sur site ou via un autre fournisseur de services cloud REST Utilisez des clés API ou la fédération d'identité de charge de travail. Si vous souhaitez utiliser des clés API, nous vous recommandons de les sécuriser en appliquant des restrictions de clés API.
Bibliothèques clientes Utilisez les ressources suivantes :
- Pour Python ou Java, utilisez des clés API ou la fédération d'identité de charge de travail.
Si vous souhaitez utiliser des clés API, nous vous recommandons de les sécuriser en appliquant des restrictions de clés API.
- Pour les autres langages, utilisez la fédération d'identité de charge de travail.
Choisissez un identifiant de compte stable
accountIdqui n'est pas souvent modifié par l'utilisateur et fournissez-le à l'évaluation dans la méthodeprojects.assessments.create. Cet identifiant de compte stable doit avoir la même valeur pour tous les événements liés au même utilisateur. Vous pouvez fournir les éléments suivants comme identifiant de compte:Identifiants utilisateur
Si chaque compte peut être associé de manière unique à un nom d'utilisateur, une adresse e-mail ou un numéro de téléphone stables, vous pouvez l'utiliser comme
accountId. Lorsque vous fournissez de tels identifiants intersites (qui peuvent être réutilisés sur plusieurs sites), reCAPTCHA Enterprise se sert de ces informations pour améliorer la protection de vos comptes utilisateur sur la base de modèles intersites. Il signale les identifiants de compte abusifs et exploite les connaissances sur les schémas d'utilisation abusive sur plusieurs sites qui leur sont associés.Si un ID utilisateur interne est associé de manière unique à chaque compte, vous pouvez également le fournir en tant que
accountId.Hachées ou chiffrées
Si aucun ID utilisateur interne n'est associé de manière unique à chaque compte, vous pouvez transformer n'importe quel identifiant stable en un identifiant de compte opaque spécifique au site. Cet identifiant est toujours nécessaire pour que reCAPTCHA Enterprise Account Defender puisse comprendre les modèles d'activité des utilisateurs et détecter les comportements anormaux, mais il n'est pas partagé entre d'autres sites.
Choisissez un identifiant de compte stable et rendez-le opaque avant de l'envoyer à reCAPTCHA Enterprise à l'aide du chiffrement ou du hachage:
chiffrement (recommandé): chiffrez l'identifiant de compte à l'aide d'une méthode de chiffrement déterministe produisant un texte chiffré stable. Pour obtenir des instructions détaillées, consultez la section Chiffrer des données de manière déterministe. Lorsque vous choisissez le chiffrement symétrique plutôt que le hachage, vous n'avez pas besoin de conserver un mappage entre vos identifiants utilisateur et les identifiants utilisateur opaques correspondants. Déchiffrez les identifiants opaques renvoyés par reCAPTCHA Enterprise pour les transformer en identifiant utilisateur.
Hachage: nous vous recommandons de hacher l'identifiant de compte à l'aide de la méthode SHA256-HMAC avec un salage personnalisé de votre choix. Les hachages étant à sens unique, vous devez conserver une correspondance entre les hachages générés et vos identifiants utilisateur afin de pouvoir mapper l'identifiant de compte haché renvoyé aux comptes d'origine.
Ajoutez le paramètre accountId et un point de terminaison, tel qu'une adresse e-mail à vérifier dans l'évaluation via la méthode projects.assessments.create.
Avant d'utiliser les données de requête, effectuez les remplacements suivants:
- PROJECT_ID : ID de votre projet Google Cloud.
- TOKEN: jeton renvoyé par l'appel
grecaptcha.enterprise.execute(). - KEY_ID: clé basée sur des scores que vous avez installée sur votre site Web.
- ACCOUNT_ID: identifiant d'un compte utilisateur propre à votre site Web.
- EMAIL_ID: adresse e-mail pour laquelle la demande de validation doit être déclenchée.
Méthode HTTP et URL :
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corps JSON de la requête :
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userInfo": {
"accountId": "ACCOUNT_ID"
}
}
"accountVerification": {
"endpoints": [{
"emailAddress": "EMAIL_ID",
}]
}
}
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json et exécutez la commande suivante:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"
PowerShell
Enregistrez le corps de la requête dans un fichier nommé request.json et exécutez la commande suivante:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON de ce type :
{
[...],
"accountVerification": {
"endpoints": [{
"emailAddress": "foo@bar.com",
"requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
"lastVerificationTime": "",
}],
"latestVerificationResult": "RESULT_UNSPECIFIED"
}
}
L'évaluation contiendra la date et l'heure de la dernière validation réussie pour les points de terminaison indiqués sur l'appareil qui a émis le jeton, le cas échéant. Elle contient également un champ requestToken par point de terminaison, qui contient une chaîne chiffrée. Si vous décidez de déclencher un test MFA pour ce point de terminaison, vous devez renvoyer cette chaîne chiffrée à la page Web. Les jetons de requête sont valides pendant 15 minutes.
Actions recommandées
Si reCAPTCHA Enterprise Account Defender est activé pour votre projet, la réponse d'évaluation contient des informations liées à Account Defender en plus de celles liées à MFA;authentification multifacteur. Le champ recommended_action indique l'action que vous pouvez effectuer avant de déclencher le défi MFA.
L'exemple suivant présente un exemple d'évaluation qui indique que l&#MFA;action recommandée "Ignorer l'authentification multifacteur" est "Ignorer l'authentification multifacteur" :
{
[...],
"accountDefenderAssessment": {
labels: ["PROFILE_MATCH"],
"recommended_action": "SKIP_2FA"
}
}
Le champ recommended_action peut avoir l'une des valeurs suivantes:
| Value (Valeur) | Description |
|---|---|
RECOMMENDED_ACTION_UNSPECIFIED |
Indique que Account Defender n'a pas pu prendre de jugement concernant cette demande. |
SKIP_2FA |
Indique que Account Defender considère qu'il peut être sécurisé d'ignorer MFA pour cette évaluation. Cela signifie généralement que l'utilisateur a été validé récemment pour votre site sur cet appareil. |
REQUEST_2FA |
Indique que vous déclenchez un défi MFA pour l'utilisateur. Pour en savoir plus, consultez Réponse à l'évaluation Account Defender. |
Déclencher un test MFA sur votre site Web
Pour interroger l'utilisateur sur la base des informations contenues dans l'évaluation, envoyez la clé MFA requestToken pour le point de terminaison que vous souhaitez vérifier à partir de l'évaluation vers la page Web.
Déclenchez le test MFA en appelant challengeAccount().
La fonction challengeAccount() renvoie une promesse qui est résolue à la fin du test, ou qui est refusée en cas d'erreur ou d'expiration du délai.
Une fois l'opération terminée, un nouveau jeton contenant des informations mises à jour est généré, puis envoyé pour évaluation.
Pour déclencher un défi MFA, procédez comme suit:
Testez l'intégration de la MFA.
Déclenchez un défi MFA avec un appel à
challengeAccount()en fournissant les valeurs suivantes:- KEY_ID: clé basée sur des scores que vous avez installée sur votre site Web.
- REQUEST_TOKEN_FROM_ASSESSMENT: valeur du champ
requestTokende la réponse d'évaluation. - CONTAINER_HTML_COMPONENT_ID: ID du composant HTML dans lequel la question de validation doit être affichée. Si vous ne spécifiez pas ce paramètre, le test sera sera affiché dans une superposition sur la page.
L'exemple suivant montre comment déclencher le défi MFA avec un appel à
challengeAccount():grecaptcha.enterprise.challengeAccount(KEY_ID, { 'account-token': REQUEST_TOKEN_FROM_ASSESSMENT, 'container': CONTAINER_HTML_COMPONENT_ID }).then(newToken => { // Handle the new token. });Si la requête
challengeAccount()aboutit, le composant HTML s'affiche pour saisir le code secret reçu. Une fois le bon code saisi, la variablenewTokenest transmise à la fonction en chaîne contenant le jeton d'évaluation, à vérifier via une évaluation créée dans le backend.Créez un identifiant de validation et lancez un test avec les paramètres suivants:
// Initialize verification handle. const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle( KEY_ID, REQUEST_TOKEN_FROM_ASSESSMENT ); // Call the challenge API. verificationHandle.challengeAccount().then( (challengeResponse) => { if (challengeResponse.isSuccess()) { // Handle success: This means displaying an input for the end user to // enter the PIN that they received and then call the `verifyAccount(pin)` // method. } else { // Handle API failure } });
Vérifier un code MFA à partir de la page Web
Une fois que vous avez reçu le code d'accès de l'utilisateur final, vous devez vérifier s'il est correct ou non.
Pour valider le code, appelez verificationHandle.verifyAccount() avec le code saisi par l'utilisateur final.
verificationHandle.verifyAccount(pin).then(
(verifyResponse) => {
if (verifyResponse.isSuccess()) {
// Handle success: Send the result of `verifyResponse.getVerdictToken()`
// to the backend in order to determine if the code was valid.
} else {
// Handle API failure
}
},
(error) => {
// Handle other errors
}
);
Créer une évaluation
Créez une évaluation avec accountId et endpoints. Pour obtenir des instructions, consultez la page Créer une évaluation pour la MFA.
Une fois le workflow terminé sur le client, vous recevez un nouveau jeton que vous pouvez utiliser pour obtenir le résultat de la validation que vous avez déclenchée. L'évaluation contient un horodatage récent de la dernière validation réussie, ainsi qu'un statut affichant un résultat positif.
L'exemple suivant présente un exemple d'évaluation que vous recevez lors de la création d'une évaluation à l'aide du nouveau jeton obtenu sur le site Web:
{
[...],
"accountVerification": {
"endpoints": [{
"emailAddress": "foo@bar.com",
"requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
"lastVerificationTime": "2020-03-23 08:27:12 PST",
}],
"latestVerificationResult": "SUCCESS_USER_VERIFIED"
}
}
Le champ latestVerificationResult peut afficher un état différent, comme indiqué dans le tableau suivant:
| État du résultat de la validation | Description |
|---|---|
| SUCCESS_USER_VERIFIED | L'utilisateur a bien été validé. |
| ERROR_USER_NOT_VERIFIED | L'utilisateur n'a pas réussi le test de validation. |
| ERROR_SITE_ONBOARDING_INCOMPLETE | Votre site n'est pas correctement intégré à la fonctionnalité. |
| ERROR_RECIPIENT_NOT_ALLOWED | Ce destinataire n'est pas autorisé à envoyer des e-mails à (lors des tests uniquement). |
| ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED | Ce destinataire a déjà reçu trop de codes de validation en peu de temps. |
| ERROR_CUSTOMER_QUOTA_EXHAUSTED | Vous avez dépassé votre quota MFA disponible. |
| ERROR_CRITICAL_INTERNAL | La validation n'a pas été effectuée en raison d'une erreur interne dans nos systèmes. |
| RESULT_UNSPECIFIED | Aucune information sur la dernière validation (jamais validée). |