Configurare l'autenticazione a più fattori

Questa pagina descrive come configurare l'autenticazione a più fattori (MFA) che ti consente di verificare l'identità dei tuoi utenti inviando un codice di verifica via email. Con questa funzionalità, puoi verificare che i tuoi utenti siano proprietari dell'indirizzo email associato al loro account. L'MFA può aiutarti a proteggere i tuoi utenti dagli attacchi di credential stuffing e dai takeover dell'account (ATO).

L'MFA è disponibile per le chiavi basate sul punteggio e non è disponibile per le chiavi con casella di controllo.

Informazioni sulla procedura di configurazione dell'MFA

La funzionalità MFA di reCAPTCHA viene implementata in aggiunta al normale reCAPTCHA workflow.

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 ottenere un requestToken MFA.
Attiva una verifica MFA con il requestToken in base al canale che vuoi utilizzare (è supportata solo l'email).
Verifica il PIN inserito dall'utente finale sul tuo sito web.
Crea una nuova valutazione utilizzando il token che viene restituito nella richiesta di verifica.

Prima di iniziare

Prepara l'ambiente per reCAPTCHA.
L'MFA è accessibile dopo una revisione della sicurezza, che viene avviata quando aggiungi un account di fatturazione al progetto. Aggiungi un account di fatturazione per eseguire l'onboarding del tuo sito a questa funzionalità.
Se vuoi attivare la funzionalità di verifica email dell'MFA:

Nota: ti consigliamo vivamente di fornire agli utenti finali più metodi di verifica, ad esempio contattare l'assistenza clienti per verificare il loro account, per evitare che non possano accedere ai loro account perché l'MFA non è disponibile.
1. Nella Google Cloud console, vai alla pagina reCAPTCHA.
  
  Vai a reCAPTCHA
2. Verifica che il nome del tuo progetto venga visualizzato nel selettore di risorse.
  
  Se non vedi il nome del tuo progetto, fai clic sul selettore di risorse, quindi seleziona il tuo progetto.
3. Fai clic su Impostazioni.
4. Nel riquadro Autenticazione a più fattori, fai clic su Configura.
5. Nella finestra di dialogo Configura MFA, procedi nel seguente modo:
  1. Per attivare la verifica email, fai clic sul pulsante Attiva email.
  2. Nella casella Nome del mittente, inserisci il tuo nome.
  3. Nella casella Email del mittente, inserisci il tuo indirizzo email.
6. Fai clic su Salva.
Nota: per impostazione predefinita, l'email inviata è generica e senza brand. Se devi aggiungere il brand o personalizzare questa email, contatta il tuo specialista tecnico assegnato.
Dopo aver configurato l'indirizzo email del mittente, configura i record DNS per evitare problemi di recapito. Nei passaggi seguenti, sostituisci example.com con il tuo dominio.
1. Aggiungi un record SPF per consentire a reCAPTCHA di inviare email per tuo conto:
```
Host: example.com
Value: v=spf1 include:_spf.recaptchamail.goog ~all
```
2. Includi le seguenti voci CNAME per consentire ai server di trovare la DKIM:
```
Host: recaptcha1._domainkey.example.com
Value: recaptcha1._domainkey.recaptchamail.goog.
```
```
Host: recaptcha2._domainkey.example.com
Value: recaptcha2._domainkey.recaptchamail.goog.
```
Configura reCAPTCHA sul tuo sito web utilizzando le chiavi basate sul punteggio.

Strumentare il flusso di lavoro critico sul tuo sito web

Trasmetti le informazioni necessarie a reCAPTCHA 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 tuo sito web.

Creare una valutazione

Con il token generato dalla funzione execute(), crea una valutazione utilizzando le librerie client reCAPTCHA o l'API REST dal backend.

Questo documento mostra come creare una valutazione per l'MFA utilizzando l'API REST. Per scoprire come creare una valutazione utilizzando le librerie client, consulta Creare valutazioni per i siti web.

Prima di creare una valutazione:

Configura l'autenticazione a reCAPTCHA.

Il metodo di autenticazione che scegli dipende dall'ambiente in cui è configurato reCAPTCHA. 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 i service account collegati.
On-premise o un altro cloud provider	REST	Utilizza le chiavi API o la federazione delle identità per i workload. Se vuoi utilizzare le chiavi API, ti consigliamo di proteggerle applicando le limitazioni delle chiavi API.
Librerie client	Utilizza quanto segue: Per Python o Java, utilizza le chiavi API o la federazione delle identità per i workload. Se vuoi utilizzare le chiavi API, ti consigliamo di proteggerle applicando le limitazioni delle chiavi API. Per altre lingue, utilizza la federazione delle identità per i workload.

Ambiente

Interfaccia

Metodo di autenticazione

Google Cloud

REST
Librerie client

Utilizza i service account collegati.

On-premise o un altro cloud provider

REST

Utilizza le chiavi API o la federazione delle identità per i workload.

Se vuoi utilizzare le chiavi API, ti consigliamo di proteggerle applicando le limitazioni delle chiavi API.

Librerie client

Utilizza quanto segue:

Per Python o Java, utilizza le chiavi API o la federazione delle identità per i workload.
Se vuoi utilizzare le chiavi API, ti consigliamo di proteggerle applicando le limitazioni delle chiavi API.
Per altre lingue, utilizza la federazione delle identità per i workload.

Scegli un identificatore dell'account stabile accountId che non venga modificato spesso dall'utente e fornisci alla valutazione nel projects.assessments.create metodo. Questo identificatore dell'account stabile deve avere lo stesso valore per tutti gli eventi correlati allo stesso utente. Puoi fornire quanto segue come identificatore dell'account:
Identificatori utente

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 il accountId. Quando fornisci questi identificatori cross-site (identificatori che possono essere riutilizzati su più siti), reCAPTCHA utilizza queste informazioni per migliorare la protezione degli account utente in base ai modelli cross-site contrassegnando gli identificatori degli account illeciti e utilizzando la conoscenza dei pattern di attività illecite cross-site correlati a questi identificatori.

In alternativa, se hai un ID utente interno associato in modo univoco a ogni account, puoi fornirelo come il accountId.
Con hash o criptati

Se non hai un ID utente interno associato in modo univoco a ogni account, puoi trasformare qualsiasi identificatore stabile in un identificatore dell'account opaco e specifico del sito. Questo identificatore è comunque necessario per l'account defender di reCAPTCHA per comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso con altri siti.

Scegli un identificatore dell'account stabile e rendilo opaco prima di inviarlo a reCAPTCHA utilizzando la crittografia o l'hashing:
- Crittografia (consigliata): cripta l'identificatore dell'account utilizzando un metodo di crittografia deterministico che produce un testo cifrato stabile. Per istruzioni dettagliate, consulta criptare i dati in modo deterministico. Quando scegli la crittografia simmetrica rispetto all'hashing, non devi conservare una mappatura tra gli identificatori utente e gli identificatori utente opachi corrispondenti. Decripta gli identificatori opachi restituiti da reCAPTCHA per trasformarli nell' identificatore utente.
- Hashing: ti consigliamo di eseguire l'hashing dell'identificatore dell'account utilizzando il metodo SHA256-HMAC con un salt personalizzato a tua scelta. Poiché gli hash sono unidirezionali, devi conservare una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare gli identificatori dell'account con hash 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, apporta le sostituzioni seguenti:

PROJECT_ID: l'ID del tuo Google Cloud progetto.
TOKEN: il 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 per 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 di queste opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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 anche un campo requestToken per endpoint, che contiene una stringa criptata. Se decidi di attivare una verifica MFA per quell'endpoint, devi inviare questa stringa criptata alla pagina web. I token di richiesta sono validi per 15 minuti.

Azioni consigliate

Se hai attivato l'account defender di reCAPTCHA per il tuo progetto, la risposta alla 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 di ignorare l'MFA come comportamento consigliato:

{
  [...],
  "accountDefenderAssessment": {
    labels: ["PROFILE_MATCH"],
    "recommended_action": "SKIP_2FA"
  }
}

Il campo recommended_action può avere uno dei seguenti valori:

Valore	Descrizione
`RECOMMENDED_ACTION_UNSPECIFIED`	Indica che l'account defender non è stato in grado di esprimere un giudizio per questa richiesta.
`SKIP_2FA`	Indica che l'account defender ritiene che sia sicuro ignorare l'MFA per questa valutazione. In genere, questo significa che l'utente è stato verificato di recente per il tuo sito su questo dispositivo.
`REQUEST_2FA`	Indica che devi attivare una verifica MFA per l'utente. Per ulteriori informazioni, consulta la risposta alla valutazione dell'account defender.

Attivare una verifica MFA sul tuo sito web

Per verificare l'utente in base alle informazioni contenute nella valutazione, invia il requestToken MFA per l'endpoint che vuoi verificare dalla valutazione alla pagina web.

Attiva la verifica MFA con una chiamata a challengeAccount(). La funzione challengeAccount() restituisce una promessa che viene risolta al termine della verifica o rifiutata in caso di errore o timeout. Al termine, viene generato un nuovo token contenente informazioni aggiornate, che viene poi inviato per la valutazione.

Per attivare una verifica MFA:

Verifica l'integrazione dell'MFA.

Attiva una verifica MFA con una chiamata a challengeAccount() fornendo i seguenti valori:
- KEY_ID: la chiave basata sul punteggio che hai installato sul tuo sito web.
- REQUEST_TOKEN_FROM_ASSESSMENT: il valore del requestToken campo della risposta alla valutazione.
- CONTAINER_HTML_COMPONENT_ID: l'ID del componente HTML in cui deve essere eseguito il rendering della verifica. Se non specifichi questo parametro, la verifica viene eseguita in una sovrapposizione sopra la 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() va a buon fine, viene visualizzato il componente HTML per inserire il PIN ricevuto. Dopo aver inserito il PIN corretto, la variabile newToken viene passata alla funzione concatenata contenente il token di verdetto da verificare tramite una valutazione creata nel backend.

Nota: questa UI di verifica predefinita non dispone di funzionalità di gestione degli errori o di altre personalizzazioni adatte a un ambiente di produzione. Pertanto, ti consigliamo di non utilizzare questo prototipo oltre la fase di integrazione.

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
    }
  });

