Testare il protocollo di verifica email con una prova dell'origine

Rowan Merewood

Pubblicato l'8 luglio 2026

Quando raccogli un indirizzo email nell'ambito di una registrazione, di un accesso, di un abbonamento, di un pagamento, del recupero dell'account o di un'altra procedura, è prassi comune confermare che l'indirizzo email appartenga alla persona che lo inserisce. I metodi di verifica esistenti, come le password monouso (OTP) o i link di verifica email (link magici), richiedono all'utente di uscire dal tuo sito. Questa procedura di interruzione può aumentare il rischio che l'utente, sia una persona che un agente, abbandoni completamente la sessione e non completi mai la procedura di autenticazione.

L'API Email Verification è una proposta che consente al browser di comunicare direttamente con il provider di email per verificare che l'utente sia il proprietario dell'indirizzo email. Gli utenti selezionano un'email dal suggerimento di compilazione automatica o completamento automatico del browser, inviano il modulo e il sito verifica l'indirizzo email con il provider senza inviare un'email o interrompere il flusso dell'utente.

Demo del prompt utente dell'API Email Verification
Demo del prompt utente dell'API Email Verification

La raccolta di email è un punto di conversione fondamentale nel percorso di un utente e Chrome vorrebbe ricevere feedback sulla proposta da parte di siti che vogliono verificare le email, provider di email che possono eseguire la verifica, e utenti che utilizzano la procedura. Puoi registrarti alla prova dell'origine oggi stesso e seguire le istruzioni di implementazione qui. Per la configurazione generale della prova dell'origine, consulta la pagina Introduzione alle prove dell'origine.

Puoi provare il flusso con un account demo:

Flusso di verifica email

Le sezioni seguenti spiegano cosa devi fare tu e i tuoi utenti per avviare il flusso di verifica email e l'intero flusso di lavoro quando utilizzi il protocollo di verifica email.

Termini chiave

I termini chiave per l'API Email Verification sono i seguenti:

  • Strumento di verifica: il sito che raccoglie l'indirizzo email e vuole verificare l'indirizzo. Lo strumento di verifica è chiamato anche Relying Party.
  • Provider di email: il servizio che fornisce l'indirizzo email dell'utente, per esempio gmail.com.
  • Emittente: il servizio che gestisce l'account per l'email dell'utente, ad esempio accounts.google.com. L'emittente è chiamato anche Identity Provider.

In alcuni casi, il provider di email e l'emittente potrebbero operare dallo stesso dominio. Tuttavia, è importante distinguere tra avere un indirizzo email e avere una sessione attiva per l'account associato.

Architettura del flusso di verifica email
Architettura del flusso di verifica email

Prerequisiti

  • L'utente deve aver eseguito l'accesso al proprio provider di email o emittente nello stesso profilo del browser. Ad esempio, se utilizza Gmail, deve aver eseguito l'accesso al proprio Account Google.
  • In qualità di sito di verifica partecipante, devi registrarti alla prova dell'origine e fornire il token nella stessa pagina del modulo email.

  • L'utente deve selezionare il proprio indirizzo email dal menu a discesa di compilazione automatica o completamento automatico.

    • Se l'utente ha inserito in precedenza un indirizzo email nel campo, verrà offerto tramite il completamento automatico.

    • Se l'utente ha aggiunto il proprio indirizzo email utilizzando le impostazioni di Chrome "Compilazione automatica e password" (chrome://settings/autofill), verrà offerto tramite la compilazione automatica.

  • La prima volta che un utente fornisce un indirizzo email per la verifica, visualizzerà un prompt di autorizzazione. Questo avviene una sola volta per indirizzo email.

Una volta che l'utente ha una sessione attiva nel browser, può avviare la procedura:

  1. In un modulo con un campo email, l'utente seleziona il proprio indirizzo email dal menu a discesa di completamento automatico. Il sito di verifica fornisce un campo nascosto nel modulo con un nonce per istanza per convalidare questa richiesta.

  2. Il browser recupererà quindi il record DNS di verifica email per il dominio email. In questo modo il browser viene indirizzato all'emittente. L'emittente confermerà quindi di avere una sessione attiva per quell'indirizzo email.

  3. L'emittente fornirà quindi il token di verifica email (EVT) per l'indirizzo. Il browser lo combina in un JWT associato alla chiave con l'EVT, l'origine del sito e il nonce del modulo di input.

  4. Quando il modulo viene inviato, il pacchetto EVT viene aggiunto al campo nascosto e inviato al sito.

  5. Il sito di verifica verifica quindi ciascuno di questi dettagli: l'indirizzo email previsto, il nonce e le firme del browser e dell'emittente.

  6. L'utente vede una piccola notifica che lo informa che il suo provider di email ha verificato il suo indirizzo.

