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.
Auf hoher Ebene 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
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 Seite reCAPTCHA 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 zum Aktivieren der E‑Mail-Bestätigung auf den Ein/Aus-Button E‑Mail aktivieren.
- Geben Sie im Feld Absendername Ihren Namen ein.
Geben Sie im Feld Absender-E‑Mail Ihre E‑Mail-Adresse ein.
Klicken Sie auf Speichern.
Nachdem Sie Ihre Absender-E‑Mail-Adresse 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 Versprechen 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 mit den reCAPTCHA-Clientbibliotheken oder der REST API aus Ihrem Backend.
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 bei 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 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 Folgendes:
- 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 Anwenden von API-Schlüsseleinschränkungen zu schützen.
- Verwenden Sie für andere Sprachen die Identitätsföderation von Arbeitslasten.
Wählen Sie eine stabile Konto-ID
accountIdaus, die vom Nutzer nicht oft geändert wird und geben Sie sie in derprojects.assessments.createMethode für die Bewertung 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 (IDs, 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 Kenntnisse über websiteübergreifende Missbrauchsmuster 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 reCAPTCHA 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 durch Verschlüsselung oder Hashing an reCAPTCHA senden:
Verschlüsselung (empfohlen): Verschlüsseln Sie die Konto-ID mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Geheimtext erzeugt. Eine detaillierte Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie die symmetrische Verschlüsselung dem Hashing vorziehen, müssen Sie keine Zuordnung zwischen Ihren Nutzer-IDs und den entsprechenden intransparenten Nutzer-IDs beibehalten. Entschlüsseln Sie die von reCAPTCHA zurückgegebenen intransparenten IDs, 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 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 den Parameter accountId und einen Endpunkt hinzu, z. B. eine E‑Mail-Adresse, die in der Bewertung in der projects.assessments.create Methode bestätigt werden soll.
Ersetzen Sie diese Werte in den folgenden 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 Account Defender
für Ihr Projekt aktiviert haben, enthält die Bewertungsantwort zusätzlich zu den Informationen zu MFA auch Informationen
zu Account Defender. 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 Aktion 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 Account Defender für diese Anfrage keine Entscheidung treffen konnte. |
SKIP_2FA |
Gibt an, dass Account Defender es für sicher hält, MFA für diese Bewertung zu überspringen. Das bedeutet in der Regel, dass der Nutzer kürzlich auf dieser Website auf diesem Gerät bestätigt wurde. |
REQUEST_2FA |
Gibt an, dass Sie eine MFA-Herausforderung für den Nutzer auslösen. Weitere Informationen finden Sie unter Bewertungsantwort von Account Defender. |
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, indem Sie die folgenden Werte angeben:- 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 zum Bestätigen 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 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 mit dem von der Website abgerufenen neuen Token eine neue Bewertung 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 haben, 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). |