Prueba el protocolo de verificación de correo electrónico con una prueba de origen

Rowan Merewood

Publicado: 8 de julio de 2026. Última actualización: 5 de octubre de 2026

Cuando se recopila una dirección de correo electrónico como parte de un proceso de registro, acceso, suscripción, confirmación de compra, recuperación de la cuenta o algún otro, es una práctica común confirmar que la dirección de correo electrónico pertenece a la persona que la ingresa. Los métodos de verificación existentes, como las contraseñas de un solo uso (OTP) o los vínculos de verificación por correo electrónico (vínculos mágicos), requieren que el usuario salga de tu sitio. Este proceso disruptivo puede aumentar el riesgo de que el usuario, ya sea una persona o un agente, abandone su sesión por completo y nunca complete su proceso de autenticación.

La API de Email Verification es una propuesta que permite que el navegador se comunique directamente con el proveedor de correo electrónico para verificar que el usuario sea el propietario de la dirección de correo electrónico. Los usuarios seleccionan un correo electrónico de la sugerencia de autocompletar del navegador, envían el formulario y el sitio verifica la dirección de correo electrónico con el proveedor sin enviar un correo electrónico ni interrumpir el flujo del usuario.

Demostración de la instrucción del usuario de la API de Email Verification
Demostración de la solicitud del usuario de la API de Email Verification

La recopilación de correos electrónicos es un punto de conversión fundamental en el recorrido del usuario, y Chrome desea recibir comentarios sobre la propuesta de los sitios que desean verificar correos electrónicos, los proveedores de correo electrónico que pueden realizar la verificación y los usuarios que experimentan el proceso. Puedes registrarte para la prueba de origen hoy mismo y seguir las instrucciones de implementación aquí. Para obtener información general sobre la configuración de las pruebas de origen, consulta Cómo comenzar a usar las pruebas de origen.

Puedes probar el flujo con una cuenta de demostración:

Flujo de verificación por correo electrónico

En las siguientes secciones, se explica lo que tú y tus usuarios necesitan para iniciar el flujo de verificación de correo electrónico, y todo el flujo de trabajo cuando se usa el Protocolo de verificación de correo electrónico.

Términos clave

Los términos clave de la API de Email Verification son los siguientes:

  • Verificador: Es el sitio que recopila la dirección de correo electrónico y desea verificarla. El verificador también se denomina parte confiante.
  • Proveedor de correo electrónico: Es el servicio que proporciona la dirección de correo electrónico del usuario, por ejemplo, gmail.com.
  • Emisor: Es el servicio que administra la cuenta de correo electrónico del usuario, por ejemplo, accounts.google.com. La entidad emisora también se denomina proveedor de identidad.

En algunos casos, el proveedor de correo electrónico y la entidad emisora pueden operar desde el mismo dominio. Sin embargo, es importante distinguir entre tener una dirección de correo electrónico y tener una sesión activa para la cuenta asociada.

Arquitectura del flujo de verificación por correo electrónico
Arquitectura del flujo de verificación por correo electrónico

