Multi-Faktor-Authentifizierung konfigurieren

Auf dieser Seite wird beschrieben, wie Sie die Multi-Faktor-Authentifizierung (MFA) konfigurieren, mit der bestätigen Sie die durch Senden eines Bestätigungscodes per E-Mail. Mit dieser Funktion können Sie überprüfen, ob Ihren Nutzern die E-Mail-Adresse gehört, die mit ihrem Konto verknüpft sind. 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 zur regulären reCAPTCHA zu optimieren.

Der MFA-Workflow sieht in etwa so aus:

  1. Instrumentieren Sie den kritischen Workflow auf Ihrer Website.
  2. Erstellen Sie eine Bewertung. Verwenden Sie dazu das vom execute()-Aufruf zurückgegebene Token und die MFA-Parameter, um ein MFA-requestToken zu erhalten.
  3. Lösen Sie eine MFA-Herausforderung mit der requestToken aus, die dem gewünschten Kanal entspricht (nur E-Mail wird unterstützt).
  4. Prüfen Sie die vom Endnutzer auf Ihrer Website eingegebene PIN.
  5. Erstellen Sie eine neue Bewertung mit dem Token, das wird in der Bestätigungsanfrage zurückgegeben.

Hinweise

  1. Umgebung für reCAPTCHA vorbereiten

  2. Die MFA ist nach einer Sicherheitsüberprüfung verfügbar, die gestartet wird, wenn Sie Ihrem Projekt ein Abrechnungskonto hinzufügen. Fügen Sie ein Abrechnungskonto hinzu, um Ihre Website auf diese Funktion 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 Einstellungen.

    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 in das Feld Name des Absenders Ihren Namen ein.

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

    6. Klicken Sie auf Speichern.

  4. Richten Sie reCAPTCHA mit wertbasierten Schlüsseln auf Ihrer Website ein.

Kritische Workflows 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 wertbasierten Schlüssel, der die Sie für Ihre Website erstellt haben.

Bewertung erstellen

Mit dem Token, das von execute() generiert wird erstellen Sie eine Bewertung mit dem reCAPTCHA- Clientbibliotheken oder die REST API von Ihrem Back-End aus.

In diesem Dokument wird gezeigt, wie Sie mit der REST API eine MFA-Bewertung erstellen. Informationen zum Erstellen einer Bewertung mit Clientbibliotheken finden Sie unter Bewertungen für Websites erstellen.

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

  • Richten Sie die Authentifizierung bei reCAPTCHA ein.

    Welche Authentifizierungsmethode Sie auswählen, hängt von der Umgebung ab, in der reCAPTCHA ist eingerichtet. In der folgenden Tabelle finden Sie Informationen zur Auswahl der geeigneten Authentifizierungsmethode und der unterstützten Benutzeroberfläche für die Authentifizierung:

    Umgebung Schnittstelle Authentifizierungsmethode
    Google Cloud
    • REST
    • Clientbibliotheken
    		 Verwenden Sie angehängte Dienstkonten.
    Lokal oder ein anderer Cloud-Anbieter REST Verwenden Sie API-Schlüssel oder die Workload Identity-Föderation.

    Wenn Sie API-Schlüssel verwenden möchten, empfehlen wir, die API-Schlüssel durch Anwenden von Einschränkungen für API-Schlüssel zu sichern.
    Clientbibliotheken

    Verwenden Sie:

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

    Nutzerkennungen

    Jedes Konto kann eindeutig einem stabilen Nutzernamen, einer E-Mail-Adresse oder einer Telefonnummer zugeordnet werden. können Sie sie als accountId verwenden. Wenn Sie solche websiteübergreifenden (Kennungen, die websiteübergreifend wiederverwendet werden können), verwendet reCAPTCHA diese um den Schutz Ihrer Nutzerkonten auf der Grundlage von websiteübergreifenden Modellen zu verbessern, indem Missbrauch von Konto-IDs melden und Kenntnis von websiteübergreifenden Missbrauchsmustern im Zusammenhang mit zu diesen IDs.

    Alternativ können Sie eine interne Nutzer-ID angeben, die jedem Konto eindeutig zugeordnet ist.

    Gehasht oder verschlüsselt

    Wenn Sie keine interne Nutzer-ID haben, die eindeutig mit jedem Konto verknüpft ist, können Sie jede stabile Kennung in eine undurchsichtige, websitespezifische Konto-ID umwandeln. Diese Kennung ist weiterhin erforderlich, damit reCAPTCHA Account Defender die Nutzeraktivitätsmuster nachvollziehen und anormales Verhalten erkennen kann. Sie wird jedoch nicht für andere Websites freigegeben.

    Wählen Sie eine beliebige stabile Konto-ID aus und machen Sie sie vor dem Senden an reCAPTCHA undurchsichtig, indem Sie durch Verschlüsselung oder Hash-Technologie:

    • Verschlüsselung (empfohlen): Verschlüsseln Sie die Konto-ID mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Geheimtext erzeugt. Eine ausführliche Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie symmetrische Verschlüsselung statt Hashing verwenden, Zuordnung zwischen Ihren Nutzer-IDs und den entsprechenden intransparenten Nutzer-IDs. Entschlüsseln Sie die von reCAPTCHA zurückgegebenen opaken Kennungen, um sie in den User-ID.

    • Hash-Technologie: Wir empfehlen, die Konto-ID mit der SHA256-HMAC-Methode mit 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 gehashte Konto-ID, die zurückgegeben wird, den ursprünglichen Konten zuordnen können.

