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 dieser Funktion 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 (Account Takeovers, ATOs) zu schützen.
MFA ist für auf Punktzahlen basierende Schlüssel verfügbar und nicht für Kästchenschlüssel.
Konfigurationsprozess für MFA
Die MFA-Funktion von reCAPTCHA wird zusätzlich zum regulären reCAPTCHA Workflow implementiert.
Im Großen und Ganzen sieht der MFA-Workflow so aus:
- Instrumentieren Sie den kritischen Workflow auf Ihrer Website.
- Erstellen Sie eine Bewertung mit
dem Token, das vom
execute()Aufruf zurückgegeben wird, und den MFA-Parametern , um ein MFArequestTokenzu erhalten. - Lösen Sie eine MFA-Herausforderung aus mit dem
requestTokengemäß dem gewünschten Kanal (nur E‑Mail wird unterstützt). - Bestätigen Sie die vom Endnutzer eingegebene PIN auf Ihrer Website.
- Erstellen Sie eine neue Bewertung mit dem Token, das in der Bestätigungsanfrage zurückgegeben wird.
Hinweis
Bereiten Sie Ihre Umgebung für Google Cloud Fraud Defense vor.
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 für diese Funktion zu registrieren.
Wenn Sie die E‑Mail-Bestätigungsfunktion von MFA aktivieren möchten, gehen Sie so vor:
Rufen Sie in der Google Cloud Console die reCAPTCHA Seite 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 Ihr Projekt aus.
Klicken Sie auf Einstellungen.
Klicken Sie im Bereich Multi-Faktor-Authentifizierung auf Konfigurieren.
Gehen Sie im Dialogfeld MFA konfigurieren so vor:
- Klicken Sie auf die Schaltfläche E‑Mail aktivieren, um die E‑Mail-Bestätigung zu aktivieren.
- Geben Sie im Feld Absendername Ihren Namen ein.
Geben Sie im Feld Absender-E‑Mail-Adresse Ihre E‑Mail-Adresse ein.
Klicken Sie auf Speichern.
Nachdem Sie die E‑Mail-Adresse des Absenders konfiguriert haben, konfigurieren Sie Ihre DNS-Einträge, um Zustellungsprobleme zu vermeiden. Ersetzen Sie in den folgenden Schritten
example.comdurch Ihre Domain.Fügen Sie einen SPF-Eintrag hinzu, damit reCAPTCHA in Ihrem Namen E‑Mails senden kann:
Host: example.com Value: v=spf1 include:_spf.recaptchamail.goog ~allFügen Sie die folgenden CNAME-Einträge für die Server hinzu, um die DKIM Signatur zu finden:
Host: recaptcha1._domainkey.example.com Value: recaptcha1._domainkey.recaptchamail.goog.Host: recaptcha2._domainkey.example.com Value: recaptcha2._domainkey.recaptchamail.goog.
Richten Sie reCAPTCHA auf Ihrer Website mit auf Punktzahlen basierenden Schlüsseln ein.
Instrumentieren Sie den kritischen Workflow auf Ihrer Website
Übergeben Sie die erforderlichen Informationen über die Funktion execute() für die Risikobewertung an reCAPTCHA. Die Funktion execute() gibt ein Promise zurück, das bei der Tokengenerierung aufgelöst wird.
Hängen Sie einen zusätzlichen Parameter twofactor 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 wurde, eine Bewertung. Verwenden Sie dazu entweder die reCAPTCHA-Clientbibliotheken oder die REST API von Ihrem Backend aus.
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 vor dem Erstellen einer Bewertung die folgenden Schritte aus:
Richten Sie die Authentifizierung für Fraud Defense ein.
Die von Ihnen gewählte Authentifizierungsmethode hängt von der Umgebung ab, in der Fraud Defense 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 API-Schlüssel oder Identitätsföderation von Arbeitslasten verwenden. Wenn Sie API-Schlüssel verwenden möchten, empfehlen wir, sie durch Anwenden von API-Schlüsseleinschränkungen zu schützen.
Clientbibliotheken Verwenden Sie:
- Für Python oder Java: API-Schlüssel oder Identitätsföderation von Arbeitslasten verwenden.
Wenn Sie API-Schlüssel verwenden möchten, empfehlen wir, sie durch Anwenden von API-Schlüsseleinschränkungen zu schützen.
- Für andere Sprachen: Identitätsföderation von Arbeitslasten verwenden.
Wählen Sie eine stabile Konto-ID
accountIdaus, die vom Nutzer nicht oft geändert wird und geben Sie sie in derprojects.assessments.createMethode an. Diese stabile Konto-ID sollte für alle Ereignisse im Zusammenhang mit demselben Nutzer denselben Wert haben. Sie können Folgendes als Konto-ID angeben:Nutzer-IDs
Wenn jedes Konto eindeutig mit einem stabilen Nutzernamen, einer stabilen E‑Mail-Adresse oder einer stabilen Telefon nummer verknüpft werden kann, können Sie diese als
accountIdverwenden. Wenn Sie solche websiteübergreifenden IDs angeben (IDs, die auf mehreren Websites wiederverwendet werden können), verwendet Fraud Defense 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 IDs verwendet.Alternativ können Sie, wenn Sie eine interne Nutzer-ID haben, die eindeutig mit jedem Konto verknüpft ist, diese als die
accountIdangeben.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 intransparente, websitespezifische Konto-ID umwandeln. Diese ID ist weiterhin erforderlich, damit Fraud Defense Account Defender Nutzeraktivitätsmuster erkennen und anomales Verhalten erkennen kann. Sie wird jedoch nicht auf anderen Websites geteilt.
Wählen Sie eine beliebige stabile Konto-ID aus und machen Sie sie intransparent, bevor Sie sie an Fraud Defense senden. Verwenden Sie dazu die Verschlüsselung oder das Hashing:
Verschlüsselung (empfohlen): Verschlüsseln Sie die Konto-ID mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Chiffretext erzeugt. Eine detaillierte Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie die symmetrische Verschlüsselung anstelle des Hashings verwenden, müssen Sie keine Zuordnung zwischen Ihren Nutzer-IDs und den entsprechenden intransparenten Nutzer-IDs aufbewahren. Entschlüsseln Sie die intransparenten IDs, die von Fraud Defense zurückgegeben werden, um sie in die Nutzer-ID umzuwandeln.
Hashing: Wir empfehlen, die Konto-ID mit der SHA256-HMAC-Methode mit einem benutzerdefinierten Salt Ihrer Wahl zu hashen. Da Hashes nur unidirektional sind, müssen Sie eine Zuordnung zwischen den generierten Hashes und Ihren Nutzer-IDs aufbewahren, damit Sie die zurückgegebenen gehashten Konto-IDs den ursprünglichen Konten zuordnen können.
Fügen Sie den accountId Parameter und einen Endpunkt hinzu, z. B. eine E‑Mail-Adresse, die in der Bewertung
bestätigt werden soll, in der projects.assessments.create Methode.
Ersetzen Sie folgende Werte in den Anfragedaten:
- PROJECT_ID: Projekt-ID in Google Cloud .
- TOKEN: Token, das vom Aufruf
grecaptcha.enterprise.execute()zurückgegeben wird. - KEY_ID: Der auf Punktzahlen basierende Schlüssel, den Sie auf Ihrer Website installiert haben.
- ACCOUNT_ID: Eine ID 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 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. Sie enthält außerdem ein Feld requestToken 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 Sie reCAPTCHA-Kontoschutz
für Ihr Projekt aktiviert haben, enthält die Bewertungsantwort neben den Informationen zu MFA auch Informationen
zu Kontoschutz. Im Feld recommended_action wird die mögliche Aktion angezeigt, die Sie ausführen können, bevor Sie die MFA-Herausforderung auslösen.
Das folgende Beispiel zeigt eine Beispielbewertung, in der „MFA überspringen“ 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 Kontoschutz für diese Anfrage keine Entscheidung treffen konnte. |
SKIP_2FA |
Gibt an, dass Kontoschutz es für sicher hält, MFA für diese Bewertung zu überspringen. Das bedeutet in der Regel, dass der Nutzer kürzlich auf diesem Gerät für Ihre Website bestätigt wurde. |
REQUEST_2FA |
Gibt an, dass Sie eine MFA-Herausforderung für den Nutzer auslösen. Weitere Informationen finden Sie unter Bewertungsantwort für Kontoschutz. |
MFA-Herausforderung auf Ihrer Website auslösen
Wenn Sie den Nutzer anhand der in der Bewertung enthaltenen Informationen abfragen 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() aus.
Die Funktion challengeAccount() 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:
Testen Sie die MFA-Integration.
Lösen Sie eine MFA-Herausforderung mit einem Aufruf von
challengeAccount()aus und geben Sie 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
requestTokenFelds 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 Anfrage
challengeAccount()erfolgreich ist, wird die HTML-Komponente angezeigt, in der die empfangene PIN eingegeben werden kann. Nachdem die richtige PIN eingegeben wurde, wird die VariablenewTokenan die verkettete Funktion übergeben, die das Ergebnis-Token enthält, das durch eine im Backend erstellte Bewertung bestätigt werden soll.Erstellen Sie ein Bestätigungshandle und initiieren Sie eine Herausforderung 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 von der Webseite bestätigen
Nachdem Sie die PIN vom Endnutzer erhalten haben, müssen Sie prüfen, ob die PIN korrekt ist.
Rufen Sie dazu 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 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 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:
| 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 berechtigt, E‑Mails an zu senden (nur während der Tests ). |
| 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). |