Testar o protocolo de verificação de e-mail com um teste de origem

Rowan Merewood

Publicado em: 8 de julho de 2026

Ao coletar um endereço de e-mail como parte de um processo de inscrição, login, assinatura, finalização da compra, recuperação de conta ou outro, é comum confirmar se o endereço de e-mail pertence à pessoa que o está inserindo. Os métodos de verificação atuais, como senhas de uso único (OTPs) ou links de verificação de e-mail (links mágicos), exigem que o usuário saia do seu site. Esse processo disruptivo pode aumentar o risco de o usuário, seja humano ou um agente, abandonar a sessão completamente e nunca concluir o processo de autenticação.

A API Email Verification é uma proposta que permite que o navegador se comunique diretamente com o provedor de e-mail para verificar se o usuário é o proprietário do endereço de e-mail. Os usuários selecionam um e-mail no preenchimento automático ou na sugestão de preenchimento automático do navegador, enviam o formulário e o site verifica o endereço de e-mail com o provedor sem enviar um e-mail ou interromper o fluxo do usuário.

Demonstração do prompt do usuário da API Email Verification
Demonstração do prompt do usuário da API Email Verification

A coleta de e-mails é um ponto de conversão essencial na jornada de um usuário, e o Chrome gostaria de receber feedback sobre a proposta de sites que querem verificar e-mails, provedores de e-mail que podem realizar a verificação, e usuários que estão passando pelo processo. Inscreva-se no teste de origem hoje mesmo e siga as instruções de implementação aqui. Para a configuração geral do teste de origem, consulte Introdução aos testes de origem.

Você pode testar o fluxo com uma conta de demonstração:

Fluxo de verificação de e-mail

As seções a seguir explicam o que você e seus usuários precisam para iniciar o fluxo de verificação de e-mail e todo o fluxo de trabalho ao usar o protocolo de verificação de e-mail.

Termos-chave

Os termos-chave da API Email Verification são os seguintes:

  • Verificador: o site que coleta o endereço de e-mail e quer verificar isso. O verificador também é chamado de parte confiável.
  • Provedor de e-mail: o serviço que fornece o endereço de e-mail do usuário, por exemplo gmail.com.
  • Emissor: o serviço que gerencia a conta do e-mail do usuário, por exemplo accounts.google.com. O emissor também é chamado de provedor de identidade.

Em alguns casos, o provedor de e-mail e o emissor podem operar no mesmo domínio. No entanto, é importante distinguir entre ter um endereço de e-mail e ter uma sessão ativa para a conta associada.

Arquitetura do fluxo de verificação por e-mail
Arquitetura do fluxo de verificação de e-mail