Fügen Sie den Parameter accountId und einen Endpunkt wie eine E-Mail-Adresse hinzu in der Bewertung mit der Methode projects.assessments.create bestätigen.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

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

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl 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"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$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 in etwa folgende JSON-Antwort 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 gültig für 15 Minuten.

Wenn Sie reCAPTCHA Account Defender für Ihr Projekt aktiviert haben, enthält die Antwort auf die Bewertung neben den Informationen zur MFA auch Informationen zu Account Defender. Im Feld recommended_action sehen Sie die möglichen Aktionen, die Sie ausführen können, bevor die MFA-Aufforderung ausgelöst wird.

Das folgende Beispiel zeigt eine Beispielbewertung, in der das Überspringen der MFA als empfohlene Maßnahme angezeigt wird:

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

Das Feld recommended_action kann einen der folgenden Werte haben:

Wert Beschreibung
RECOMMENDED_ACTION_UNSPECIFIED Gibt an, dass der Kontobeschützer keine Entscheidung für diese Anfrage treffen konnte.
SKIP_2FA Gibt an, dass Account Defender es für sicher hält, die MFA für diese Bewertung zu überspringen. Das bedeutet in der Regel, dass der Nutzer kürzlich für Ihre Website auf diesem Gerät überprüft wurde.
REQUEST_2FA Gibt an, dass Sie eine MFA-Abfrage für den Nutzer auslösen. Weitere Informationen finden Sie unter Antwort auf die Kontobewertung durch Account Defender.

MFA-Aufgabe auf Ihrer Website auslösen

Wenn Sie den Nutzer anhand der in der Bewertung enthaltenen Informationen zur Bestätigung auffordern möchten, senden Sie das MFA-requestToken für den Endpunkt, den Sie von der Bewertung aus bestätigen möchten, zurück an die Webseite.

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 die MFA-Herausforderung mit einem Aufruf von challengeAccount() aus. Geben Sie dazu die folgenden Werte an:

    • KEY_ID: der leistungsbasierte Schlüssel, den Sie auf Ihrer Website installiert haben.
    • REQUEST_TOKEN_FROM_ASSESSMENT: Wert von requestToken aus der Bewertungsantwort.
    • CONTAINER_HTML_COMPONENT_ID: ID der HTML-Komponente in dem die Identitätsbestätigung erfolgen muss. Wenn Sie diesen Parameter nicht angeben, wird die Aufforderung in einer Überlagerung über der Seite gerendert.

    Das folgende Beispiel zeigt, wie die MFA-Abfrage mit einem Aufruf an challengeAccount():

    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 zum Eingeben der empfangenen PIN angezeigt. Nach Eingabe der richtigen PIN wird das Symbol Die Variable newToken wird an die verkettete Funktion übergeben, die Folgendes enthält: Ergebnis-Token mit einer im Back-End erstellten Bewertung überprüft werden.

  2. Erstelle einen Bestätigungs-Handle und starte eine Aufgabe 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 verifizieren

Nachdem Sie die PIN vom Endnutzer erhalten haben, müssen Sie bestätigen, dass die PIN oder nicht.

Rufe zum Bestätigen der PIN verificationHandle.verifyAccount() an Endanwendenden eingegeben werden.

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. Anweisungen finden Sie unter eine Bewertung für MFA 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 beim Erstellen einer neuen Bewertung mit dem neuen Token erhalten, das Sie von der Website abgerufen haben:

{
  [...],
  "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 haben, wie hier aufgeführt in der folgenden Tabelle:

Ergebnisstatus der Bestätigung Beschreibung
SUCCESS_USER_VERIFIED Der Nutzer wurde bestätigt.
ERROR_USER_NOT_VERIFIED Der Nutzer hat die Bestätigungsaufforderung nicht bestanden.
ERROR_SITE_ONBOARDING_INCOMPLETE Ihre Website wird nicht ordnungsgemäß eingerichtet, um dieses Feature zu nutzen.
ERROR_RECIPIENT_NOT_ALLOWED Dieser Empfänger ist während des Tests nicht zum Senden von E-Mails an zugelassen )
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Dieser Empfänger hat bereits zu viele Bestätigungscodes in kurzer Zeit erhalten.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Sie haben Ihr verfügbares MFA-Kontingent überschritten.
ERROR_CRITICAL_INTERNAL Die Verifizierung wurde aufgrund eines internen Fehlers in unseren Systemen nicht abgeschlossen.
RESULT_UNSPECIFIED Keine Informationen zur letzten Bestätigung (nie bestätigt).

Nächste Schritte