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

Rowan Merewood

Pubblicato: 8 luglio 2026. Ultimo aggiornamento: 5 ottobre 2026

Quando raccogli un indirizzo email nell'ambito di una registrazione, di un accesso, di un abbonamento, di un pagamento, di un recupero dell'account o di un altro processo, è prassi comune confermare che l'indirizzo email appartiene alla persona che lo inserisce. I metodi di verifica esistenti, come le password monouso (OTP) o i link di verifica via email (link magici), richiedono all'utente di uscire dal tuo sito. Questo processo interruttivo può aumentare il rischio che l'utente, che si tratti di una persona o di 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 posta elettronica per verificare che l'utente sia il proprietario dell'indirizzo email. Gli utenti selezionano un'email dal suggerimento di compilazione automatica 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 indirizzi email è un punto di conversione fondamentale nel percorso di un utente e Chrome vorrebbe feedback sulla proposta da siti che vogliono verificare le email, da provider di posta elettronica che possono eseguire la verifica e dagli utenti che sperimentano 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 Guida introduttiva 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 dell'email e l'intero flusso di lavoro quando utilizzi il protocollo di verifica dell'email.

Termini chiave

Di seguito sono riportati i termini chiave per l'API Email Verification:

  • Verificatore: il sito che raccoglie l'indirizzo email e vuole verificarlo. Il verificatore è anche chiamato parte autorizzata.
  • Provider email: il servizio che fornisce l'indirizzo email dell'utente, ad esempio gmail.com.
  • Emittente: il servizio che gestisce l'account per l'email dell'utente, ad esempio accounts.google.com. L'emittente è chiamato anche provider di identità.

In alcuni casi, il provider email e l'emittente potrebbero operare dallo stesso dominio. Tuttavia, è importante distinguere tra l'avere un indirizzo email e l'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 email o emittente nello stesso profilo del browser. Ad esempio, se utilizza Gmail, deve aver eseguito l'accesso al suo 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.

    • Se l'utente ha già inserito un indirizzo email nel campo, questo 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à una richiesta di autorizzazione. Questa operazione viene eseguita una sola volta per indirizzo email.

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

  1. In un modulo con un campo email, l'utente seleziona il proprio indirizzo email dal menu a discesa del 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à di avere una sessione attiva per quell'indirizzo email.

  3. L'emittente fornirà quindi il proprio token di verifica email (EVT) per l'indirizzo. Il browser combina questi elementi in un JWT associato a una 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 visualizza una piccola notifica che lo informa che il suo provider 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 > Dati di contatto > Email verificata (o apri chrome://settings/contactInfo).

Considerazioni sul caso d'uso

La verifica email è un potenziamento 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 dell'email a tutti i moduli pertinenti, come accessi, iscrizioni alla newsletter, creazione di account e recupero 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 ripristinare il flusso di conferma via email predefinito. Ciò significa anche che non viene rilevata alcuna funzionalità per l'API; il sito di verifica considera l'EVT come facoltativo e lo elabora se è presente nella richiesta.

La verifica dell'email conferma che l'utente ha una sessione attiva con il provider del suo indirizzo email. Non verifica che la tua 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.

Implementa il sito di verifica

Per ulteriori dettagli, puoi esaminare il codice della demo end-to-end e fare riferimento ai passaggi di convalida nelle proposte relative all'API Email Verification e al protocollo Email Verification.

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 dell'email al momento dell'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, il browser attiva le query DNS e di ricerca dell'account successive per il provider email e l'emittente. Si tratta di richieste interne del browser; il tuo sito non riceve nulla fino all'invio del modulo.

Convalida l'EVT

Per convalidare ogni componente del pacchetto EVT, sono necessari cinque passaggi.

  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. Analizza il token

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

Se example.com verifica demo@gmail.com, il payload decodificato è 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 a quelli 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. Convalida dell'associazione di tasti

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

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

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

4. Convalida 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 _email-verification.gmail.com TXT. Per questo fornitore, la query restituisce la posizione del fornitore dell'account, ovvero accounts.google.com.

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

5. Scopri l'emittente e verifica la firma EVT

Assicurati che l'emittente fornisca 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 i 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, l'indirizzo email è stato verificato dal provider. In caso contrario, torna all'invio di un'email di conferma all'utente come da flusso normale.

Implementa il servizio del provider email e dell'emittente

Per ulteriori dettagli, puoi esaminare il codice della demo del provider di email simulato e consultare i passaggi per l'emittente nelle proposte relative all'API Email Verification e al protocollo Email Verification.

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 presenti per rispondere a queste richieste.

Configura 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.

Configura il record di delega DNS

Configura un record DNS TXT 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 e all'URL di accesso dei tuoi account.

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 accounts dell'API FedCM fornisce al momento un elenco di account con accesso eseguito. 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 fornitore e devi segnalarlo 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 application/x-www-form-urlencoded POST che contiene 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 proprietari session/authentication dell'utente trasmessi insieme alla richiesta per garantire l'esistenza di 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 al seguente:

{
  "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

Una volta convalidati correttamente la sessione e il token di richiesta, genera un JWT 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 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 riuscita (HTTP 200):

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

Considerazioni sugli origin trial

Le origin trial sono esperimenti per raccogliere feedback, quindi il tuo contributo è fondamentale se partecipi in qualità di relying party o di fornitore di identità. Per segnalare problemi, utilizza i seguenti repository GitHub:

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

L'attivazione della funzionalità di origin trial è controllata in base alla risposta dall'inclusione del token di origin trial. 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 l'origin trial per una popolazione sperimentale controllata. In alternativa, se hai un gruppo di utenti che partecipano a test beta o anteprime, potresti voler o dover attivare la funzionalità per loro. In questo caso, esegui il controllo in base all'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 affidano alla funzionalità prima del lancio. L'API emittente è in fase di sviluppo e devi aspettarti modifiche incompatibili con le versioni precedenti, oltre ad aggiornamenti dell'esperienza utente di Chrome.

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