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 (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 über den regulären reCAPTCHA-Workflow implementiert.
Der MFA-Workflow sieht in etwa so aus:
- Instrumentieren Sie den kritischen Workflow auf Ihrer Website.
- Erstellen Sie eine Bewertung. Verwenden Sie dazu das vom
execute()-Aufruf zurückgegebene Token und die MFA-Parameter, um ein MFA-requestTokenzu erhalten. - Lösen Sie eine MFA-Herausforderung mit der
requestTokenaus, die dem gewünschten Kanal entspricht (nur E-Mail wird unterstützt). - Prüfen Sie die vom Endnutzer auf Ihrer Website eingegebene PIN.
- Erstellen Sie eine neue Bewertung mit dem Token, das in der Bestätigungsanfrage zurückgegeben wird.
Hinweise
Die MFA ist nach einer Sicherheitsüberprüfung verfügbar, die gestartet wird, wenn Sie Ihrem Projekt ein Rechnungskonto hinzufügen. Fügen Sie ein Abrechnungskonto hinzu, um Ihre Website auf diese Funktion umzustellen.
So aktivieren Sie die E-Mail-Bestätigungsfunktion der MFA:
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.
Klicke 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 in das Feld Name des Absenders Ihren Namen ein.
Geben Sie im Feld E-Mail-Adresse des Absenders Ihre E-Mail-Adresse ein.
Klicken Sie auf Speichern.
Richten Sie reCAPTCHA auf Ihrer Website mithilfe von punktbasierten Schlüsseln ein.
Kritischen Workflow auf Ihrer Website erfassen
Ü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
Erstellen Sie mit dem Token, das von der execute()-Funktion generiert wurde, eine Bewertung. Verwenden Sie dazu entweder die reCAPTCHA-Clientbibliotheken oder die REST API aus Ihrem Backend.
In diesem Dokument wird gezeigt, wie Sie mit der REST API eine Bewertung für die Multi-Faktor-Authentifizierung 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 reCAPTCHA ein.
Die Authentifizierungsmethode, die Sie auswählen, hängt von der Umgebung ab, in der reCAPTCHA eingerichtet ist. 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 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 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, empfehlen wir, sie durch Einschränkungen für API-Schlüssel zu sichern.
- Für andere Sprachen verwenden Sie Workload Identity-Föderation.
Wählen Sie eine stabile Konto-ID
accountIdaus, die vom Nutzer nicht häufig geändert wird, und geben Sie sie in der Methodeprojects.assessments.createan. 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
accountIdverwenden. Wenn Sie solche websiteübergreifenden IDs angeben (IDs, die auf Websites wiederverwendet werden können), verwendet reCAPTCHA diese Informationen, um den Schutz Ihrer Nutzerkonten auf der Grundlage von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Konto-IDs gemeldet und Kenntnisse zu websiteübergreifenden Missbrauchsmustern in Bezug auf diese IDs genutzt.Wenn Sie eine interne Nutzer-ID haben, die eindeutig mit jedem Konto verknüpft ist, können Sie diese als
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 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 stabile Konto-ID aus und machen Sie sie undurchsichtig, bevor Sie sie an reCAPTCHA senden, indem Sie sie verschlüsseln oder hashen:
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 die symmetrische Verschlüsselung anstelle des Hashwerts verwenden, müssen Sie keine Zuordnung zwischen Ihren Nutzer-IDs und den entsprechenden undurchsichtigen Nutzer-IDs beibehalten. Entschlüsseln Sie die intransparenten Kennungen, die von reCAPTCHA zurückgegeben werden, um sie in die Nutzer-ID umzuwandeln.
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 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 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 eindeutige Kennung für ein Nutzerkonto auf Ihrer Website.
- 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 15 Minuten lang gültig.
Empfohlene Maßnahmen
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 vor Kurzem 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 Antwort auf die Kontobewertung durch Account Defender. |
MFA-Herausforderung 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, 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:
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 des Felds
requestTokenaus 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 die MFA-Herausforderung 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 zum Eingeben der empfangenen PIN angezeigt. Nachdem die richtige PIN eingegeben wurde, wird die VariablenewTokenan die verkettete Funktion übergeben, die das Urteilstoken enthält, das über eine im Backend erstellte Bewertung überprüft werden soll.Erstelle einen Bestätigungs-Handle und starte eine Bestätigungsanfrage 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 bestätigen
Nachdem Sie die PIN vom Endnutzer erhalten haben, müssen Sie prüfen, ob sie korrekt ist.
Rufe verificationHandle.verifyAccount() mit der vom Endnutzer eingegebenen PIN auf, um sie zu bestätigen.
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 Multi-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 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 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 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). |