Questa pagina descrive come configurare l'autenticazione a più fattori (MFA) che ti consente di verificare l'identità degli utenti inviando un codice di verifica per email. Con questa funzionalità puoi verificare che gli utenti possiedano l'indirizzo email associato al loro account. L'MFA può contribuire a proteggere gli utenti dagli attacchi di Credential stuffing e dalle violazioni degli account (ATO).
L'MFA è disponibile per le chiavi basate sul punteggio e non è disponibile per le chiavi delle caselle di controllo.
Informazioni sul processo di configurazione dell'MFA
La funzionalità MFA di reCAPTCHA Enterprise è implementata in aggiunta al normale flusso di lavoro reCAPTCHA Enterprise.
A livello generale, il flusso di lavoro MFA è il seguente:
- Instrumenta il flusso di lavoro critico sul tuo sito web.
- Crea una valutazione utilizzando il token restituito dalla chiamata
execute()e i parametri MFA per ottenererequestTokenMFA. - Attiva una sfida MFA con
requestTokenin base al canale che vuoi utilizzare (sono supportati solo gli indirizzi email). - Verifica il PIN inserito dall'utente finale sul tuo sito web.
- Crea una nuova valutazione utilizzando il token restituito nella richiesta di verifica.
Prima di iniziare
L'autenticazione MFA è accessibile dopo un controllo di sicurezza. Contatta il nostro team di vendita per configurare il tuo sito su questa funzionalità. Fornisci le seguenti informazioni di onboarding al team di vendita:
- Numero di progetto Google Cloud
- Chiavi reCAPTCHA da integrare
- Media di QPS (messaggi email al secondo)
- Picco di QPS (messaggi email al secondo)
- Per l'MFA email, l'indirizzo del mittente e gli indirizzi email o i domini necessari durante il test
Se vuoi attivare la funzionalità di verifica email di MFA:
Nella console Google Cloud, vai alla pagina reCAPTCHA Enterprise.
Verifica che il nome del progetto venga visualizzato nel selettore di risorse.
Se non vedi il nome del progetto, fai clic sul selettore di risorse e seleziona il progetto.
Fai clic su Impostazioni.
Nel riquadro Autenticazione a più fattori, fai clic su Configura.
Nella finestra di dialogo Configura MFA, segui questi passaggi:
- Per attivare la verifica email, fai clic sul pulsante di attivazione/disattivazione Attiva email.
- Nella casella Nome mittente, inserisci il tuo nome.
Nella casella Email mittente, inserisci il tuo indirizzo email.
Fai clic su Salva.
Configura reCAPTCHA Enterprise sul tuo sito web utilizzando chiavi basate sul punteggio.
Definisci il flusso di lavoro critico sul tuo sito web
Passa le informazioni necessarie a reCAPTCHA Enterprise tramite la
funzione execute() per la valutazione del rischio. La funzione execute() restituisce una promessa che viene risolta al momento della generazione del token.
Aggiungi un parametro twofactor aggiuntivo alla funzione execute(), come mostrato nel seguente codice campione:
grecaptcha.enterprise.execute(KEY_ID, {
action: 'login',
twofactor: true
}).then(token => {
// Handle the generated token.
});
Sostituisci KEY_ID con la chiave basata sul punteggio che hai creato per il sito web.
Crea una valutazione
Con il token generato dalla funzione execute(), crea una valutazione utilizzando le librerie client di reCAPTCHA Enterprise o l'API REST del tuo backend.
Questo documento mostra come creare una valutazione per MFA utilizzando l'API REST. Per informazioni su come creare un test utilizzando le librerie client, vedi Creare valutazioni per i siti web.
Prima di creare una valutazione:
Configura l'autenticazione a reCAPTCHA Enterprise.
Il metodo di autenticazione scelto dipende dall'ambiente in cui è configurato reCAPTCHA Enterprise. La tabella seguente ti aiuta a scegliere il metodo di autenticazione appropriato e l'interfaccia supportata per configurare l'autenticazione:
Ambiente Interfaccia Metodo di autenticazione Google Cloud - REST
- Librerie client
Utilizza gli account di servizio collegati. On-premise o un cloud provider diverso REST Utilizza le chiavi API o la Federazione delle identità per i carichi di lavoro. Se vuoi utilizzare chiavi API, ti consigliamo di proteggere le chiavi API applicando restrizioni alle chiavi API.
Librerie client Utilizza quanto segue:
- Per Python o Java, utilizza le chiavi API o la Federazione delle identità per i carichi di lavoro.
Se vuoi utilizzare chiavi API, ti consigliamo di proteggere le chiavi API applicando restrizioni alle chiavi API.
- Per gli altri linguaggi, utilizza la federazione delle identità per i carichi di lavoro.
Scegli un identificatore dell'account stabile
accountIdche non venga modificato spesso dall'utente e forniscilo alla valutazione nel metodoprojects.assessments.create. Questo identificatore dell'account stabile deve avere lo stesso valore per tutti gli eventi relativi allo stesso utente. Puoi fornire quanto segue come identificatore dell'account:Identificatori degli utenti
Se ogni account può essere associato in modo univoco a un nome utente, un indirizzo email o un numero di telefono stabile, puoi utilizzarlo come
accountId. Quando fornisci questi identificatori tra siti (identificatori che possono essere riutilizzati su più siti), reCAPTCHA Enterprise utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli tra siti, segnalando identificatori di account illeciti e sfruttando la conoscenza dei pattern di comportamento illecito tra siti relativi a questi identificatori.In alternativa, se hai un ID utente interno associato in modo univoco a ciascun account, puoi fornirlo come
accountId.Con hash o criptato
Se non disponi di un ID utente interno associato in modo univoco a ogni account, puoi trasformare qualsiasi identificatore stabile in un identificatore dell'account opaco specifico per il sito. Questo identificatore è ancora necessario per consentire al defender dell'account reCAPTCHA Enterprise di comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso tra altri siti.
Scegli un identificatore dell'account stabile e rendilo opaco prima di inviarlo a reCAPTCHA Enterprise utilizzando la crittografia o l'hashing:
crittografia (consigliata): cripta l'identificatore dell'account utilizzando un metodo di crittografia deterministico che produca un testo crittografato stabile. Per istruzioni dettagliate, consulta Criptare i dati in modo deterministico. Quando scegli la crittografia simmetrica anziché l'hashing, non è necessario mantenere una mappatura tra gli identificatori utente e gli identificatori utente opachi corrispondenti. Decripta gli identificatori opachi restituiti da reCAPTCHA Enterprise per trasformarli in identificatori utente.
hashing: ti consigliamo di eseguire l'hashing dell'identificatore dell'account utilizzando il metodo SHA256-HMAC con un sale personalizzato a tua scelta. Poiché gli hash sono solo unidirezionale, devi mantenere una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare gli identificatori dell'account sottoposti ad hashing che vengono restituiti agli account originali.
Aggiungi il parametro accountId e un endpoint, ad esempio un indirizzo email da verificare nella valutazione nel metodo projects.assessments.create.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto Google Cloud.
- TOKEN: token restituito dalla chiamata
grecaptcha.enterprise.execute(). - KEY_ID: la chiave basata sul punteggio che hai installato sul tuo sito web.
- ACCOUNT_ID: un identificatore di un account utente univoco per il tuo sito web.
- EMAIL_ID: l'indirizzo email per il quale deve essere attivata la richiesta di verifica.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corpo JSON della richiesta:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userInfo": {
"accountId": "ACCOUNT_ID"
}
}
"accountVerification": {
"endpoints": [{
"emailAddress": "EMAIL_ID",
}]
}
}
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando:
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
Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando:
$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
Dovresti ricevere una risposta JSON simile alla seguente:
{
[...],
"accountVerification": {
"endpoints": [{
"emailAddress": "foo@bar.com",
"requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
"lastVerificationTime": "",
}],
"latestVerificationResult": "RESULT_UNSPECIFIED"
}
}
La valutazione contiene la data e l'ora dell'ultima verifica riuscita per gli endpoint specificati sul dispositivo che ha emesso il token, se presente. Contiene inoltre un campo requestToken per endpoint, che contiene una stringa criptata. Se decidi di attivare una verifica MFA per quell'endpoint, devi inviare nuovamente questa stringa criptata alla pagina web. I token di richiesta sono validi
per 15 minuti.
Azioni consigliate
Se hai abilitato reCAPTCHA Enterprise account defender per il tuo progetto, la risposta della valutazione contiene informazioni relative all'account defender, oltre a quelle relative all'MFA. Il campo recommended_action mostra la possibile azione che puoi intraprendere prima di attivare la verifica MFA.
L'esempio seguente mostra una valutazione di esempio che mostra l'opzione Ignora MFA come azione consigliata:
{
[...],
"accountDefenderAssessment": {
labels: ["PROFILE_MATCH"],
"recommended_action": "SKIP_2FA"
}
}
Il campo recommended_action può avere uno qualsiasi dei seguenti valori:
| Valore | Descrizione |
|---|---|
RECOMMENDED_ACTION_UNSPECIFIED |
Indica che l'account defender non è riuscito a emettere un giudizio in merito a questa richiesta. |
SKIP_2FA |
Indica che il responsabile dell'account ritiene che sia sicuro ignorare l'autenticazione MFA per questa valutazione. In genere, ciò significa che l'utente è stato verificato di recente per il tuo sito su questo dispositivo. |
REQUEST_2FA |
Indica che attivi una verifica MFA per l'utente. Per ulteriori informazioni, consulta la pagina relativa alla risposta alla valutazione di Account defender. |
Attiva una sfida MFA sul tuo sito web
Per eseguire il test dell'utente in base alle informazioni contenute nella valutazione, invia alla pagina web il codice MFA requestToken per l'endpoint che vuoi verificare dalla valutazione.
Attiva la sfida MFA con una chiamata al numero challengeAccount().
La funzione challengeAccount() restituisce una promessa che viene risolta dopo il completamento del test o rifiutata in caso di errore o timeout.
Al termine, viene generato un nuovo token contenente informazioni aggiornate, che viene quindi inviato per la valutazione.
Per attivare una sfida MFA:
Testare l'integrazione MFA.
Attiva una verifica MFA con una chiamata al
challengeAccount()fornendo i seguenti valori:- KEY_ID: la chiave basata sul punteggio che hai installato sul tuo sito web.
- REQUEST_TOKEN_FROM_ASSESSMENT: valore del campo
requestTokendella risposta della valutazione. - CONTAINER_HTML_COMPONENT_ID: ID del componente HTML in cui deve essere visualizzata la verifica di verifica. Se non specifichi questo parametro, la verifica viene visualizzata in un overlay nella parte superiore della pagina.
L'esempio seguente mostra come attivare la verifica MFA con una chiamata a
challengeAccount():grecaptcha.enterprise.challengeAccount(KEY_ID, { 'account-token': REQUEST_TOKEN_FROM_ASSESSMENT, 'container': CONTAINER_HTML_COMPONENT_ID }).then(newToken => { // Handle the new token. });Se la richiesta
challengeAccount()ha esito positivo, viene visualizzato il componente HTML per inserire il PIN ricevuto. Dopo aver inserito il PIN corretto, la variabilenewTokenviene passata alla funzione concatenata contenente il token del verdetto da verificare tramite una valutazione creata nel backend.Crea un handle di verifica e avvia una verifica con i seguenti parametri:
// 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 } });
Verifica un codice MFA dalla pagina web
Dopo aver ricevuto il PIN dall'utente finale, devi verificare se è corretto o meno.
Per convalidare il PIN, chiama il numero verificationHandle.verifyAccount() con il PIN
inserito dall'utente finale.
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
}
);
Crea una nuova valutazione
Crea una nuova valutazione con accountId e endpoints. Per istruzioni, consulta Creare una valutazione per MFA.
Una volta completato il flusso di lavoro sul client, riceverai un nuovo token che potrai utilizzare per ottenere l'esito della verifica che hai attivato. La valutazione contiene un timestamp recente relativo all'ultima verifica riuscita, insieme allo stato del risultato di esito positivo.
L'esempio seguente mostra una valutazione di esempio che ricevi al momento della creazione di una nuova valutazione utilizzando il nuovo token ottenuto dal sito web:
{
[...],
"accountVerification": {
"endpoints": [{
"emailAddress": "foo@bar.com",
"requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
"lastVerificationTime": "2020-03-23 08:27:12 PST",
}],
"latestVerificationResult": "SUCCESS_USER_VERIFIED"
}
}
Il campo latestVerificationResult può mostrare uno stato diverso, come indicato nella seguente tabella:
| Stato del risultato della verifica | Descrizione |
|---|---|
| SUCCESS_USER_VERIFIED | L'utente è stato verificato. |
| ERROR_USER_NOT_VERIFIED | L'utente non ha superato la verifica di verifica. |
| ERROR_SITE_ONBOARDING_INCOMPLETE | Il tuo sito non è stato inserito correttamente per l'utilizzo della funzionalità. |
| ERROR_RECIPIENT_NOT_ALLOWED | Questo destinatario non è approvato per l'invio di email a (solo durante i test). |
| ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED | Questo destinatario ha già ricevuto troppi codici di verifica in un breve periodo di tempo. |
| ERROR_CUSTOMER_QUOTA_EXHAUSTED | Hai superato la quota MFA disponibile. |
| ERROR_CRITICAL_INTERNAL | La verifica non è stata completata a causa di un errore interno nei nostri sistemi. |
| RESULT_UNSPECIFIED | Nessuna informazione sull'ultima verifica (mai verificata). |