Implementación de la parte autenticada

Para implementar la verificación por correo electrónico en tu sitio, actualiza el lenguaje de marcado del formulario para solicitar el token y agrega la validación del servidor para los tokens entrantes.

Regístrate en la prueba de origen

Los sitios de verificación deben tener configurada la prueba de origen en su sitio.

A partir de Chrome 154, se admiten las pruebas de origen de terceros con una advertencia importante: el origen registrado para la prueba debe ser del mismo sitio que la entidad emisora. Por ejemplo:

  • Dominio de la entidad emisora: issuer.example
  • Registrante de la prueba de origen: https://issuer.example
  • Origen de JavaScript: https://issuer.example (o https://app.issuer.example con coincidencia de subdominios)

Configura los campos del formulario

Agrega un campo de token oculto al formulario de envío de correo electrónico:

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

Requisitos de los campos:

  • Campo de correo electrónico: Establece type="email" y autocomplete="email" para que Chrome pueda autocompletar y reconocer la dirección.
  • Atributos del campo de token:
    • Establece autocomplete="email-verification-token": Chrome identifica este campo para propagar el token en el envío.
    • Establece nonce="<VALUE>": El sitio debe proporcionar un nonce único vinculado a la sesión para verificar el envío del formulario.

Valida el token de verificación por correo electrónico (EVT)

Cuando el usuario envía el formulario, tu servidor recibe la dirección de correo electrónico y el token del campo oculto. Un campo de token vacío indica que el navegador o el proveedor no admiten EVP o que el usuario omitió la verificación. Si esto ocurre, vuelve a tu proceso de verificación existente, como enviar un OTP o un vínculo mágico.

Si hay un token, valídalo de la siguiente manera:

  1. Analiza el token con una biblioteca de SD-JWT.
  2. Valida los valores esperados y las reclamaciones de sesión.
  3. Verifica la delegación de DNS.
  4. Descubre los metadatos de la entidad emisora y recupera JWKS.
  5. Verifica las firmas criptográficas y la vinculación de claves.

1. Analiza el token

El token usa el formato RFC 9901: Selective Disclosure JWT (SD-JWT+KB). Usa las bibliotecas adecuadas para tu plataforma para analizar y validar el token. Por ejemplo, para Node, puedes usar @sd-jwt/core y jose. En su forma sin procesar, se ve de la siguiente manera: un JWT firmado por la entidad emisora, seguido de cero o más divulgaciones, y que termina con un JWT de vinculación de claves con cada componente separado por una tilde:

<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

En la implementación actual, el token contiene cero divulgaciones (<Issuer-signed EVT>~<Key Binding JWT>). Sin embargo, esto podría cambiar en el futuro.

Decodifica el token con la biblioteca:

import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;

Si verifier.example verifica demo@provider.example, el token decodificado se ve similar al siguiente:

{
  "evtJwtDecodedHeader": {
    "typ": "evt+jwt",
    "alg": "EdDSA",
    "kid": "issuer-key-id"
  },
  "evtJwtDecodedPayload": {
    "iss": "https://provider.example",
    "iat": 12345678901,
    "exp": 12345679901,
    "cnf": {
      "jwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@provider.example",
    "email_verified": true
  },
  "kbJwtDecodedHeader": {
    "alg": "EdDSA",
    "typ": "kb+jwt"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://verifier.example",
    "iat": 12345678901,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  },
  "disclosures": []
}

2. Valida los valores esperados y las reclamaciones de sesión

Verifica que los valores básicos de la carga útil coincidan con los valores proporcionados y esperados:

  • email_verified: Debe ser true.
  • email: Debe coincidir con la dirección de correo electrónico enviada en el formulario.
  • aud (público): Debe coincidir con el origen de tu sitio.
  • nonce: Debe coincidir con el nonce proporcionado en tu formulario.
  • iat (emitido en) y exp (vencimiento): Confirma que el token esté dentro de su período de validez y que no haya vencido.

3. Verifica la delegación de 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 TXT _email-verification.gmail.com. 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"

Verifica que el esquema de la entidad emisora sea https:// y que https://<domain> coincida con la reclamación iss en el EVT.

4. Verifica la firma del EVT

Recupera los metadatos de descubrimiento de la entidad emisora de https://<issuer>/.well-known/email-verification:

{
  "issuer": "https://accounts.google.com",
  "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": ["Ed25519", "EdDSA"]
}

Si los metadatos incluyen un campo issuer, verifica que coincida con la iss reclamación en el EVT byte por byte. Recupera el conjunto de claves web JSON de jwks_uri.

Usa tu biblioteca de SD-JWT para verificar el paquete de tokens. La biblioteca coordina la validación:

  1. Valida la firma de la entidad emisora en el EVT con el JWKS recuperado.
  2. Valida la firma del navegador en el KB-JWT con la clave pública efímera en cnf.jwk.
  3. Verifica la vinculación de claves (aud, nonce y el hash de resumen sd_hash).

Ejemplo de lógica de verificación en Node.js:

import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
  throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
  hasher,
  // Verifier for the Issuer-signed EVT
  verifier: async (data, sig) => {
    const token = `${data}.${sig}`;
    const header = decoded.jwt.header;
    // Match by kid if present, or iterate across matching algorithm keys
    const keysToTry = header.kid
      ? jwksData.keys.filter(k => k.kid === header.kid)
      : jwksData.keys;
    for (const jwk of keysToTry) {
      try {
        const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
        await compactVerify(token, pubKey);
        return true;
      } catch {
        // Try next candidate key
      }
    }
    return false;
  },
  // Verifier for the Key Binding JWT (KB-JWT)
  kbVerifier: async (data, sig) => {
    try {
      const browserJwkKey = evtPayload.cnf?.jwk;
      if (!browserJwkKey) return false;
      const pubKey = await importJWK(browserJwkKey, kbAlg);
      await compactVerify(`${data}.${sig}`, pubKey);
      return true;
    } catch {
      return false;
    }
  },
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
  kb: {
    expectedNonce: sessionNonce,
    expectedAudience: "https://example.com",
    required: true,
  },
});
const verifiedPayload = result.payload;
if (
  verifiedPayload.email_verified !== true ||
  verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
  throw new Error("Token email does not match submitted email");
}

