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 funzione puoi verificare che i tuoi utenti siano proprietari dell'indirizzo email associati al proprio account. L'autenticazione a più fattori può aiutarti a proteggere i tuoi utenti da attacchi di credential stuffing e da violazioni di account (ATO).

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

Informazioni sulla procedura di configurazione della verifica in due passaggi

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

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA.

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

  3. Se vuoi attivare la funzionalità di verifica email dell'MFA, segui questi passaggi:

    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. 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, 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 il Funzione execute() per la valutazione del rischio. La funzione execute() restituisce una promessa che viene risolta al momento della generazione dei token.

Aggiungi un parametro twofactor aggiuntivo alla funzione execute() come mostrato nel seguente codice di esempio:

  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 creato per il sito web.

Crea 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 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, segui questi passaggi:

  • Configura l'autenticazione per reCAPTCHA.

    Il metodo di autenticazione che scegli dipende dall'ambiente in cui è configurato reCAPTCHA. La tabella seguente ti consente di scegliere il metodo di autenticazione appropriato e l'interfaccia supportata 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 limitazioni relative alle 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 di account stabile deve avere lo stesso valore per tutti gli eventi correlati 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 fornirlo 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 una crittografia deterministica di crittografia che produce un testo crittografato stabile. Per istruzioni dettagliate, consulta Criptare i 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 nel identificatore 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 per consentirti di mappare gli hash generati identificatore di account 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 seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo 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 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, 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 indicati 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 tale endpoint, devi inviare la stringa criptata alla pagina web. I token della 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'autenticazione a due fattori. 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'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. In genere, 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 risposta alla valutazione dell'account defender.

Attivare una verifica tramite l'autenticazione a più fattori sul tuo sito web

Per richiedere una verifica all'utente in base alle informazioni contenute in la valutazione, invia l'requestToken MFA per l'endpoint a cui eseguire la verifica dalla valutazione alla pagina web.

Attiva la verifica in due passaggi 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:

  1. Testa l'integrazione dell'MFA.

    Attiva una verifica tramite autenticazione a due fattori 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 sottoposta 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 un chiamata al numero 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, il componente HTML viene visualizzato per inserire il PIN ricevuto. Dopo aver inserito il PIN corretto, La variabile newToken viene passata alla funzione concatenata contenente la variabile di esito positivo 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 cliente, riceverai un nuovo che puoi utilizzare per ottenere l'esito della verifica che hai attivato. La valutazione contiene un timestamp recente relativo all'ultima verifica riuscita e lo stato di un risultato riuscito.

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 dall'elenco la 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 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 è stato approvato per l'invio di email a (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