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

Rowan Merewood

Fecha de publicación: 8 de julio 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 la compra, recuperación de cuenta o cualquier otro proceso, es una práctica habitual 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 el 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 función de autocompletar o de la sugerencia de autocompletado 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 de usuario de la API de Email Verification

La recopilación de correos electrónicos es un punto de conversión fundamental en el recorrido de un 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 en la prueba de origen hoy mismo y seguir las instrucciones de implementación aquí. Para obtener información general sobre la configuración de la prueba 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 por correo electrónico, así como todo el flujo de trabajo cuando se usa el protocolo de verificación por 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 verificar la. El verificador también se denomina parte que confía.
  • Proveedor de correo electrónico: Es el servicio que proporciona la dirección de correo electrónico del usuario, por ejemplo gmail.com.
  • Entidad emisora: Es el servicio que administra la cuenta del 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 o autocompletado.

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

    • 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 de autocompletar.

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

Una vez que el usuario tenga esa sesión activa en su navegador, podrá 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 autocompletado. El sitio 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, la entidad emisora confirmará que tiene una sesión activa para esa dirección de correo electrónico.

  3. Luego, la entidad emisora proporcionará su token de verificación por correo electrónico (EVT) para la dirección. El navegador lo combina 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 verificador verifica cada uno de esos detalles: la dirección de correo electrónico esperada, el nonce y las firmas del navegador y la entidad emisora.

  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 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 los casos 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 salga de 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 accesos, los registros de boletines informativos, la creación de cuentas y la 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 volver 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 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 incorporación existentes, y que quieras o necesites pedirle al usuario que revise su configuración de spam.

Implementa el sitio 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 verificación por correo electrónico.

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

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

El nuevo campo hidden se propagará 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 la 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 propagar.

Valida los elementos del formulario verificando el panel de red en las Herramientas para desarrolladores. Cuando seleccionas una dirección de correo electrónico, ves que el navegador activa el DNS y las consultas de búsqueda de cuenta posteriores 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 EVT.

  1. Analiza el token.
  2. Valida los valores esperados.
  3. Valida la vinculación de claves.
  4. Valida el registro DNS.
  5. Descubre la entidad emisora y verifica la firma del EVT.

1. Analiza el token

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

Si example.com verifica demo@gmail.com, la carga útil decodificada es 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 proporcionados:

  • Verifica que email_verified esté configurado como true.
  • Verifica que email coincida con la dirección de correo electrónico proporcionada en tu 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, después de que se renderizó el formulario.

3. Valida la vinculación de claves

El navegador crea una clave efímera y temporal para la transacción para confirmar que firmó el token. Extrae esta clave de la reclamación 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 la reclamación 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 para el dominio de la dirección de correo electrónico. Por ejemplo, para demo@gmail.com, consulta el registro _email-verification.gmail.com TXT. Para este proveedor, la consulta muestra 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 la entidad emisora 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 compatibles.

$ 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 JWKs para verificar el JWT del 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 realizan correctamente, verificaste 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 entidad emisora y proveedor 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 de la entidad emisora en las propuestas de la API de Email Verification y el protocolo de verificación por correo electrónico.

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 en su lugar para responder a esas solicitudes.

Configura el descubrimiento de la entidad emisora

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 delegado de DNS

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

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

Archivo de zona de ejemplo:

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

Aloja un extremo .well-known/email-verification

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

Extremo: 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"]
}

Aloja un extremo .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). Proporciona vínculos a tu extremo de cuentas y a la URL de acceso.

Extremo: 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 a las que se accedió 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.

Extremo: 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 indicar eso al navegador con la API de Login Status.

Cuando un usuario accede o sale correctamente, publica el encabezado de respuesta HTTP coincidente:

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");

Controla las solicitudes de emisión

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

En las siguientes secciones, se muestra el proceso completo de control 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 session/authentication propias del usuario transmitidas 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 ser similar a lo siguiente:

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

Tras la validación correcta de 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 la prueba de origen

Las pruebas de origen son experimentos para recopilar comentarios, por lo que tu opinión es fundamental si participas como parte que confía 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 mediante la inclusión del token 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 trabajo de pruebas A/B, puedes integrar la prueba de origen allí para una población de experimentos controlada. Como alternativa, si tienes un grupo de usuarios de pruebas beta o de vista previa anticipada, es posible que quieras 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 los sitios que dependen de la función antes del lanzamiento. La API de la entidad emisora está en desarrollo, y debes esperar cambios incompatibles con versiones anteriores junto con las actualizaciones de la UX de Chrome.

Publicaremos más actualizaciones en el blog aquí y en la evp-announce@chromium.org a medida que avance el desarrollo.