Configurer l'authentification multifacteur

Cette page explique comment configurer l'authentification multifacteur (MFA, Multi-factor authentication) 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 propriétaires de l'adresse e-mail associée à leur compte. La MFA peut aider à protéger vos utilisateurs contre les attaques par credential stuffing et piratages de compte (ATO).

La MFA est disponible pour les clés basées sur des scores et non pour les clés de case à cocher.

Comprendre le processus de configuration de la MFA

La fonctionnalité MFA de reCAPTCHA est mise en œuvre en plus du workflow reCAPTCHA standard.

Dans les grandes lignes, le flux de travail MFA se présente comme suit:

  1. Instrumentez le workflow critique sur votre site Web.
  2. Créez une évaluation à l'aide du jeton renvoyé par l'appel execute() et des paramètres MFA pour obtenir un requestToken MFA.
  3. Déclenchez une MFA multifacteur avec l'requestToken en fonction du canal que vous souhaitez utiliser (seules les adresses e-mail sont acceptées).
  4. Validez le code saisi par l'utilisateur final sur votre site Web.
  5. Créez une évaluation en utilisant le jeton renvoyé dans la requête de validation.

Avant de commencer

  1. Préparez votre environnement pour reCAPTCHA.

  2. 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 (e-mails par seconde)
    • Pour l'authentification multifacteur (MFA), l'adresse de l'expéditeur, et les adresses e-mail ou les domaines dont vous avez besoin lors des tests

  3. Si vous souhaitez activer la fonctionnalité de vérification de l’adresse e-mail de MFA, procédez comme suit:

    1. Dans la console Google Cloud, accédez à la page reCAPTCHA.

      Accéder à reCAPTCHA

    2. 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.

    3. Cliquez sur Paramètres.

    4. Dans le volet Authentification multifacteur, cliquez sur Configurer.

    5. Dans la boîte de dialogue Configure MFA (Configurer la MFA), procédez comme suit:

      1. Pour activer la validation par e-mail, cliquez sur le bouton Activer les e-mails.
      2. Dans le champ Nom de l'expéditeur, saisissez votre nom.

      3. Dans le champ Adresse e-mail de l'expéditeur, saisissez votre adresse e-mail.

    6. Cliquez sur Enregistrer.

  4. Configurez reCAPTCHA sur votre site Web à l'aide de clés basées sur des scores.

Instrumentez le workflow critique sur votre site Web.

Transmettez les informations nécessaires à reCAPTCHA 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 les 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 ou de l'API REST depuis votre backend.

Ce document explique comment créer une évaluation MFA à l'aide de l'API REST. Pour découvrir comment créer une évaluation à l'aide des bibliothèques clientes, consultez Créer des évaluations pour les sites Web.

Avant de créer une évaluation, procédez comme suit:

  • Configurez l'authentification auprès de reCAPTCHA.

    La méthode d'authentification que vous choisissez dépend de l'environnement dans lequel reCAPTCHA 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
    Accès IAP
    • REST
    • Bibliothèques clientes
    		 Utilisez des comptes de service associés.
    Sur site ou auprès d'un autre fournisseur 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 liées aux clés API.
    Bibliothèques clientes

    Utilisez les ressources suivantes :

  • Choisissez un identifiant de compte stable accountId, qui n'est pas souvent modifié par l'utilisateur, et fournissez-le à l'évaluation dans la méthode projects.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 utiliser 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 (identifiants pouvant être réutilisés sur plusieurs sites), reCAPTCHA utilise ces informations pour améliorer la protection de vos comptes utilisateur en fonction de modèles intersites. Il signale les identifiants de compte abusifs et s'appuie sur nos connaissances des modèles d'abus intersites liés à ces identifiants.

    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 vous n'avez pas d'ID utilisateur interne associé de manière unique à chaque compte, vous pouvez transformer tout identifiant stable en identifiant de compte opaque spécifique au site. Cet identifiant est toujours nécessaire pour permettre à reCAPTCHA Account Defender de comprendre les modèles d'activité des utilisateurs et de détecter les comportements anormaux, mais il n'est pas partagé avec d'autres sites.

    Choisissez un identifiant de compte stable et rendez-le opaque avant de l'envoyer à reCAPTCHA à l'aide du chiffrement ou du hachage:

    • chiffrement (recommandé): chiffre l'identifiant de compte à l'aide d'une méthode de chiffrement déterministe qui produit 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 pour les transformer en identifiants utilisateur.

    • hachage: nous vous recommandons de hacher l'identifiant de compte à l'aide de la méthode SHA256-HMAC avec une valeur salt personnalisée de votre choix. Étant donné que les hachages sont à sens unique, vous devez conserver le mappage entre les hachages générés et vos identifiants utilisateur afin de pouvoir mapper l'identifiant de compte haché qui est 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 de 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 les 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, puis 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, puis 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 une question d'authentification 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.

Si reCAPTCHA Account Defender est activé pour votre projet, la réponse d'évaluation contient des informations sur Account Defender en plus des informations sur la MFA. Le champ recommended_action indique l'action possible avant de déclencher la question d'authentification MFA.

L'exemple suivant montre un exemple d'évaluation dans lequel l'action recommandée est d'ignorer la MFA:

{
  [...],
  "accountDefenderAssessment": {
    labels: ["PROFILE_MATCH"],
    "recommended_action": "SKIP_2FA"
  }
}

Le champ recommended_action peut avoir l'une des valeurs suivantes:

Valeur Description
RECOMMENDED_ACTION_UNSPECIFIED Indique que Account Defender n'a pas pu porter de jugement concernant cette demande.
SKIP_2FA Indique que Account Defender estime qu'il est possible 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 une question MFA pour l'utilisateur. Pour en savoir plus, consultez la réponse de l'évaluation Account Defender.

Déclenchez un défi MFA sur votre site Web

Pour interroger l'utilisateur sur la base des informations contenues dans l'évaluation, renvoyez l'requestToken MFA du point de terminaison que vous souhaitez vérifier depuis 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 une authentification MFA, procédez comme suit:

  1. Testez l'intégration MFA.

    Déclenchez un test MFA via un appel à challengeAccount() en fournissant les valeurs suivantes:

    • KEY_ID: clé basée sur les scores que vous avez installée sur votre site Web.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valeur du champ requestToken de la réponse d'évaluation.
    • CONTAINER_HTML_COMPONENT_ID: ID du composant HTML dans lequel la question d'authentification 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 la question d'authentification 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 vous permettre de saisir le code reçu. Une fois le bon code PIN saisi, la variable newToken est transmise à la fonction enchaînée contenant le jeton d'évaluation à vérifier via une évaluation créée dans le backend.

  2. Créez un identifiant de validation et lancez une question d'authentification 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 l'utilisateur final vous a envoyé le code, 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 section Créer une évaluation pour 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 L'envoi d'e-mails à ce destinataire n'est pas approuvé (pendant les 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).

Étapes suivantes