Configura l'autenticazione a più fattori

In questa pagina viene descritto come configurare l'autenticazione a più fattori (MFA) che consente di verificare l'identità degli 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ò contribuire a proteggere gli utenti da attacchi di credential stuffing e violazione di account (ATO).

MFA è disponibile per le chiavi basate sul punteggio e non è disponibile per le chiavi delle caselle di controllo.

Comprendere il processo di configurazione della MFA

La funzionalità MFA di reCAPTCHA è implementata al di sopra del normale flusso di lavoro reCAPTCHA.

A livello generale, il flusso di lavoro MFA è il seguente:

  1. Strumento il flusso di lavoro più importante sul tuo sito web
  2. Crea una valutazione utilizzando il token restituito dalla chiamata execute() e i parametri MFA per ottenere un requestToken MFA.
  3. Attiva una verifica MFA con requestToken in base al canale che vuoi utilizzare (supportato solo email).
  4. Verifica il PIN inserito dall'utente finale sul tuo sito web.
  5. Crea una nuova valutazione utilizzando il token che viene restituito nella richiesta di verifica.

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA.

  2. L'MFA è accessibile dopo un controllo di sicurezza. Contatta il nostro team di vendita per integrare il tuo sito a questa funzionalità. Fornisci le seguenti informazioni di onboarding al team di vendita:

    • Numero di progetto Google Cloud
    • Chiavi reCAPTCHA da eseguire l'onboarding
    • Media QPS (messaggi email al secondo)
    • Picco QPS (messaggi email al secondo)
    • Per l'autenticazione MFA email, l'indirizzo del mittente e gli indirizzi email o i domini necessari durante il test

  3. Se vuoi attivare la funzionalità di verifica email della MFA:

    1. Nella console Google Cloud, vai alla pagina reCAPTCHA.

      Vai a reCAPTCHA

    2. 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 poi seleziona il progetto.

    3. Fai clic su Impostazioni.

    4. Nel riquadro Autenticazione a più fattori, fai clic su Configura.

    5. Nella finestra di dialogo Configura MFA, segui questi passaggi:

      1. Per attivare la verifica email, fai clic sul pulsante di attivazione/disattivazione Attiva email.
      2. Nella casella Nome mittente, inserisci il tuo nome.

      3. Nella casella Email mittente, inserisci il tuo indirizzo email.

    6. Fai clic su Salva.

  4. Configura reCAPTCHA sul tuo sito web utilizzando chiavi basate sul punteggio.

Strumenti per il flusso di lavoro più importante 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.

Crea una valutazione

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

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

Prima di creare una valutazione:

  • Configura l'autenticazione per reCAPTCHA.

    Il metodo di autenticazione scelto dipende dall'ambiente in cui è configurato reCAPTCHA. La tabella seguente consente di 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 account di servizio collegati.
    On-premise o da un cloud provider diverso REST Utilizza le chiavi API o la federazione delle identità per i carichi di lavoro.

    Se vuoi utilizzare le chiavi API, ti consigliamo di proteggerle applicando limitazioni relative alle chiavi API.
    Librerie client

    Utilizza quanto segue:

  • Scegli un identificatore dell'account stabile accountId che non viene modificato spesso dall'utente e forniscilo alla valutazione nel metodo projects.assessments.create. Questo identificatore di account stabile deve avere lo stesso valore per tutti gli eventi relativi allo stesso utente. Puoi fornire il seguente 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 in più siti), reCAPTCHA utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli cross-site segnalando gli identificatori di account illeciti e utilizzando la conoscenza dei pattern di abuso tra siti correlati a questi identificatori.

    In alternativa, se hai un ID utente interno associato in modo univoco a ogni account, puoi fornirlo come accountId.

    Con hash o criptato

    Se non disponi di un ID utente interno associato in modo univoco a ciascun account, puoi trasformare qualsiasi identificatore stabile in un identificatore di account opaco specifico per il sito. Questo identificatore è ancora necessario affinché l'account defender di reCAPTCHA possa comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso tra altri siti.

    Scegli qualsiasi 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 crittografato stabile. Per istruzioni dettagliate, consulta la sezione sulla crittografia dei dati in modo deterministico. Quando scegli la crittografia simmetrica rispetto all'hashing, non è necessario mantenere una mappatura tra gli identificatori utente e i corrispondenti identificatori utente opaci. Decripta gli identificatori opachi restituiti da reCAPTCHA per convertirli in identificatori utente.

    • Hashing: 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 unidirezionali, devi mantenere una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare gli identificatori dell'account con hash 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: l'ID del tuo progetto Google Cloud.
  • TOKEN: token restituito dalla chiamata grecaptcha.enterprise.execute().
  • KEY_ID: la chiave basata sul punteggio installata sul tuo sito web.
  • ACCOUNT_ID: un identificatore univoco per il tuo sito web per un account utente.
  • 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:

curl

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

Se hai abilitato reCAPTCHA 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 "Salta 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 il difensore dell'account non è riuscito a emettere un giudizio in merito a questa richiesta.
SKIP_2FA Indica che l'account defender ritiene che sia sicuro ignorare l'MFA per questa valutazione. Questo di solito 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 maggiori 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 alla pagina web l'oggetto MFA requestToken per l'endpoint che vuoi verificare dalla valutazione.

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 quindi inviato per la valutazione.

Per attivare una verifica MFA:

  1. Testare l'integrazione MFA.

    Attiva una verifica MFA con una chiamata al challengeAccount() fornendo i seguenti valori:

    • KEY_ID: la chiave basata sul punteggio installata sul tuo sito web.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valore del campo requestToken della 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 sfida 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 variabile newToken viene passata alla funzione concatenata contenente il token del verdetto da verificare tramite una valutazione creata nel backend.

  2. 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 il PIN è corretto o meno.

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

Crea una nuova valutazione

Crea un nuovo test con accountId e endpoints. Per le istruzioni, vedi Creare una valutazione per MFA.

Dopo aver completato il flusso di lavoro sul client, ricevi un nuovo token che puoi 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 riuscito.

L'esempio seguente mostra una valutazione di esempio che ricevi durante la 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 configurato 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).

Passaggi successivi