Configurare l'autenticazione a più fattori

Questa pagina descrive 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ò aiutarti a proteggere i tuoi utenti da attacchi di credential stuffing e violazioni degli account (ATO).

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

Comprendere il processo di configurazione dellMFA fattori

La funzionalità MFA di reCAPTCHA viene implementata in aggiunta al flusso di lavoro reCAPTCHA regolare.

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

  1. Integra il flusso di lavoro critico 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 MFA fattori con requestToken in base al canale che vuoi utilizzare (è supportata solo l'email).
  4. Verifica il PIN inserito dall'utente finale sul tuo sito web.
  5. Crea un nuovo test utilizzando il token restituito nella richiesta di verifica.

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA.

  2. MFA è accessibile dopo un controllo di sicurezza, che viene avviato quando aggiungi un account di fatturazione al progetto. Aggiungi un account di fatturazione per integrare il tuo sito in questa funzionalità.

  3. Se vuoi abilitare la funzionalità di verifica dell'email della MFA, procedi nel seguente modo:

    1. Nella console Google Cloud , 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, poi 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, 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.

Strumentare il flusso di lavoro critico sul tuo sito web

Trasferisci 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 un test

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 MFA;autenticazione a più fattori utilizzando l'API REST. Per scoprire come creare una valutazione utilizzando le librerie client, consulta Creare valutazioni per i siti web.

Prima di creare un test, segui questi passaggi:

  • Configura l'autenticazione in reCAPTCHA.

    Il metodo di autenticazione che scegli dipende dall'ambiente in cui è configurato reCAPTCHA. La seguente tabella 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 provider cloud 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 alle chiavi API.
    Librerie client

    Utilizza quanto segue:

  • Scegli un identificatore di account stabile accountId che non venga 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 correlati allo stesso utente. Puoi fornire i seguenti elementi 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 cross-site (identificatori che possono essere riutilizzati su più siti), reCAPTCHA utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli cross-site contrassegnando gli identificatori di account illeciti e utilizzando la conoscenza dei pattern di abuso cross-site correlati a questi identificatori.

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

    Sottoposto ad hashing 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 di account opaco specifico per il sito. Questo identificatore è ancora necessario a reCAPTCHA Account Defender per comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso con altri siti.

    Scegli un identificatore di 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, vedi Criptare i dati in modo deterministico. Quando scegli la crittografia simmetrica anziché l'hashing, non devi mantenere una mappatura tra i tuoi 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 sale personalizzato a tua scelta. Poiché gli hash sono unidirezionali, devi mantenere una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare l'identificatore dell'account sottoposto ad hashing restituito 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 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 per un account utente univoco per il tuo sito web.
  • EMAIL_ID: l'indirizzo email per cui 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

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

Se hai attivato reCAPTCHA Account Defender per il tuo progetto, la risposta del test contiene informazioni relative ad Account Defender, oltre a quelle relative allMFA;autenticazione a più fattori. Il campo recommended_action mostra la possibile azione che puoi intraprendere prima di attivare la richiesta MFAri.

L'esempio seguente mostra una valutazione di esempio che indica Ignora MFA come azione consigliata:

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

Il campo recommended_action può contenere uno qualsiasi dei seguenti valori:

Valore Descrizione
RECOMMENDED_ACTION_UNSPECIFIED Indica che Account Defender non è stato in grado di esprimere un giudizio per questa richiesta.
SKIP_2FA Indica che Account Defender ritiene che sia sicuro ignorare MFA per questa valutazione. Di solito significa che l'utente è stato verificato di recente per il tuo sito su questo dispositivo.
REQUEST_2FA Indica che attivi una richiesta di MFA per l'utente. Per maggiori informazioni, consulta Risposta alla valutazione di Account Defender.

Attivare una richiesta di MFA sul tuo sito web

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

Attiva la richiesta di MFA con una chiamata al numero 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 richiesta di MFA:

  1. Testa l'integrazione MFA.

    Attiva una richiesta di 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: valore del campo requestToken dalla risposta del test.
    • CONTAINER_HTML_COMPONENT_ID: ID del componente HTML in cui deve essere visualizzata la sfida di verifica. Se non specifichi questo parametro, la sfida viene visualizzata in una sovrapposizione nella parte superiore della pagina.

    L'esempio seguente mostra come attivare la richiesta di 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 sfida 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 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
  }
);

Creare un nuovo test

Crea un nuovo test con accountId e endpoints. Per istruzioni, vedi Creare una valutazione per l'autenticazione a più fattori.

Una volta completato il flusso di lavoro sul client, riceverai un nuovo token che puoi utilizzare per ottenere il risultato della verifica che hai attivato. La valutazione contiene un timestamp recente relativo all'ultima verifica riuscita, insieme a uno stato di risultato riuscito.

L'esempio seguente mostra un test campione che ricevi dopo aver creato un nuovo test 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 elencato nella tabella seguente:

Stato del risultato della verifica Descrizione
SUCCESS_USER_VERIFIED L'utente è stato verificato.
ERROR_USER_NOT_VERIFIED L'utente non ha superato il test di verifica.
ERROR_SITE_ONBOARDING_INCOMPLETE Il tuo sito non è stato configurato correttamente per utilizzare la funzionalità.
ERROR_RECIPIENT_NOT_ALLOWED Questo destinatario non è approvato per l'invio di email a (solo durante il 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