Auf dieser Seite wird beschrieben, wie Sie die Multi-Faktor-Authentifizierung (MFA) konfigurieren, mit der Sie die Identität Ihrer Nutzer überprüfen können, indem Sie einen Bestätigungscode per E-Mail senden. Mit dieser Funktion können Sie überprüfen, ob Ihre Nutzer Inhaber der E-Mail-Adresse sind, die mit ihrem Konto verknüpft ist. Mit MFA können Sie Ihre Nutzer vor Credential Stuffing-Angriffen und Kontoübernahmen (Account Takeovers, ATOs) schützen.
MFA ist für auf Punktzahlen basierende Schlüssel und nicht für Kästchenschlüssel verfügbar.
Informationen zum Konfigurationsprozess von MFA
Die MFA-Funktion von reCAPTCHA Enterprise wird zusätzlich zum regulären reCAPTCHA Enterprise-Workflow implementiert.
Auf übergeordneter Ebene sieht der MFA-Workflow so aus:
- Instrumentieren Sie den kritischen Workflow auf Ihrer Website.
- Erstellen Sie eine Bewertung mithilfe des vom
execute()-Aufruf zurückgegebenen Tokens und der MFA-Parameter, um eine MFA-requestTokenabzurufen. - Löse eine MFA-Abfrage mit der
requestTokenfür den Kanal aus, den du verwenden möchtest (nur E-Mail-Unterstützung unterstützt). - Bestätigen Sie die PIN, die der Endnutzer auf Ihrer Website eingegeben hat.
- Erstellen Sie eine neue Bewertung mithilfe des Tokens, das in der Überprüfungsanfrage zurückgegeben wird.
Hinweise
Die MFA ist nach einer Sicherheitsüberprüfung verfügbar. Wenden Sie sich an unser Vertriebsteam, um diese Funktion für Ihre Website einzurichten. Stellen Sie dem Vertriebsteam die folgenden Onboarding-Informationen zur Verfügung:
- Google Cloud-Projektnummer
- Zu einrichtende reCAPTCHA-Schlüssel
- Durchschnittliche Abfragen pro Sekunde (E-Mail-Nachrichten pro Sekunde)
- Spitzenwerte pro Sekunde (E-Mail-Nachrichten pro Sekunde)
- Für E-Mail-MFA die Absenderadresse und die E-Mail-Adressen oder Domains, die Sie während des Tests benötigen
So aktivieren Sie die E-Mail-Bestätigungsfunktion der MFA:
Rufen Sie in der Google Cloud Console die Seite reCAPTCHA Enterprise auf.
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 dann Ihr Projekt aus.
Klicken Sie auf Einstellungen.
Klicken Sie im Bereich Multi-Faktor-Authentifizierung auf Konfigurieren.
Führen Sie im Dialogfeld MFA konfigurieren die folgenden Schritte aus:
- Klicken Sie auf die Ein/Aus-Schaltfläche E-Mail aktivieren, um die E-Mail-Bestätigung zu aktivieren.
- Geben Sie Ihren Namen in das Feld Name des Absenders ein.
Geben Sie im Feld E-Mail-Adresse des Absenders Ihre E-Mail-Adresse ein.
Klicken Sie auf Speichern.
Den kritischen Workflow auf Ihrer Website instrumentieren
Übergeben Sie die erforderlichen Informationen über die Funktion execute() für die Risikobewertung an reCAPTCHA Enterprise. 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 auf Punktzahlen basierenden Schlüssel, den Sie für Ihre Website erstellt haben.
Bewertung erstellen
Erstellen Sie mit dem Token, das von der Funktion execute() generiert wird, eine Bewertung. Verwenden Sie dazu entweder die reCAPTCHA Enterprise-Clientbibliotheken oder die REST API aus Ihrem Back-End.
In diesem Dokument wird gezeigt, wie Sie mit der REST API eine Bewertung für MFA erstellen. Informationen zum Erstellen einer Bewertung mit Clientbibliotheken finden Sie unter Bewertungen für Websites erstellen.
Führen Sie die folgenden Schritte aus, bevor Sie eine Bewertung erstellen:
Richten Sie die Authentifizierung für reCAPTCHA Enterprise ein.
Die ausgewählte Authentifizierungsmethode hängt von der Umgebung ab, in der reCAPTCHA Enterprise eingerichtet wird. 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
Verwenden Sie angehängte Dienstkonten. Lokal oder anderer Cloud-Anbieter REST Verwenden Sie API-Schlüssel oder die Identitätsföderation von Arbeitslasten. Wenn Sie API-Schlüssel verwenden möchten, sollten Sie Einschränkungen für API-Schlüssel anwenden, um sie zu sichern.
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, sollten Sie Einschränkungen für API-Schlüssel anwenden, um sie zu sichern.
- Verwenden Sie für andere Sprachen die Identitätsföderation von Arbeitslasten.
Wählen Sie eine stabile Konto-ID
accountId, die nicht oft vom Nutzer geändert wird, und stellen Sie sie der Bewertung in der Methodeprojects.assessments.createzur Verfügung. Diese stabile Konto-ID sollte für alle Ereignisse desselben Nutzers denselben Wert haben. Du kannst 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 es als
accountIdverwenden. Wenn Sie solche websiteübergreifenden Kennungen (IDs, die websiteübergreifend wiederverwendet werden können) angeben, verwendet reCAPTCHA Enterprise diese Informationen, um den Schutz Ihrer Nutzerkonten anhand von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Kontokennungen gemeldet und das Wissen über websiteübergreifende Missbrauchsmuster im Zusammenhang mit diesen Kennungen genutzt.Wenn eine interne Nutzer-ID mit jedem Konto eindeutig verknüpft ist, können Sie sie auch als
accountIdangeben.Gehasht oder verschlüsselt
Wenn keine interne Nutzer-ID mit jedem Konto eindeutig verknüpft ist, können Sie eine beliebige stabile Kennung in eine intransparente, websitespezifische Konto-ID umwandeln. Diese Kennung wird weiterhin für reCAPTCHA Enterprise Account Defender benötigt, um Nutzeraktivitätsmuster zu verstehen und anomales Verhalten zu erkennen. Sie wird jedoch nicht für andere Websites verwendet.
Wählen Sie eine beliebige stabile Konto-ID aus und machen Sie sie undurchsichtig, bevor Sie sie an reCAPTCHA Enterprise senden. Verwenden Sie dazu Verschlüsselung oder Hashing:
Verschlüsselung (empfohlen): Verschlüsseln Sie die Kontokennung mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Geheimtext erzeugt. Eine ausführliche Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie sich für die symmetrische Verschlüsselung gegenüber der Hash-Technologie entscheiden, müssen Sie keine Zuordnung zwischen Ihren Nutzerkennungen und den entsprechenden intransparenten Nutzerkennungen vornehmen. Entschlüsseln Sie die intransparenten Kennungen, die von reCAPTCHA Enterprise zurückgegeben werden, um sie in die Nutzerkennungen umzuwandeln.
Hash-Technologie: Wir empfehlen, die Kontokennung mithilfe der SHA256-HMAC-Methode mit einem benutzerdefinierten Salt Ihrer Wahl zu hashen. Da Hashes nur einseitig sind, müssen Sie eine Zuordnung zwischen den generierten Hashes und Ihren Nutzerkennungen beibehalten, damit Sie die gehashten Konto-IDs, die zurückgegeben werden, den ursprünglichen Konten zuordnen können.
Fügen Sie den Parameter accountId und einen Endpunkt hinzu, z. B. eine E-Mail-Adresse, um sie bei der Bewertung in der Methode projects.assessments.create zu überprüfen.
Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:
- PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
- TOKEN: vom
grecaptcha.enterprise.execute()-Aufruf zurückgegebenes Token. - KEY_ID: der auf Punktzahlen basierende 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 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
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 für diesen Endpunkt eine MFA-Abfrage auslösen, müssen Sie diesen verschlüsselten String zurück an die Webseite senden. Die Anfragetokens sind 15 Minuten lang gültig.
Empfohlene Maßnahmen
Wenn Sie für Ihr Projekt reCAPTCHA Enterprise Account Defender aktiviert haben, enthält die Antwort auf die Bewertung neben den MFA-Informationen auch Informationen zu Account Defender. Im Feld recommended_action sehen Sie die möglichen Maßnahmen, die Sie ausführen können, bevor die MFA-Abfrage ausgelöst wird.
Das folgende Beispiel zeigt eine Beispielbewertung, bei der das Überspringen von MFA als empfohlene Maßnahme empfohlen wird:
{
[...],
"accountDefenderAssessment": {
labels: ["PROFILE_MATCH"],
"recommended_action": "SKIP_2FA"
}
}
Das Feld recommended_action kann einen der folgenden Werte enthalten:
| Wert | Beschreibung |
|---|---|
RECOMMENDED_ACTION_UNSPECIFIED |
Gibt an, dass der Account Defender diese Anfrage nicht beurteilen konnte. |
SKIP_2FA |
Gibt an, dass Account Defender es als sicher erachtet, MFA für diese Bewertung zu überspringen. Das bedeutet in der Regel, dass der Nutzer kürzlich für deine Website auf diesem Gerät bestätigt wurde. |
REQUEST_2FA |
Gibt an, dass Sie eine MFA-Abfrage für den Nutzer auslösen. Weitere Informationen finden Sie im Artikel Antwort von Account Defender. |
MFA-Identitätsbestätigung auf Ihrer Website auslösen
Um den Nutzer anhand der in der Bewertung enthaltenen Informationen herauszufordern, senden Sie die MFA-requestToken für den Endpunkt, den Sie von der Bewertung überprüfen 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-Anforderung aus:
Testen Sie die MFA-Integration.
Lösen Sie eine MFA-Abfrage mit einem Aufruf von
challengeAccount()aus. Geben Sie dazu die folgenden Werte an:- KEY_ID: der auf Punktzahlen basierende Schlüssel, den Sie auf Ihrer Website installiert haben.
- REQUEST_TOKEN_FROM_ASSESSMENT: Wert des Felds
requestTokenaus der Bewertungsantwort. - CONTAINER_HTML_COMPONENT_ID: ID der HTML-Komponente, in der die Identitätsbestätigung ausgeführt werden soll. 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 von
challengeAccount()ausgelöst wird: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 zur Eingabe der erhaltenen PIN angezeigt. Nachdem die richtige PIN eingegeben wurde, wird die VariablenewTokenan die verkettete Funktion übergeben, die das Ergebnistoken enthält, das durch eine im Back-End erstellte Bewertung überprüft werden soll.Erstellen Sie einen Bestätigungs-Alias und initiieren Sie eine Identitätsbestätigung 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 auf der Webseite prüfen
Nachdem du die PIN vom Endnutzer erhalten hast, musst du prüfen, ob sie korrekt ist.
Rufe zum Validieren der PIN verificationHandle.verifyAccount() mit der vom Endnutzer eingegebenen PIN auf.
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 dazu finden Sie unter 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 erhalten, wenn Sie eine neue Bewertung mit dem neuen Token von der Website erstellen:
{
[...],
"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 anzeigen (siehe folgende 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 nicht zum Senden von E-Mails an (nur während des Tests) 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). |