Multi-Faktor-Authentifizierung konfigurieren

Auf dieser Seite wird beschrieben, wie Sie die Multi-Faktor-Authentifizierung (MFA) konfigurieren, mit der Sie die Identität Ihrer Nutzer bestätigen können, indem Sie einen Bestätigungscode per E-Mail senden. Mit diesem Feature können Sie prüfen, ob Ihre Nutzer die E-Mail-Adresse haben, die mit ihrem Konto verknüpft ist. MFA kann dabei helfen, Ihre Nutzer vor Credential Stuffing-Angriffen und Kontoübernahmen (ATOs) zu schützen.

MFA ist für punktebasierte Schlüssel verfügbar und nicht für Kästchenschlüssel.

Informationen zum Konfigurationsprozess von MFA

Die MFA-Funktion von reCAPTCHA wird zusätzlich zum regulären reCAPTCHA-Ablauf implementiert.

Auf übergeordneter Ebene sieht der MFA-Workflow so aus:

1. Instrumentieren Sie den kritischen Workflow auf Ihrer Website.
2. Erstellen Sie eine Bewertung mit dem Token, das vom execute()-Aufruf zurückgegeben wird, und den MFA-Parametern, um eine MFA-requestToken zu erhalten.
3. MFA-Herausforderung auslösen mit requestToken, je nach Kanal, den Sie verwenden möchten (nur E-Mail wird unterstützt).
4. Die vom Endnutzer eingegebene PIN auf Ihrer Website bestätigen
5. Erstellen Sie eine neue Bewertung mit dem Token, das in der Bestätigungsanfrage zurückgegeben wird.

Hinweise

1. Umgebung für reCAPTCHA vorbereiten

2. Die MFA ist nach einer Sicherheitsüberprüfung verfügbar, die initiiert wird, wenn Sie Ihrem Projekt ein Rechnungskonto hinzufügen. Fügen Sie ein Rechnungskonto hinzu, um Ihre Website auf dieses Feature umzustellen.

3. So aktivieren Sie die E‑Mail-Bestätigungsfunktion der MFA:

   1. Rufen Sie in der Google Cloud Console die Seite reCAPTCHA auf.

      Zu reCAPTCHA

   2. Prüfen Sie, ob der Name Ihres Projekts in der Ressourcenauswahl angezeigt wird.

      Wenn Sie den Namen Ihres Projekts nicht sehen, klicken Sie auf die Ressourcenauswahl und wählen Sie Ihr Projekt aus.

   3. Klicken Sie auf settingsEinstellungen.

   4. Klicken Sie im Bereich Multi-Faktor-Authentifizierung auf Konfigurieren.

   5. Führen Sie im Dialogfeld MFA konfigurieren die folgenden Schritte aus:

      1. Klicken Sie auf die Ein/Aus-Schaltfläche E-Mail aktivieren, um die E-Mail-Bestätigung zu aktivieren.
      2. Geben Sie im Feld Absendername Ihren Namen ein.

      3. Geben Sie im Feld E-Mail-Adresse des Absenders Ihre E-Mail-Adresse ein.

         

   6. Klicken Sie auf Speichern.

4. reCAPTCHA auf Ihrer Website mit auf Punktzahlen basierenden Schlüsseln einrichten

Kritischen Workflow auf Ihrer Website instrumentieren

Übergeben Sie die erforderlichen Informationen über die Funktion execute() für die Risikobewertung an reCAPTCHA. Die execute()-Funktion gibt ein Versprechen zurück, das bei der Tokengenerierung aufgelöst wird.

Hängen Sie einen zusätzlichen twofactor-Parameter an die Funktion execute() an, wie im folgenden Beispielcode gezeigt:

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

Ersetzen Sie KEY_ID durch den punktebasierten Schlüssel, den Sie für Ihre Website erstellt haben.

Bewertung erstellen

Mit dem Token, das von der execute()-Funktion generiert wurde, erstellen Sie eine Bewertung mit den reCAPTCHA-Clientbibliotheken oder der REST API aus Ihrem Backend.

In diesem Dokument wird beschrieben, wie Sie mit der REST API eine Bewertung für die Multi-Faktor-Authentifizierung erstellen. Weitere Informationen zum Erstellen von Bewertungen mit Clientbibliotheken

Führen Sie vor dem Erstellen einer Prüfung die folgenden Schritte aus:

