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(ohttps://app.issuer.examplecon 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"yautocomplete="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.
- Establece
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:
- Analiza el token con una biblioteca de SD-JWT.
- Valida los valores esperados y las reclamaciones de sesión.
- Verifica la delegación de DNS.
- Descubre los metadatos de la entidad emisora y recupera JWKS.
- 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 sertrue.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) yexp(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:
- Valida la firma de la entidad emisora en el EVT con el JWKS recuperado.
- Valida la firma del navegador en el KB-JWT con la clave pública efímera en
cnf.jwk. - Verifica la vinculación de claves (
aud,noncey el hash de resumensd_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-Trialo 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), ynonceno 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ónkid(ID de clave) en el encabezado EVT y JWKS es opcional (por ejemplo, Gmail omitekid). Sikidno está presente, itera por todas las claves candidatas en eljwks_uride la entidad emisora en lugar de fallar en una búsqueda de ID de clave. - Identificadores de algoritmo (
Ed25519yEdDSA): A partir de Chrome 156, Chrome usa el identificador de algoritmoEd25519completamente especificado (RFC 9864) para los encabezadoscnf.jwkyKB-JWT, mientras que las entidades emisoras y las bibliotecas pueden especificarEd25519oEdDSA(junto conES256). 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ónissdel EVT es un origen HTTPS completo (https://accounts.issuer.example, sin barra diagonal final). Agrega el prefijohttps://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
noncerenderizado 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ónaudes 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.comparafirst.last@example.com). Usa una comparación que no distinga mayúsculas de minúsculas cuando hagas coincidir la reclamaciónemaildel token con el valor del formulario enviado.