Pré-requisitos

  • O usuário precisa fazer login no provedor de e-mail ou no emissor no mesmo perfil do navegador. Por exemplo, se ele usar o Gmail, precisará fazer login na Conta do Google.
  • Como um site verificador participante, você precisa se inscrever no teste de origem e fornecer o token na mesma página do formulário de e-mail.

  • O usuário precisa selecionar o endereço de e-mail no menu suspenso de preenchimento automático ou preenchimento automático.

    • Se o usuário tiver inserido um endereço de e-mail no campo anteriormente, ele será oferecido usando o preenchimento automático.

    • Se o usuário tiver adicionado o endereço de e-mail usando as configurações do Chrome "Preenchimento automático e senha" (chrome://settings/autofill), ele será oferecido usando o preenchimento automático.

  • Na primeira vez que um usuário fornecer um endereço de e-mail para verificação, ele vai receber um prompt de permissão. Isso só ocorre uma vez por endereço de e-mail.

Depois que o usuário tiver essa sessão ativa no navegador, ele poderá iniciar o processo:

  1. Em um formulário com um campo de e-mail, o usuário seleciona o endereço de e-mail no menu suspenso de preenchimento automático. O site do verificador fornece um campo oculto no formulário com um nonce por instância para validar essa solicitação.

  2. Em seguida, o navegador vai recuperar o registro DNS de verificação de e-mail do domínio de e-mail. Isso aponta o navegador para o emissor. Em seguida, o emissor vai confirmar que tem uma sessão ativa para esse endereço de e-mail.

  3. Em seguida, o emissor vai fornecer o token de verificação de e-mail (EVT, na sigla em inglês) para o endereço. O navegador combina isso em um JWT vinculado à chave com o EVT, a origem do site e o nonce do formulário de entrada.

  4. Quando o formulário é enviado, o pacote EVT é adicionado ao campo oculto e enviado ao site.

  5. Em seguida, o site do verificador verifica cada um desses detalhes: o endereço de e-mail esperado, o nonce e as assinaturas do navegador e do emissor.

  6. O usuário recebe uma pequena notificação informando que o provedor de e-mail verificou o endereço.

Esse processo fornece ao site do verificador a confirmação de que o endereço de e-mail é válido e pertence ao usuário atual, o que significa que o site pode pular o envio de um e-mail de verificação.

Os usuários podem gerenciar os e-mails verificados em Configurações > Preenchimento automático e senhas > Informações de contato > E-mail verificado (ou abrir chrome://settings/contactInfo).

Considerações sobre casos de uso

A verificação de e-mail é um aprimoramento progressivo do fluxo atual que remove a necessidade de um usuário sair do seu site para recuperar uma OTP ou clicar em um link. Os sites podem adicionar os campos de verificação de e-mail a todos os formulários relevantes, como logins, inscrições em newsletters, criação de contas e recuperação de senhas. O EVP é acionado apenas se o navegador oferecer suporte a ele. Se nenhum código for recebido no envio ou se alguma das etapas de validação falhar, você poderá voltar ao fluxo de confirmação de e-mail padrão. Isso também significa que não há detecção de recursos para a API. O site do verificador trata o EVT como opcional, processando-o se ele estiver presente na solicitação.

A verificação de e-mail confirma que o usuário tem uma sessão ativa com o provedor do endereço de e-mail. Ela não verifica se o e-mail chegou ao usuário. Talvez você ainda queira enviar e-mails de boas-vindas ou de integração e talvez queira ou precise pedir ao usuário para verificar as configurações de spam.

Implementar o site do verificador

Para mais detalhes, você pode acessar o código de demonstração completo e consultar as etapas de validação nas propostas da API Email Verification e do protocolo de verificação de e-mail.

Configurar campos de formulário

Verifique se os campos do formulário têm os atributos corretos:

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

Defina os atributos type e autocomplete da entrada email como email para permitir que o navegador ofereça preenchimento automático para o endereço de e-mail.

O novo campo hidden será preenchido com o token de verificação de e-mail no envio do formulário. Os atributos necessários são:

  • Defina type="hidden" porque esse campo não exige entrada do usuário.
  • Defina nonce="rAnD0m-VaLuE". O site precisa fornecer um nonce exclusivo vinculado à sessão para verificar o envio do formulário.
  • Defina autocomplete="email-verification-token". O navegador usa esse atributo para identificar o campo a ser preenchido.

Valide os elementos do formulário verificando o painel "Rede" nas Ferramentas para desenvolvedores. Quando você seleciona um endereço de e-mail, o navegador aciona o DNS e as consultas de pesquisa de conta subsequentes para o provedor de e-mail e o emissor. Essas são solicitações internas do navegador. Seu site não recebe nada até o envio do formulário.

Validar o EVT

Há cinco etapas para validar cada componente do pacote EVT.

  1. Analise o token.
  2. Valide os valores esperados.
  3. Valide a vinculação de chaves.
  4. Valide o registro DNS.
  5. Descubra o emissor e verifique a assinatura do EVT.

1. Analise o token

Os dados brutos do envio do formulário contêm o EVT e as declarações assinadas em um JSON Web Token de divulgação seletiva (SD-JWT+KB) separados por um til (~ caractere). Você precisará separar esses dados e decodificar os cabeçalhos e payloads de assinatura e criptografia de objetos JavaScript (JOSE, na sigla em inglês), por exemplo, usando jose para Node.js.

Se example.com verificar demo@gmail.com, o payload decodificado será semelhante ao exemplo a seguir:

{
  "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. Validar valores esperados

Verifique se os valores básicos no payload correspondem aos valores fornecidos:

  • Verifique se email_verified está definido como true.
  • Verifique se email corresponde ao endereço de e-mail fornecido no formulário.
  • Verifique se nonce corresponde ao nonce fornecido no formulário.
  • Verifique se aud corresponde à origem do seu site.
  • Verifique se iat tem um carimbo de data/hora relativamente recente, por exemplo, depois que o formulário foi renderizado.

3. Validar a vinculação de chaves

O navegador cria uma chave temporária e efêmera para a transação para confirmar que ela assinou o token. Extraia essa chave da declaração cnf (confirmação) no EVT e use-a para verificar o JWT vinculado à chave.

Em seguida, calcule o hash esperado e compare-o com a declaração sd_hash. O exemplo de Node.js a seguir mostra como realizar esse cálculo:

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

4. Validar o registro DNS

Verifique o registro DNS _email-verification do domínio do endereço de e-mail. Por exemplo, para demo@gmail.com, consulte o registro _email-verification.gmail.com TXT. Para esse provedor, a consulta retorna o local do provedor de contas, ou seja, accounts.google.com.

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

5. Descobrir o emissor e verificar a assinatura do EVT

Verifique se o emissor veicula o recurso /.well-known/email-verification, que fornece os endpoints para emitir o token, a chave da Web JSON (JWK) para o site e os algoritmos de assinatura compatíveis.

$ 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"]
}

Use as JWKs para verificar o JWT do EVT extraído do token. A maioria das bibliotecas JOSE fornece funções para processar essa verificação.

Se todas as cinco etapas forem bem-sucedidas, você terá verificado o endereço de e-mail no provedor. Caso contrário, volte a enviar um e-mail de confirmação ao usuário de acordo com o fluxo normal.

Implementar o serviço de provedor de e-mail e emissor

Para mais detalhes, você pode acessar o código de demonstração do provedor de e-mail simulado e consultar as etapas do emissor nas propostas da API Email Verification e do protocolo de verificação de e-mail.

Como emissor, você não precisa se inscrever no teste de origem nem fornecer um token, já que o comportamento do navegador é acionado pelo site da parte confiável. Você só precisa garantir que os endpoints esperados estejam em vigor para responder a essas solicitações.

Configurar a descoberta do emissor

Para permitir que os navegadores descubram automaticamente seus endpoints de verificação quando um endereço de e-mail pertencente ao seu domínio for selecionado, exponha sua configuração usando o DNS e um endpoint HTTP .well-known.

Configurar o registro de delegado de DNS

Configure um registro TXT de DNS no seu domínio de e-mail que delega a autoridade de verificação ao identificador do emissor. Esses identificadores podem usar o mesmo domínio, dependendo da sua infraestrutura.

Formato do registro: _email-verification.<email-domain>

Exemplo de arquivo de zona:

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

Hospedar um endpoint .well-known/email-verification

Hospede um arquivo JSON de metadados no domínio do emissor no caminho /.well-known/. Esse arquivo descreve suas capacidades de emissão e os algoritmos de assinatura criptográfica que sua infraestrutura oferece suporte.

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

Exemplo de resposta:

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

Hospedar um endpoint .well-known/web-identity

Um recurso JSON .well-known adicional que você já pode ter implementado como parte da API Federated Credentials (FedCM) . Isso fornece links para o endpoint de contas e o URL de login.

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

Exemplo de resposta:

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

Usar um endpoint de contas

O endpoint de contas da API FedCM fornece uma lista de contas conectadas no momento. O exemplo a seguir mostra uma resposta mínima. Para mais detalhes, consulte o guia de implementação do provedor de identidade.

Endpoint: conforme especificado em .well-known/web-identity

Veja a seguir um exemplo de resposta:

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

Integrar com a API Login Status

O usuário precisa ter uma sessão ativa com o provedor, e você precisa sinalizar isso para o navegador com a API Login Status.

Quando um usuário faz login ou logout, veicule o cabeçalho de resposta HTTP correspondente:

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

Como alternativa, atualize o status usando JavaScript no contexto do aplicativo da Web:

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

Processar solicitações de emissão

O issuance_endpoint recebe uma solicitação application/x-www-form-urlencoded POST que contém o request_token.

As seções a seguir mostram o processo completo de tratamento de solicitações de emissão.

1. Validar a solicitação de emissão

Analise e valide os payloads do navegador recebidos:

  • Método:POST
  • Verificação de sessão:valide os cookies primários session/authentication do usuário transmitidos junto com a solicitação para garantir que um contexto de identidade ativo e autorizado exista.
  • Verificação de parâmetros:extraia o parâmetro request_token (um JWT assinado gerado pelo navegador). Verifique se ele contém a chave pública efêmera esperada, o e-mail de destino, o público-alvo correto e um carimbo de data/hora válido.

O token decodificado deve ser semelhante 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. Responder com um token

Após a validação bem-sucedida da sessão e do token de solicitação, gere um JWT de divulgação seletiva assinado (SD-JWT) usando o 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
}

Assine o payload usando sua chave privada e o algoritmo compatível. Por exemplo, usando jose no 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}~`;

Exemplo de resposta bem-sucedida (HTTP 200):

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

Considerações sobre o teste de origem

Os testes de origem são experimentos para coletar feedback. Portanto, sua entrada é fundamental se você participar como uma parte confiável ou um provedor de identidade. Para informar problemas, use os seguintes repositórios do GitHub:

Se você encontrar bugs na implementação do Chrome, registre um bug no componente:

A ativação da funcionalidade de teste de origem é controlada por resposta pela inclusão do token OT. Isso significa que você tem controle refinado se preferir restringir a funcionalidade a uma parte dos usuários. Por exemplo, se você já tiver uma estrutura de testes A/B, poderá integrar o teste de origem para uma população de experimentos controlada. Como alternativa, se você tiver um grupo de usuários de testes Beta ou de visualização antecipada, talvez queira ou precise ativar o recurso para eles. Nesse caso, verifique o endereço de e-mail fornecido antes de emitir ou validar o token.

Os testes de origem também têm limites de tráfego para minimizar os sites que dependem do recurso antes do lançamento. A API do emissor está em desenvolvimento, e você deve esperar mudanças incompatíveis com versões anteriores, além de atualizações na UX do Chrome.

Vamos postar mais atualizações no blog aqui e na evp-announce@chromium.org à medida que o desenvolvimento avança.