Requisitos previos

  • El usuario debe acceder a su proveedor de correo electrónico o entidad emisora en el mismo perfil del navegador. Por ejemplo, si usa Gmail, debe acceder a su Cuenta de Google.
  • Como sitio verificador participante, debes registrarte en la prueba de origen y proporcionar el token en la misma página que tu formulario de correo electrónico.

  • El usuario debe seleccionar su dirección de correo electrónico en el menú desplegable de autocompletar.

    • Si el usuario ya ingresó una dirección de correo electrónico en el campo, se ofrecerá con la función de autocompletar.

    • Si el usuario agregó su dirección de correo electrónico con la configuración de Chrome "Autocompletar y contraseñas" (chrome://settings/autofill), se ofrecerá con la función Autocompletar.

  • La primera vez que un usuario proporcione una dirección de correo electrónico para la verificación, verá un mensaje de permiso. Esto solo ocurre una vez por dirección de correo electrónico.

Una vez que el usuario tiene esa sesión activa en su navegador, puede iniciar el proceso:

  1. En un formulario con un campo de correo electrónico, el usuario selecciona su dirección de correo electrónico en el menú desplegable de autocompletar. El sitio del verificador proporciona un campo oculto en el formulario con un nonce por instancia para validar esta solicitud.

  2. Luego, el navegador recuperará el registro DNS de verificación por correo electrónico para el dominio de correo electrónico. Esto dirige el navegador a la entidad emisora. Luego, el emisor confirmará que tiene una sesión activa para esa dirección de correo electrónico.

  3. Luego, el emisor proporcionará su token de verificación de correo electrónico (EVT) para la dirección. El navegador combina todo eso en un JWT vinculado a la clave con el EVT, el origen del sitio y el nonce del formulario de entrada.

  4. Cuando se envía el formulario, el paquete EVT se agrega al campo oculto y se envía al sitio.

  5. Luego, el sitio del verificador verifica cada uno de esos detalles: la dirección de correo electrónico esperada, el nonce y las firmas del navegador y del emisor.

  6. El usuario ve una pequeña notificación que le informa que su proveedor de correo electrónico verificó su dirección.

Este proceso le proporciona al sitio verificador la confirmación de que la dirección de correo electrónico es válida y pertenece al usuario actual, lo que significa que el sitio puede omitir el envío de un correo electrónico de verificación.

Los usuarios pueden administrar sus correos electrónicos verificados en Configuración > Autocompletar y contraseñas > Información de contacto > Correo electrónico verificado (o abrir chrome://settings/contactInfo).

Consideraciones sobre el caso de uso

La verificación por correo electrónico es una mejora progresiva de tu flujo existente que elimina la necesidad de que un usuario abandone tu sitio para recuperar una OTP o hacer clic en un vínculo. Los sitios pueden agregar los campos de verificación por correo electrónico a todos los formularios pertinentes, como los de acceso, registro a boletines informativos, creación de cuentas y recuperación de contraseñas. El EVP se activa solo si el navegador lo admite. Si no se recibe ningún código en el envío o falla alguno de los pasos de validación, puedes recurrir a tu flujo de confirmación por correo electrónico predeterminado. Esto también significa que no hay detección de funciones para la API; el sitio del verificador trata el EVT como opcional y lo procesa si está presente en la solicitud.

La verificación por correo electrónico confirma que el usuario tiene una sesión activa con el proveedor de su dirección de correo electrónico. No verifica que tu correo electrónico haya llegado al usuario. Es posible que aún quieras enviar correos electrónicos de bienvenida o integración existentes, y que quieras o necesites pedirle al usuario que revise su configuración de spam.

Implementa el sitio del verificador

Para obtener más detalles, puedes consultar el código de demostración de extremo a extremo y consultar los pasos de validación en las propuestas de la API de Email Verification y el Protocolo de Email Verification.

Configura los campos del formulario

Asegúrate de que los campos del formulario tengan los atributos correctos:

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

Establece los atributos type y autocomplete de la entrada email en email para permitir que el navegador ofrezca autocompletar la dirección de correo electrónico.

El nuevo campo hidden se completará con el token de verificación por correo electrónico cuando se envíe el formulario. Los atributos necesarios son los siguientes:

  • Establece type="hidden" porque este campo no requiere entrada del usuario.
  • Establece nonce="rAnD0m-VaLuE". El sitio debe proporcionar un nonce único vinculado a la sesión para verificar el envío del formulario.
  • Establece autocomplete="email-verification-token". El navegador usa este atributo para identificar el campo que se debe completar.

Valida los elementos de tu formulario. Para ello, revisa el panel Network en DevTools. Cuando seleccionas una dirección de correo electrónico, ves que el navegador activa el DNS y las consultas posteriores de búsqueda de cuentas para el proveedor de correo electrónico y la entidad emisora. Estas son solicitudes internas del navegador; tu sitio no recibe nada hasta que se envía el formulario.

Valida el EVT

Hay cinco pasos para validar cada componente del paquete de EVT.

  1. Analiza el token.
  2. Valida los valores esperados.
  3. Valida la vinculación de la clave.
  4. Valida el registro DNS.
  5. descubrir el emisor y verificar la firma del EVT

1. Analiza el token

Los datos sin procesar del envío del formulario contienen el EVT y las declaraciones firmadas en un token web JSON de divulgación selectiva (SD-JWT+KB) separados por una virgulilla (carácter ~). Deberás separar estos elementos y decodificar los encabezados y las cargas útiles de la firma y el cifrado de objetos de JavaScript (JOSE) (por ejemplo, con jose para Node.js).

Si example.com verifica demo@gmail.com, la carga útil decodificada se verá similar al siguiente ejemplo:

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

Verifica que los valores básicos de la carga útil coincidan con los valores que proporcionaste:

  • Verifica que email_verified esté configurado como true.
  • Verifica que email coincida con la dirección de correo electrónico que proporcionaste en el formulario.
  • Verifica que nonce coincida con el nonce proporcionado en tu formulario.
  • Verifica que aud coincida con el origen de tu sitio.
  • Verifica que iat tenga una marca de tiempo relativamente reciente, por ejemplo, posterior a la renderización del formulario.

3. Valida la vinculación de la llave

El navegador crea una clave efímera y temporal para la transacción con el fin de confirmar que firmó el token. Extrae esta clave del reclamo cnf (confirmación) en el EVT y, luego, úsala para verificar el JWT vinculado a la clave.

Luego, calcula el hash esperado y compáralo con el reclamo sd_hash. En el siguiente ejemplo de Node.js, se muestra cómo realizar este cálculo:

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

4. Valida el registro DNS

Verifica el registro DNS _email-verification del dominio de la dirección de correo electrónico. Por ejemplo, para demo@gmail.com, consulta el registro _email-verification.gmail.com TXT. En el caso de este proveedor, la consulta devuelve la ubicación del proveedor de la cuenta, es decir, accounts.google.com.

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

5. Descubre el emisor y verifica la firma del EVT

Asegúrate de que la entidad emisora publique el recurso /.well-known/email-verification, que proporciona los extremos para emitir el token, la clave web JSON (JWK) para el sitio y los algoritmos de firma admitidos.

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

Usa los JWK para verificar el JWT de EVT que extrajiste del token. La mayoría de las bibliotecas de JOSE proporcionan funciones para controlar esta verificación.

Si los cinco pasos se completan correctamente, habrás verificado la dirección de correo electrónico con el proveedor. De lo contrario, vuelve a enviar un correo electrónico de confirmación al usuario según tu flujo normal.

Implementa el servicio de proveedor y emisor de correo electrónico

Para obtener más detalles, puedes consultar el código de demostración del proveedor de correo electrónico simulado y consultar los pasos del emisor en las propuestas de la API de Email Verification y el Protocolo de Email Verification.

Como entidad emisora, no necesitas registrarte en la prueba de origen ni proporcionar un token, ya que el comportamiento del navegador se activa en el sitio de la parte que confía. Solo debes asegurarte de que los extremos esperados estén disponibles para responder a esas solicitudes.

Configura el descubrimiento del emisor

Para permitir que los navegadores descubran automáticamente tus extremos de verificación cuando se selecciona una dirección de correo electrónico que pertenece a tu dominio, expón tu configuración con DNS y un extremo HTTP .well-known.

Configura el registro de delegación de DNS

Configura un registro TXT de DNS en tu dominio de correo electrónico que delegue la autoridad de verificación en el identificador de tu entidad emisora. Estos identificadores pueden usar el mismo dominio según tu infraestructura.

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

Ejemplo de archivo de zona:

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

Cómo alojar un extremo de .well-known/email-verification

Aloja un archivo de metadatos JSON en la ruta /.well-known/ de tu dominio de la entidad emisora. En este archivo, se describen tus capacidades de emisión y los algoritmos de firma criptográfica que admite tu infraestructura.

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

Respuesta de ejemplo:

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

Cómo alojar un extremo de .well-known/web-identity

Un recurso JSON .well-known adicional que es posible que ya hayas implementado como parte de la API de Federated Credentials (FedCM). Esto proporciona vínculos al extremo de tus cuentas y a la URL de acceso.

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

Respuesta de ejemplo:

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

Usa un extremo de cuentas

El extremo de cuentas de la API de FedCM proporciona una lista de las cuentas que accedieron en el momento. En el siguiente ejemplo, se muestra una respuesta mínima. Para obtener más detalles, consulta la guía de implementación del proveedor de identidad.

Endpoint: Como se especifica en .well-known/web-identity

A continuación, se muestra una respuesta de ejemplo:

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

Realiza la integración con la API de Login Status

El usuario debe tener una sesión activa con el proveedor, y debes indicarle eso al navegador con la API de Login Status.

Cuando un usuario acceda o salga correctamente, publica el encabezado de respuesta HTTP correspondiente:

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

Como alternativa, actualiza el estado con JavaScript en el contexto de tu aplicación web:

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

Cómo controlar las solicitudes de emisión

Tu issuance_endpoint recibe una solicitud de application/x-www-form-urlencoded POST que contiene el request_token.

En las siguientes secciones, se muestra el proceso completo de manejo de solicitudes de emisión.

1. Valida la solicitud de emisión

Analiza y valida las cargas útiles entrantes del navegador:

  • Método: POST
  • Verificación de sesión: Valida las cookies de origen session/authentication del usuario que se transmiten junto con la solicitud para garantizar que exista un contexto de identidad activo y autorizado.
  • Verificación de parámetros: Extrae el parámetro request_token (un JWT firmado generado por el navegador). Verifica que contenga la clave pública efímera esperada, el correo electrónico de destino, el público correcto y una marca de tiempo válida.

El token decodificado debería verse de la siguiente manera:

{
  "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 con un token

Una vez que se valida correctamente la sesión y el token de solicitud, genera un JWT de divulgación selectiva (SD-JWT) firmado con la carga útil:

{
  "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 la carga útil con tu clave privada y el algoritmo compatible. Por ejemplo, con jose en 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}~`;

Ejemplo de respuesta correcta (HTTP 200):

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

Consideraciones sobre las pruebas de origen

Las pruebas de origen son experimentos para recopilar comentarios, por lo que tu opinión es fundamental si participas como parte dependiente o proveedor de identidad. Para informar problemas, usa los siguientes repositorios de GitHub:

Si encuentras errores en la implementación de Chrome, informa un error en el componente:

La habilitación de la funcionalidad de la prueba de origen se controla por respuesta a través de la inclusión del token de OT. Esto significa que tienes un control detallado si prefieres restringir la funcionalidad a una parte de tus usuarios. Por ejemplo, si ya tienes un marco de pruebas A/B, puedes integrar la prueba de origen allí para obtener una población de experimentos controlada. Como alternativa, si tienes un grupo de usuarios para pruebas beta o de vista previa anticipada, es posible que desees o necesites habilitar la función para ellos. En este caso, verifica la dirección de correo electrónico proporcionada antes de emitir o validar el token.

Las pruebas de origen también tienen límites de tráfico para minimizar la cantidad de sitios que dependen de la función antes del lanzamiento. La API del emisor está en desarrollo, por lo que es probable que haya cambios incompatibles con versiones anteriores junto con actualizaciones de la UX de Chrome.

Publicaremos más actualizaciones en este blog y en la lista de distribución de correos electrónicos evp-announce@chromium.org a medida que avance el desarrollo.