Configurer l'authentification multi-facteurs

Cette page explique comment configurer l'authentification multifacteur (MFA, Multifactor Authentication) qui vous permet de valider 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 possèdent bien l'adresse e-mail ou le numéro de téléphone associé à leur compte. La MFA permet de protéger vos utilisateurs contre les attaques de credential stuffing et les piratages de compte.

Elle est disponible pour les clés de site basées sur les scores et n'est pas disponible pour les clés de site de cases à 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éter les informations MFA dans l'évaluation.
  3. Déclencher un défi MFA pour 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 a bien été validé.

Avant de commencer

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

  2. Elle est accessible après un examen de sécurité. Contactez notre équipe commerciale pour activer cette fonctionnalité sur votre site.

  3. Intégrez reCAPTCHA Enterprise aux plates-formes pour lesquelles vous souhaitez activer l'authentification multifacteur 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 lors de la génération du jeton.

Sur les sites Web

Ajoutez un paramètre twofactor supplémentaire à la 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é parexecute(), envoyez une requête d'évaluation à l'aide de la méthodeBibliothèques clientes reCAPTCHA Enterprise ou l'applicationoutil 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 à vérifier dans l'évaluation. L'identifiant haché du compte est un identifiant anonyme et unique pour un compte utilisateur propre à votre site Web. Utilisez un hachage unidirectionnelle d'un identifiant de compte stable. Nous vous recommandons d'utiliser le schéma 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é réussit, l'évaluation doit contenir plus d'informations relatives à l'authentification multifacteur ( celui-ci), comme illustré dans l'exemple suivant:

{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "",
    },
    {
      "phoneNumber": "+11111111111",
      "requestToken": "fwdgk0kcg1W0mbpetYlgTZKyrp4IHKzjgRkb6vLNZeBQhWdR3a",
      "lastVerificationTime": "",
    }],
    "latestVerificationResult": "RESULT_UNSPECIFIED"
  }
}

L'évaluation contient la date et l'heure de la dernière vérification réussie pour les points de terminaison donnés sur l'appareil ayant émis le jeton, le cas échéant. Il contient également un champ requestToken par point de terminaison, qui contient une chaîne chiffrée. Si vous décidez de déclencher un défi 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 défi MFA pour le client

Si vous avez décidé de remettre en question l'utilisateur sur la base des informations contenues dans l'évaluation, envoyez le jeton de requête MFA pour le point de terminaison que vous souhaitez valider à partir du client. Ce jeton de requête est nécessaire pour déclencher le défi MFA.

Déclenchez le défi MFA en appelant challengeAccount(). La fonction challengeAccount() renvoie une promesse qui est résolue après la résolution du défi, ou refusée en cas d'erreur ou d'expiration du délai. Une fois l'opération terminée, un nouveau jeton contenant les informations mises à jour est généré, qui est ensuite envoyé pour évaluation.

Sur les sites Web

Déclenchez le défi MFA avec un appel à la fonction challengeAccount(), comme illustré dans l'exemple suivant.

Indiquez les valeurs suivantes :

  • REQUEST_TOKEN_FROM_ASSESSMENT: valeur du champ requestToken de la réponse d'évaluation.
  • CONTAINER_HTML_COMPONENT_ID: ID d'un composant HTML dans lequel la question d'authentification à la validation doit être affichée. Si vous ne spécifiez pas ce paramètre, la question est affichée en 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 le défi MFA en appelant challengeAccount() depuis 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 ...
           }

         }
       });

Une fois que vous avez 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 défi 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.
}

Une fois que vous avez reçu 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 vérification déclenchée. L'évaluation contient un horodatage récent relatif à la dernière validation réussie, ainsi qu'un état de résultat réussi.

L'exemple suivant montre un exemple d'évaluation que vous recevez lors de la demande d'une nouvelle évaluation à l'aide du 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 é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 la question d'authentification à la validation.
ERROR_SITE_ONBOARDING_INCOMPLETE Votre site n'est pas correctement intégré pour utiliser cette fonctionnalité.
ERROR_RECIPIENT_NOT_ALLOWED Ce destinataire n'est pas autorisé à envoyer des SMS ou des e-mails à des fins de test uniquement.
ERROR_RECIPIENT_FETCH_LIMIT_EXHAUSTED Ce destinataire a déjà reçu un trop grand nombre de codes de validation sur une courte période.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Vous avez dépassé votre quota MFA disponible.
ERROR_CRITICAL_INTERNAL La validation n'est pas terminée en raison d'une erreur interne dans nos systèmes.
RESULT_UNSPECIFIED Aucune information sur la dernière validation (jamais validée).