Configurer l'authentification multi-facteurs

Cette page explique comment configurer l'authentification multifacteur (MFA, Multifactor Authentication) qui vous permet de vérifier l'identité de vos utilisateurs en envoyant un code de validation par e-mail ou par SMS. Grâce à cette fonctionnalité, vous pouvez vérifier que vos utilisateurs sont les détenteurs de l'adresse e-mail ou du numéro de téléphone associé à leur compte. L'authentification multifacteur peut vous aider à protéger vos utilisateurs contre les attaques de type "credential stuffing" (remplissage automatique des identifiants) et les piratages de compte.

L'authentification multifacteur est disponible pour les clés de site basées sur des scores, et non pour les clés de site de case à cocher.

Comprendre le processus de configuration de l'authentification multifacteur

Pour configurer l'authentification multifacteur, procédez comme suit :

  1. Instrumentez le workflow critique (connexion, inscription, etc.) sur le client.
  2. Demandez et interprétez les informations de l'authentification multifacteur dans l'évaluation.
  3. Déclenchez un défi MFA sur le client.
  4. Demandez une nouvelle évaluation pour vous assurer que l'adresse e-mail ou le numéro de téléphone de l'utilisateur ont bien été validés.

Avant de commencer

  1. Choisissez la meilleure méthode pour configurer reCAPTCHA Enterprise dans votre environnement et terminez la configuration.

  2. L'authentification multifacteur est accessible après un examen de sécurité. Contactez notre équipe commerciale pour intégrer votre site à cette fonctionnalité. Fournissez les informations d'intégration suivantes à l'équipe commerciale :

    • Numéro de projet Google Cloud
    • Clés de site à intégrer
    • RPS moyennes (e-mails/SMS par seconde)
    • Pic de requêtes par seconde (e-mails/SMS par seconde)
    • Pour la MFA par e-mail, l'adresse de l'expéditeur et les adresses e-mail ou les domaines dont vous avez besoin lors des tests
    • Pour la MFA par SMS, le pic d'utilisation et le nombre moyen de requêtes par seconde par pays de destination (pays de l'utilisateur)
  3. Intégrez reCAPTCHA Enterprise aux plates-formes pour lesquelles vous souhaitez activer la MFA en suivant les instructions spécifiques à la plate-forme :

Instrumenter le workflow critique sur le client

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.

Sur les sites Web

Ajoutez un paramètre twofactor supplémentaire à votre fonction execute(), comme indiqué dans l'exemple de code suivant :

grecaptcha.enterprise.execute(SITE_KEY, {
  action: 'login',
  twofactor: true
}).then(token => {
  /// Handle the generated token.
});

Sur Android :

Suivez les instructions pour générer un jeton pour votre application Android. Aucun paramètre supplémentaire n'est requis.

Sur iOS

Suivez les instructions pour générer un jeton pour votre application iOS. Aucun paramètre supplémentaire n'est requis.

Demander une évaluation

Avec le jeton généré par la fonction execute(), envoyez une requête d'évaluation à l'aide des bibliothèques clientes reCAPTCHA Enterprise ou de l'outil de ligne de commande gcloud pour l'authentification.

Fournissez un identifiant de compte haché et un ou plusieurs points de terminaison, tels qu'une adresse e-mail et un numéro de téléphone à valider dans l'évaluation. L'identifiant de compte haché est un identifiant anonyme et persistant pour un compte utilisateur propre à votre site Web. Utilisez un hachage unidirectionnel d'un identifiant de compte stable. Nous vous recommandons d'utiliser sha256-hmac avec un secret stable que vous ne partagez pas avec nous.

{
  "event": {
    "token": "token",
    "siteKey": "key",
    "hashedAccountId": "BP3ptt00D9W7UMzFmsPdEjNH3Chpi8bo40R6YW2b"
  },
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
    },
    {
      "phoneNumber": "+11111111111",
    }]
  }
}

Si l'intégration à la fonctionnalité aboutit, l'évaluation doit contenir plus d'informations concernant la MFA, comme indiqué dans l'exemple suivant :