Si todos los pasos se completan correctamente, verificaste la dirección de correo electrónico con el proveedor. Si falla la verificación, vuelve a enviar un correo electrónico de confirmación al usuario con tu flujo normal.

Solución de problemas

Si falla la verificación o el navegador no proporciona un token, verifica los siguientes problemas comunes:

El campo de token está vacío en el envío

  • Registro de la prueba de origen: Confirma que el encabezado Origin-Trial o la <meta> etiqueta se publiquen en la página y que el token no haya pasado su fecha de vencimiento (los tokens generados antes de la extensión de Chrome 160 vencen el 17 de noviembre, 2026). Para las pruebas de origen de terceros (Chrome 154 y versiones posteriores), el origen de la prueba registrado debe ser del mismo sitio que la entidad emisora (https://<issuer-domain>). Puedes inspeccionar el estado de la prueba de origen y el vencimiento del token en un sitio en DevTools en Application > Frames > (selecciona el marco pertinente) > Origin trials.
  • Lenguaje de marcado del formulario: Tanto <input type="email" autocomplete="email"> como <input type="hidden" autocomplete="email-verification-token" nonce="..."> deben estar en el mismo elemento <form> (no aislados en los límites de Shadow DOM boundaries), y nonce no debe estar vacío.
  • Envío anticipado o página reutilizada: El navegador recupera el token en segundo plano después de que se ingresa o se autocompleta el correo electrónico. Si se envía antes de que se complete la solicitud, el token quedará vacío. Esto puede suceder si el usuario presiona Retorno para enviar el formulario después de ingresar su correo electrónico.
  • Requisitos previos del navegador y del proveedor: El usuario debe haber accedido a un proveedor participante en el mismo perfil del navegador y tener habilitado el correo electrónico verificado en la configuración de Chrome (chrome://settings/contactInfo).

Falla la verificación de la firma de la entidad emisora

  • Falta el encabezado kid: La reclamación kid (ID de clave) en el encabezado EVT y JWKS es opcional (por ejemplo, Gmail omite kid). Si kid no está presente, itera por todas las claves candidatas en el jwks_uri de la entidad emisora en lugar de fallar en una búsqueda de ID de clave.
  • Identificadores de algoritmo (Ed25519 y EdDSA): A partir de Chrome 156, Chrome usa el identificador de algoritmo Ed25519 completamente especificado (RFC 9864) para los encabezados cnf.jwk y KB-JWT, mientras que las entidades emisoras y las bibliotecas pueden especificar Ed25519 o EdDSA (junto con ES256). Asegúrate de que tu lógica de importación y verificación de JWK acepte ambos identificadores.
  • Formato de origen de la entidad emisora (iss): El registro TXT de DNS (_email-verification.<domain>) contiene un nombre de host simple (iss=accounts.issuer.example), mientras que la reclamación iss del EVT es un origen HTTPS completo (https://accounts.issuer.example, sin barra diagonal final). Agrega el prefijo https:// al valor del registro DNS antes de compararlo.

Falla la validación de la vinculación de claves (KB-JWT)

  • Nonce no coincidente o vencido: Asegúrate de que el nonce renderizado en el <input> coincida con el nonce de sesión activo en tu servidor y que no se haya anulado con otra pestaña ni se haya consumido con una solicitud anterior.
  • No coincide el público (aud): La reclamación aud es el origen HTTPS del verificador (https://verifier.example, sin ruta de acceso ni barra diagonal final).

Falla la comparación de la reclamación de correo electrónico (email)

  • Uso de mayúsculas y minúsculas y canonización: Chrome 156 y versiones posteriores muestran la reclamación emailbyte por byte tal como se ingresó en el formulario, pero las versiones anteriores del navegador o los proveedores pueden mostrar una dirección canonizada (por ejemplo,First.Last@example.com para first.last@example.com). Usa una comparación que no distinga mayúsculas de minúsculas cuando hagas coincidir la reclamación email del token con el valor del formulario enviado.