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 gli 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 da violazioni di account (ATO).

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

Informazioni sulla procedura di configurazione della MFA

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

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

  1. Esegui l'analisi del 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 a due fattori con il 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 una nuova valutazione utilizzando il token fornito nella richiesta di verifica.

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA.

  2. 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à.

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

    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, 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 l'MFA, procedi nel seguente modo:

      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 Indirizzo email del mittente, inserisci il tuo indirizzo email.

    6. Fai clic su Salva.

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

Misura il flusso di lavoro critico sul tuo sito web

Passa 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 su 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 tuo backend.

Questo documento mostra come creare una valutazione per MFA;autenticazione a due 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 una valutazione, segui questi passaggi:

  • Configura l'autenticazione a 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 gli account di servizio 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 le restrizioni delle chiavi API.
    Librerie client

    Utilizza quanto segue:

  • Scegli un identificatore account stabile accountId che non viene modificato di frequente dall'utente e forniscilo alla valutazione nel metodo projects.assessments.create. Questo identificatore account stabile deve avere lo stesso valore per tutti gli eventi relativi allo stesso utente. Puoi fornire quanto segue come identificatore 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, segnalando gli identificatori di account illeciti e utilizzando la conoscenza dei pattern di abusi cross-site correlati a questi identificatori.

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

    Sottoposte ad hashing o criptate

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

    Scegli un identificatore 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 Eseguire la crittografia dei dati in modo deterministico. Se 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 valore salt personalizzato di 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 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 su punteggi 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 delle seguenti opzioni:

curl

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

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

Se hai attivato Account Defender di reCAPTCHA per il tuo progetto, la risposta al test 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 in due passaggi.

L'esempio seguente mostra una valutazione di esempio che mostra l'opzione Salta l'autenticazione a due MFA come azione consigliata:

{
  [...],
  "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 il difensore dell'account non è stato in grado di esprimere un giudizio in merito a questa richiesta.
SKIP_2FA Indica che Account Defender ritiene che sia sicuro saltare l'MFA per questa valutazione. In genere, significa che l'utente è stato verificato di recente per il tuo sito su questo dispositivo.
REQUEST_2FA Indica che hai attivato una verifica dell'autenticazione a due MFA per l'utente. Per ulteriori informazioni, consulta la risposta alla valutazione dell'account defender.

Attivare una verifica MFA sul tuo sito web

Per sfidare l'utente in base alle informazioni contenute nella valutazione, invia la verifica dell'autenticazione a due MFA requestToken per l'endpoint che vuoi verificare dalla valutazione alla pagina web.

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

Per attivare una verifica MFA;autenticazione a due fattori:

  1. Testa l'integrazione dell'MFA.

    Attiva una verifica tramite autenticazione a due MFA con una chiamata al challengeAccount() fornendo i seguenti valori:

    • KEY_ID: la chiave basata su punteggi che hai installato sul tuo sito web.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valore del campo requestToken della risposta alla valutazione.
    • CONTAINER_HTML_COMPONENT_ID: ID del componente HTML in cui deve essere visualizzata la 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 tramite l'autenticazione a due 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 variabilenewToken viene passata alla funzione a catena 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 è 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
  }
);

Creare una nuova valutazione

Crea una nuova valutazione con accountId e endpoints. Per le istruzioni, consulta la sezione Creare una valutazione per l'autenticazione a due fattori.

Una volta completato il flusso di lavoro sul client, riceverai un nuovo token che puoi utilizzare per ottenere il verdetto della verifica che hai attivato. La valutazione contiene un timestamp recente relativo all'ultima verifica andata a buon fine, nonché uno stato del risultato di successo.

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 L'utente è stato verificato correttamente.
ERROR_USER_NOT_VERIFIED L'utente non ha superato la 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 (solo durante il 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 di autenticazione a 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