{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "",
    },
    {
      "phoneNumber": "+11111111111",
      "requestToken": "fwdgk0kcg1W0mbpetYlgTZKyrp4IHKzjgRkb6vLNZeBQhWdR3a",
      "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 au client. Les jetons de requête sont valides pendant 15 minutes.

Déclencher un test MFA sur le client

Si vous avez décidé de soumettre l'utilisateur à un test sur la base des informations contenues dans l'évaluation, renvoyez au client le jeton de requête MFA du point de terminaison que vous souhaitez vérifier dans l'évaluation. Ce jeton de requête est requis pour déclencher l'authentification MFA.

Déclenchez le test MFA en appelant la méthode 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.

Sur les sites Web

Déclenchez un test MFA avec un appel à la fonction challengeAccount(), comme indiqué dans l'exemple suivant.

Indiquez les valeurs suivantes :

  • REQUEST_TOKEN_FROM_ASSESSMENT : valeur du champ requestToken de la réponse de l'évaluation.
  • CONTAINER_HTML_COMPONENT_ID : ID d'un composant HTML dans lequel le test de vérification doit être affiché. Si vous ne spécifiez pas ce paramètre, le test sera sera affiché dans une superposition sur la page.
grecaptcha.enterprise.challengeAccount(SITE_KEY, {
  'account-token': REQUEST_TOKEN_FROM_ASSESSMENT,
  'container': CONTAINER_HTML_COMPONENT_ID
}).then(newToken => {
  // Handle the new token.
});

Sur Android :

Déclenchez un test MFA en appelant challengeAccount() à partir d'un Context dans votre application.

Recaptcha.getClient(this)
   .challengeAccount(recaptchaHandle, requestToken)
   .addOnSuccessListener(
       this,
       new OnSuccessListener<VerificationHandle>() {
         @Override
         public void onSuccess(VerificationHandle handle) {
           VerificationHandle verificationHandle = handle;
           // Handle success ...
         }
       })
   .addOnFailureListener(
       this,
       new OnFailureListener() {
         @Override
         public void onFailure(@NonNull Exception e) {
           if (e instanceof ApiException) {
              ApiException apiException = (ApiException) e;
              Status apiErrorStatus = apiException.getStatusCode();
              // Handle API errors ...
           } else {
              // Handle other failures ...
           }

         }
       });

Après avoir obtenu le code de l'utilisateur, appelez verifyAccount() à partir d'un fichier Activity dans votre application pour vérifier que le code saisi est correct.

Recaptcha.getClient(this)
   .verifyAccount("userProvidedPIN", recaptchaHandle)
   .addOnSuccessListener(
       this,
       new OnSuccessListener<VerificationResult>() {
         @Override
         public void onSuccess(VerificationResult result) {
           if (result.getVerificationStatus().isSuccess()) {
             String recaptchaToken = result.recaptchaToken().orNull()
             // Handle success ...
           } else {
             VerificationHandle verificationHandle =
                              result.verificationHandle().orNull();
             Status errorStatus = result.getVerificationStatus();
             // Handle retries ...
           }
         }
       })
   .addOnFailureListener(
       this,
       new OnFailureListener() {
         @Override
         public void onFailure(@NonNull Exception e) {
           if (e instanceof ApiException) {
              ApiException apiException = (ApiException) e;
              Status apiErrorStatus = apiException.getStatusCode();
              // Handle API errors ...
           } else {
              // Handle other failures ...
           }
         }
       });

Sur iOS

Déclenchez le test MFA en appelant challengeAccount().

recaptchaClient.challengeAccount(withRequestToken: "Request Token").then { verificationHandler in
  // Show your UI and retrieve the pin from the user.
}.catch { error in
  // Handle error.
}

Après avoir obtenu le code de l'utilisateur, appelez la méthode verifyPin() de l'objet verificationHandler pour terminer la validation.

handler.verifyPin("PIN") { recaptchaToken, recaptchaError in
  // Handle token/error.
}

Demander une nouvelle évaluation

Demandez une nouvelle évaluation avec l'identifiant de compte haché et le champ endpoints.

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 illustre un exemple d'évaluation que vous recevez lors d'une requête de nouvelle évaluation utilisant le nouveau jeton obtenu auprès du client.

{
  [...],
  "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 statut 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 de SMS ou d'e-mails à ce destinataire n'est pas approuvé (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).