• Richten Sie die Authentifizierung für reCAPTCHA ein.

  Die von Ihnen gewählte Authentifizierungsmethode hängt von der Umgebung ab, in der reCAPTCHA eingerichtet ist. Die folgende Tabelle hilft Ihnen bei der Auswahl der geeigneten Authentifizierungsmethode und der unterstützten Schnittstelle zum Einrichten der Authentifizierung:

  Umgebung	Schnittstelle	Authentifizierungsmethode
  Google Cloud	REST Clientbibliotheken	Angehängte Dienstkonten verwenden.
  Lokal oder bei einem anderen Cloud-Anbieter	REST	Verwenden Sie API-Schlüssel oder die Workload Identity-Föderation. Wenn Sie API-Schlüssel verwenden möchten, empfehlen wir, sie durch Einschränkungen für API-Schlüssel zu schützen.
  	Clientbibliotheken	Verwenden Sie: Verwenden Sie für Python oder Java API-Schlüssel oder die Identitätsföderation von Arbeitslasten. Wenn Sie API-Schlüssel verwenden möchten, empfehlen wir, sie durch Einschränkungen für API-Schlüssel zu schützen. Verwenden Sie für andere Sprachen die Workload Identity-Föderation.

• Wählen Sie eine stabile Konto-ID accountId aus, die vom Nutzer nicht oft geändert wird, und geben Sie sie in der Methode projects.assessments.create für die Bewertung an. Diese stabile Konto-ID sollte für alle Ereignisse, die sich auf denselben Nutzer beziehen, denselben Wert haben. Sie können Folgendes als Konto-ID angeben:

  Nutzerkennungen

  Wenn jedes Konto eindeutig mit einem stabilen Nutzernamen, einer E‑Mail-Adresse oder einer Telefonnummer verknüpft werden kann, können Sie diese als accountId verwenden. Wenn Sie solche websiteübergreifenden Kennungen (Kennungen, die auf mehreren Websites wiederverwendet werden können) angeben, verwendet reCAPTCHA diese Informationen, um den Schutz Ihrer Nutzerkonten auf Grundlage von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Konto-IDs gekennzeichnet und Informationen zu websiteübergreifenden Missbrauchsmustern im Zusammenhang mit diesen Kennungen verwendet.

  Wenn Sie eine interne Nutzer-ID haben, die eindeutig jedem Konto zugeordnet ist, können Sie diese als accountId angeben.

  Gehasht oder verschlüsselt

  Wenn Sie keine interne Nutzer-ID haben, die eindeutig mit jedem Konto verknüpft ist, können Sie jede stabile ID in eine undurchsichtige, websitespezifische Konto-ID umwandeln. Diese ID ist weiterhin erforderlich, damit reCAPTCHA Account Defender Muster der Nutzeraktivität erkennen und anomales Verhalten erkennen kann. Sie wird jedoch nicht an andere Websites weitergegeben.

  Wählen Sie eine beliebige stabile Konto-ID aus und machen Sie sie undurchsichtig, bevor Sie sie an reCAPTCHA senden. Verwenden Sie dazu Verschlüsselung oder Hashing:

  • Verschlüsselung (empfohlen): Verschlüsseln Sie die Konto-ID mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Chiffretext erzeugt. Eine ausführliche Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie sich für die symmetrische Verschlüsselung anstelle des Hashings entscheiden, müssen Sie keine Zuordnung zwischen Ihren Nutzerkennungen und den entsprechenden undurchsichtigen Nutzerkennungen vornehmen. Entschlüsseln Sie die intransparenten Kennzeichnungen, die von reCAPTCHA zurückgegeben werden, um sie in die Nutzer-ID umzuwandeln.

  • Hashing: Wir empfehlen, die Konto-ID mit der SHA256-HMAC-Methode und einem benutzerdefinierten Salt Ihrer Wahl zu hashen. Da Hashes nur in eine Richtung funktionieren, müssen Sie eine Zuordnung zwischen den generierten Hashes und Ihren Nutzer-IDs beibehalten, damit Sie die zurückgegebenen gehashten Konto-IDs den ursprünglichen Konten zuordnen können.

Fügen Sie der Methode projects.assessments.create den Parameter accountId und einen Endpunkt hinzu, z. B. eine E-Mail-Adresse, die in der Bewertung bestätigt werden soll.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• PROJECT_ID: Ihre Google Cloud -Projekt-ID.
• TOKEN: vom Aufruf grecaptcha.enterprise.execute() zurückgegebenes Token.
• KEY_ID: Der schlüsselbasierte Schlüssel, den Sie auf Ihrer Website installiert haben.
• ACCOUNT_ID: Eine für Ihre Website eindeutige Kennung für ein Nutzerkonto.
• EMAIL_ID: die E-Mail-Adresse, für die der Bestätigungsantrag ausgelöst werden muss.

HTTP-Methode und URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

JSON-Text der Anfrage:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
       "accountId": "ACCOUNT_ID"
    }
  }
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "EMAIL_ID",
    }]
  }
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

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"

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Die Bewertung enthält das Datum und die Uhrzeit der letzten erfolgreichen Bestätigung der angegebenen Endpunkte auf dem Gerät, auf dem das Token ausgestellt wurde, sofern vorhanden. Es enthält außerdem ein requestToken-Feld pro Endpunkt, das einen verschlüsselten String enthält. Wenn Sie eine MFA-Herausforderung für diesen Endpunkt auslösen möchten, müssen Sie diesen verschlüsselten String an die Webseite zurücksenden. Die Anfragetokens sind 15 Minuten lang gültig.