Questa procedura fornisce al sito di verifica la conferma che l'indirizzo email è valido e appartiene all'utente attuale, il che significa che il sito può saltare l'invio di un'email di verifica.

Gli utenti possono gestire le proprie email verificate in Impostazioni > Compilazione automatica e password > Informazioni di contatto > Email verificata (o aprire chrome://settings/contactInfo).

Considerazioni sui casi d'uso

La verifica email è un miglioramento progressivo del flusso esistente che elimina la necessità per un utente di uscire dal tuo sito per recuperare un OTP o fare clic su un link. I siti possono aggiungere i campi di verifica email a tutti i moduli pertinenti, come accessi, iscrizioni alla newsletter, creazione di account e recupero della password. L'EVP viene attivato solo se il browser lo supporta. Se non viene ricevuto alcun codice all'invio o se uno dei passaggi di convalida non va a buon fine, puoi tornare al flusso di conferma email predefinito. Ciò significa anche che non esiste il rilevamento delle funzionalità per l'API; il sito di verifica tratta l'EVT come facoltativo, elaborandolo se è presente nella richiesta.

La verifica email conferma che l'utente ha una sessione attiva con il provider del suo indirizzo email. Non verifica che l'email sia stata ricevuta dall'utente. Potresti comunque voler inviare le email di benvenuto o di onboarding esistenti e potresti voler o dover chiedere all'utente di controllare le impostazioni dello spam.

Implementare il sito di verifica

Per ulteriori dettagli, puoi esaminare il codice demo end-to-end e fare riferimento ai passaggi di convalida nelle proposte dell'API e del protocollo di verifica email.

Configurare i campi del modulo

Assicurati che i campi del modulo abbiano gli attributi corretti:

<input
  name="email-address"
  type="email"
  autocomplete="email">
<input
  type="hidden"
  name="token"
  nonce="rAnD0m-VaLuE"
  autocomplete="email-verification-token">

Imposta gli attributi type e autocomplete dell'input email su email per consentire al browser di offrire il completamento automatico per l'indirizzo email.

Il nuovo campo hidden verrà compilato con il token di verifica email all'invio del modulo. Gli attributi necessari sono:

  • Imposta type="hidden" perché questo campo non richiede l'input dell'utente.
  • Imposta nonce="rAnD0m-VaLuE". Il sito deve fornire un nonce univoco associato alla sessione per verificare l'invio del modulo.
  • Imposta autocomplete="email-verification-token". Il browser utilizza questo attributo per identificare il campo da compilare.

Convalida gli elementi del modulo controllando il riquadro Rete in DevTools. Quando selezioni un indirizzo email, vedrai il browser attivare le query DNS e di ricerca dell'account successive per il provider di email e l'emittente. Si tratta di richieste interne del browser; il tuo sito non riceve nulla fino all'invio del modulo.

Convalidare l'EVT

Esistono cinque passaggi per convalidare ogni componente del pacchetto EVT.

  1. Analizza il token.
  2. Convalida i valori previsti.
  3. Convalida l'associazione della chiave.
  4. Convalida il record DNS.
  5. Scopri l'emittente e verifica la firma EVT.

1. Analizzare il token

I dati non elaborati dell'invio del modulo contengono l'EVT e le attestazioni firmate in un token JWT (JSON Web Token) di divulgazione selettiva (SD-JWT+KB) separati da una tilde (~ character). Dovrai separarli e decodificare le intestazioni e i payload JOSE (Javascript Object Signing and Encryption), ad esempio utilizzando jose per Node.js.

Se example.com verifica demo@gmail.com, il payload decodificato avrà un aspetto simile all'esempio seguente:

{
  "evtJwtDecodedPayload": {
    "cnf": {
      "jwk": {
        "crv": "Ed25519",
        "kty": "OKP",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@gmail.com",
    "email_verified": true,
    "iat": 1782911685,
    "iss": "https://accounts.google.com"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://example.com",
    "iat": 1782911685,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  }
}

2. Convalidare i valori previsti

Verifica che i valori di base nel payload corrispondano ai valori forniti:

  • Verifica che email_verified sia impostato su true.
  • Verifica che email corrisponda all'indirizzo email fornito nel modulo.
  • Verifica che nonce corrisponda al nonce fornito nel modulo.
  • Verifica che aud corrisponda all'origine del tuo sito.
  • Verifica che iat abbia un timestamp relativamente recente, ad esempio dopo il rendering del modulo.

3. Convalidare l'associazione della chiave

Il browser crea una chiave temporanea ed effimera per la transazione per confermare che ha firmato il token. Estrai questa chiave dall'attestazione cnf (conferma) nell'EVT e poi utilizzala per verificare il JWT associato alla chiave.

Quindi, calcola l'hash previsto e confrontalo con l'attestazione sd_hash. Il seguente esempio Node.js mostra come eseguire questo calcolo:

const calculatedHash = createHash("sha256")
        .update(evtJwt + "~")
        .digest("base64url");

4. Convalidare il record DNS

Verifica il record DNS _email-verification per il dominio dell'indirizzo email. Ad esempio, per demo@gmail.com, esegui una query sul record TXT _email-verification.gmail.com. Per questo provider, la query restituisce la posizione del provider dell'account, ovvero accounts.google.com.

$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"

5. Scoprire l'emittente e verificare la firma EVT

Assicurati che l'emittente pubblichi la risorsa /.well-known/email-verification, che fornisce gli endpoint per l'emissione del token, la chiave web JSON (JWK) per il sito e gli algoritmi di firma supportati.

$ curl https://accounts.google.com/.well-known/email-verification
{
  "issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
  "jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["EdDSA"]
}

Utilizza le JWK per verificare il JWT EVT estratto dal token. La maggior parte delle librerie JOSE fornisce funzioni per gestire questa verifica.

Se tutti e cinque i passaggi vanno a buon fine, hai verificato l'indirizzo email rispetto al provider. In caso contrario, torna all'invio di un'email di conferma all'utente come da flusso normale.

Implementare il servizio di provider di email ed emittente

Per ulteriori dettagli, puoi esaminare il codice demo del provider di email simulato e fare riferimento ai passaggi dell'emittente nelle proposte dell'API Email Verification e del protocollo di verifica email.

In qualità di emittente, non devi registrarti alla prova dell'origine o fornire un token, poiché il comportamento del browser viene attivato dal sito della Relying Party. Devi solo assicurarti che gli endpoint previsti siano attivi per rispondere a queste richieste.

Configurare il rilevamento dell'emittente

Per consentire ai browser di rilevare automaticamente gli endpoint di verifica quando viene selezionato un indirizzo email appartenente al tuo dominio, esponi la configurazione utilizzando DNS e un endpoint HTTP .well-known.

Configurare il record di delega DNS

Configura un record TXT DNS sul tuo dominio email che delega l'autorità di verifica all'identificatore dell'emittente. Questi identificatori possono utilizzare lo stesso dominio a seconda dell'infrastruttura.

Formato record: _email-verification.<email-domain>

File di zona di esempio:

_email-verification.example.com IN TXT "iss=accounts.issuer.example"

Ospitare un endpoint .well-known/email-verification

Ospita un file di metadati JSON sul tuo dominio emittente nel percorso /.well-known/. Questo file descrive le tue funzionalità di emissione e gli algoritmi di firma crittografica supportati dalla tua infrastruttura.

Endpoint: https://<issuer-domain>/.well-known/email-verification

Esempio di risposta:

{
  "issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
  "jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["EdDSA", "ES256"]
}

Ospitare un endpoint .well-known/web-identity

Una risorsa JSON .well-known aggiuntiva che potresti aver già implementato nell'ambito dell' API Federated Credentials (FedCM). Fornisce link all'endpoint degli account e all'URL di accesso.

Endpoint: https://<domain>/.well-known/web-identity

Esempio di risposta:

{
  "accounts_endpoint": "https://accounts.issuer.example/accounts",
  "login_url": "https://accounts.issuer.example/login"
}

Utilizzare un endpoint degli account

L'endpoint degli account dell'API FedCM fornisce al momento un elenco degli account con accesso. L'esempio seguente mostra una risposta minima. Per ulteriori dettagli, consulta la guida all'implementazione del provider di identità.

Endpoint: come specificato in .well-known/web-identity

Di seguito è riportato un esempio di risposta:

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

Integrare l'API Login Status

L'utente deve avere una sessione attiva con il provider e tu devi segnalare ciò al browser con l'API Login Status.

Quando un utente esegue l'accesso o la disconnessione, pubblica l'intestazione della risposta HTTP corrispondente:

Set-Login: logged-in
Set-Login: logged-out

In alternativa, aggiorna lo stato utilizzando JavaScript nel contesto dell'applicazione web:

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

Gestire le richieste di emissione

Il tuo issuance_endpoint riceve una richiesta POST application/x-www-form-urlencoded che contiene il request_token.

Le sezioni seguenti mostrano l'intera procedura di gestione delle richieste di emissione.

1. Convalidare la richiesta di emissione

Analizza e convalida i payload del browser in entrata:

  • Metodo: POST
  • Verifica della sessione: convalida i cookie session/authentication proprietari dell'utente trasmessi insieme alla richiesta per assicurarti che esista un contesto di identità attivo e autorizzato.
  • Verifica dei parametri: estrai il parametro request_token (un JWT firmato generato dal browser). Verifica che contenga la chiave pubblica effimera prevista, l'email di destinazione, il pubblico corretto e un timestamp valido.

Il token decodificato dovrebbe avere un aspetto simile a:

{
  "decodedHeader": {
    "alg": "ES256",
    "typ": "JWT",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "decodedPayload": {
    "iss": "https://accounts.issuer.example",
    "sub": "demo@example.com",
    "email": "demo@example.com",
    "iat": 1780272000,
    "exp": 1780272300
  },
  "signature": "SIGnatURE-123_SIGnatURE-123_SIGnatURE-123"
}

2. Rispondere con un token

Dopo aver convalidato correttamente la sessione e il token di richiesta, genera un JWT (JSON Web Token) di divulgazione selettiva (SD-JWT) firmato utilizzando il payload:

{
  "iss": "https://accounts.issuer.example",
  "iat": 1780272000,
  "exp": 1780272300,
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "email": "demo@example.com",
  "email_verified": true
}

Firma il payload utilizzando la tua chiave privata e l'algoritmo supportato. Ad esempio, utilizzando jose in Node.js:

const evtJwt = await new SignJWT(evtPayload)
   .setProtectedHeader({
     alg: "EdDSA",
     kid: PRIVATE_KEY_JWK.kid, // Key ID corresponding to our JWKS keys
     typ: "evt+jwt", // Standard Token Type for EVTs
   })
   .sign(privateKey);

 // Standard SD-JWT compatibility requires appending a trailing tilde "~"
 // to separate the signed token from the key binding section.
 const issuanceToken = `${evtJwt}~`;

Esempio di risposta positiva (HTTP 200):

{
  "issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}

Considerazioni sulla prova dell'origine

Le prove dell'origine sono esperimenti per raccogliere feedback, quindi il tuo contributo è fondamentale se partecipi come Relying Party o provider di identità. Per segnalare problemi, utilizza i seguenti repository GitHub:

Se riscontri bug nell'implementazione di Chrome, segnala un bug per il componente:

L'attivazione della funzionalità di prova dell'origine è controllata in base alla risposta tramite l'inclusione del token OT. Ciò significa che hai un controllo granulare se preferisci limitare la funzionalità a una parte dei tuoi utenti. Ad esempio, se hai già un framework di test A/B, puoi integrare la prova dell'origine per una popolazione di esperimenti controllata. In alternativa, se hai un gruppo di utenti di beta testing o di anteprima, potresti voler o dover attivare la funzionalità per loro. In questo caso, controlla l'indirizzo email fornito prima di emettere o convalidare il token.

Le prove dell'origine hanno anche limiti di traffico per ridurre al minimo i siti che si basano sulla funzionalità prima del lancio. L'API dell'emittente è in fase di sviluppo e dovresti aspettarti modifiche incompatibili con le versioni precedenti insieme agli aggiornamenti dell'esperienza utente di Chrome.

Pubblicheremo ulteriori aggiornamenti sul blog qui e nella evp-announce@chromium.org mailing list man mano che lo sviluppo procede.