Verificare un codice MFA dalla pagina web

Dopo aver ricevuto il PIN dall'utente finale, devi verificare se è corretto.

Per convalidare il PIN, chiama 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
  }
);

Creare una nuova valutazione

Crea una nuova valutazione con accountId ed endpoints. Per istruzioni, consulta Creare una valutazione per l'MFA.

Al termine del workflow sul client, riceverai un nuovo token che potrai utilizzare per ottenere il verdetto della verifica che hai attivato. La valutazione contiene un timestamp recente relativo all'ultima verifica riuscita, insieme a uno stato di risultato positivo.

L'esempio seguente mostra una valutazione di esempio che ricevi quando crei 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 tabella seguente:

Stato del risultato della verifica	Descrizione
SUCCESS_USER_VERIFIED	La verifica dell'utente è stata effettuata correttamente.
ERROR_USER_NOT_VERIFIED	L'utente non ha superato la verifica.
ERROR_SITE_ONBOARDING_INCOMPLETE	L'onboarding del tuo sito non è stato completato correttamente per utilizzare la funzionalità.
ERROR_RECIPIENT_NOT_ALLOWED	Questo destinatario non è approvato per l'invio di email (solo durante i test ).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED	Questo destinatario ha già ricevuto troppi codici di verifica in un breve periodo.
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).

Passaggi successivi

Rilevare e prevenire attività fraudolente correlate all'account utilizzando l'account defender di reCAPTCHA