Empfohlene Maßnahmen

Wenn reCAPTCHA Account Defender für Ihr Projekt aktiviert ist, enthält die Bewertungsantwort zusätzlich zu den Informationen zur MFA auch Informationen zu Account Defender. Im Feld recommended_action wird die mögliche Aktion angezeigt, die Sie ausführen können, bevor die MFA-Herausforderung ausgelöst wird.

Das folgende Beispiel zeigt eine Beispielbewertung, in der „MFA überspringen“ als empfohlene Aktion angezeigt wird:

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

Das Feld recommended_action kann einen der folgenden Werte haben:

MFA-Herausforderung auf Ihrer Website auslösen

Wenn Sie den Nutzer anhand der in der Bewertung enthaltenen Informationen zur MFA auffordern möchten, senden Sie das MFA-requestToken für den zu prüfenden Endpunkt von der Bewertung an die Webseite zurück.

Lösen Sie die MFA-Herausforderung mit einem Aufruf von challengeAccount(). Die challengeAccount()-Funktion gibt ein Versprechen zurück, das nach Abschluss der Herausforderung behoben wird oder abgelehnt wird, wenn ein Fehler oder eine Zeitüberschreitung aufgetreten ist. Nach Abschluss wird ein neues Token generiert, das aktualisierte Informationen enthält, die dann zur Bewertung gesendet werden.

So lösen Sie eine MFA-Herausforderung aus:

1. MFA-Integration testen

   Lösen Sie eine MFA-Herausforderung mit einem Aufruf von challengeAccount() aus und geben Sie die folgenden Werte an:

   • KEY_ID: Der schlüsselbasierte Schlüssel, den Sie auf Ihrer Website installiert haben.
   • REQUEST_TOKEN_FROM_ASSESSMENT: Wert des Felds requestToken aus der Bewertungsantwort.
   • CONTAINER_HTML_COMPONENT_ID: ID der HTML-Komponente, in der die Bestätigungsaufforderung gerendert werden muss. Wenn Sie diesen Parameter nicht angeben, wird die Aufforderung in einer Überlagerung über der Seite gerendert.

   Das folgende Beispiel zeigt, wie Sie die MFA-Herausforderung mit einem Aufruf von challengeAccount() auslösen:

   grecaptcha.enterprise.challengeAccount(KEY_ID, {
     'account-token': REQUEST_TOKEN_FROM_ASSESSMENT,
     'container': CONTAINER_HTML_COMPONENT_ID
   }).then(newToken => {
     // Handle the new token.
   });
   

   Wenn die challengeAccount()-Anfrage erfolgreich ist, wird die HTML-Komponente angezeigt, in die die empfangene PIN eingegeben werden kann. Nachdem die richtige PIN eingegeben wurde, wird die Variable newToken an die verkettete Funktion übergeben, die das zu überprüfende Ergebnis-Token enthält. Die Überprüfung erfolgt über eine Bewertung, die im Backend erstellt wird.

2. Erstellen Sie einen Bestätigungs-Handle und starten Sie eine Challenge mit den folgenden Parametern:

   // 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
       }
     });
   

MFA-Code über die Webseite bestätigen

Nachdem Sie die PIN vom Endnutzer erhalten haben, müssen Sie prüfen, ob sie korrekt ist.

Rufen Sie verificationHandle.verifyAccount() mit der vom Endnutzer eingegebenen PIN auf, um die PIN zu validieren.

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
  }
);

Neue Bewertung erstellen

Erstellen Sie eine neue Bewertung mit accountId und endpoints. Eine Anleitung finden Sie unter Bewertung für die 2‑Faktor-Authentifizierung erstellen.

Nachdem der Workflow auf dem Client abgeschlossen ist, erhalten Sie ein neues Token, mit dem Sie das Resultat der von Ihnen ausgelösten Bestätigungsaufforderung abrufen können. Die Bewertung enthält einen aktuellen Zeitstempel für die letzte erfolgreiche Bestätigung sowie einen Erfolgsergebnisstatus.

Das folgende Beispiel zeigt eine Beispielbewertung, die Sie bei der Erstellung einer neuen Bewertung mit dem von der Website abgerufenen neuen Token erhalten:

{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "2020-03-23 08:27:12 PST",
    }],
    "latestVerificationResult": "SUCCESS_USER_VERIFIED"
  }
}

Das Feld latestVerificationResult kann einen anderen Status zeigen, wie in der folgenden Tabelle aufgeführt:

Nächste Schritte

• Betrügerische Aktivitäten im Zusammenhang mit Konten mit reCAPTCHA Account Defender erkennen und verhindern