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 verificación por correo electrónico y el protocolo de verificación por correo electrónico.
Como emisor, no necesitas registrarte en la prueba de origen ni proporcionar un token, ya que el sitio de la entidad emisora activa el comportamiento del navegador. Asegúrate de que tus extremos estén configurados 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 delegado de DNS
Configura un registro TXT de DNS en tu dominio de correo electrónico que delegue la autoridad de verificación a tu identificador de emisor. 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"
El valor iss= debe ser un nombre de host canónico en minúsculas (por ejemplo,
iss=accounts.issuer.example) sin esquema (https://), puerto, ruta ni
caracteres en mayúsculas. Chrome rechaza los registros que incluyen componentes que no son nombres de host.
Aloja un extremo .well-known/email-verification
Aloja un archivo de metadatos JSON en tu dominio de emisor en la ruta /.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:
{
"issuer": "https://accounts.issuer.example",
"issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
"jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["Ed25519", "EdDSA", "ES256"]
}
Propiedades de los metadatos:
issuer: Es el origen de tu emisor (https://<issuer-domain>, sin barra diagonal final). Debe coincidir con el origen desde el que se publica el archivo de metadatos byte por byte.issuance_endpoint: Es la URL HTTPS que recibe las solicitudesPOSTde emisión de tokens.jwks_uri: Es la URL HTTPS que publica tu conjunto de claves web JSON (JWKS) públicas.signing_alg_values_supported: Es un array de algoritmos de firma JWS compatibles.
Aloja un extremo .well-known/web-identity
Es posible que ya hayas implementado un recurso JSON .well-known adicional como
parte de la API Federated Credentials (FedCM). Este recurso 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 con 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 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");
Maneja las solicitudes de emisión
Tu issuance_endpoint recibe una solicitud application/json POST que
contiene la clave email y los encabezados de firmas de mensajes
HTTP para Signature,
Signature-Input y Signature-Key.
Usa una biblioteca que admita encabezados estructurados y firmas de mensajes HTTP para tu entorno. En Node.js, puedes usar
structured-headers y
http-message-sig.
Formato de solicitud completo:
POST /email-verification/issuance HTTP/1.1
Host: provider.example
Accept: application/json
Content-Digest: sha-256=:aBc123aBc123aBc123aBc123aBc123=:
Content-Type: application/json
Sec-Fetch-Dest: email-verification
Signature: sig=:+dEf567dEf567/dEf567dEf567dEf567/dEf567==:
Signature-Input: sig=("@method" "@authority" "@path" "content-digest" "signature-key");created=1786455840
Signature-Key: sig=hwk;alg="Ed25519";crv="Ed25519";kty="OKP";x="gHi890_gHi890_gHi890"
{email: "demo@example.com"}
Analiza y valida la solicitud:
- Autenticación de sesión: Valida las cookies de sesión propias que se envían con la solicitud. El usuario debe estar autenticado.
- Encabezado
Sec-Fetch-Dest: Se establece enemail-verification. - Firmas de mensajes HTTP: Verifica la firma de la solicitud con la
clave pública efímera en
Signature-Keyy valida elContent-Digest. A partir de Chrome 156, elSignature-Keyencabezado incluyealg="Ed25519"en sushwkparámetros. Acepta"Ed25519"y"EdDSA", y permite que las versiones anteriores de Chrome omitanalg. - Carga útil: El cuerpo JSON contiene la cadena
emailsolicitada para la verificación.
Respuesta de emisión
Tras la validación correcta de la sesión y el token de solicitud, genera un JWT de divulgación selectiva (SD-JWT) firmado que se muestra como JSON con las bibliotecas adecuadas para tu plataforma. Por ejemplo, para Node, puedes usar
@sd-jwt/core y
jose.
El formato de carga útil sin procesar debería verse de la siguiente manera:
{
"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
}
Crea, firma y muestra el token:
import { importJWK, CompactSign } from "jose";
import { SDJwtInstance } from "@sd-jwt/core";
import crypto from "node:crypto";
// Issuer private key from secure storage
const privateKey = await importJWK(PRIVATE_KEY_JWK, "EdDSA");
const origin = url.origin;
const currentTime = Math.floor(Date.now() / 1000);
const evtPayload = {
iss: origin,
iat: currentTime,
exp: currentTime + 300, // 5 minutes
cnf: {
jwk: browserJwk,
},
email: payload.email, // exactly as received in payload
email_verified: true,
};
const sdJwt = new SDJwtInstance({
signer: async (data) => {
const [headerB64, payloadB64] = data.split(".");
const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
const payload = Buffer.from(payloadB64, "base64url");
const signed = await new CompactSign(payload).setProtectedHeader(header).sign(privateKey);
return signed.split(".").pop()!;
},
signAlg: "EdDSA",
hasher: async (data, alg) => {
const nodeAlg = alg.replace("-", "");
return new Uint8Array(crypto.createHash(nodeAlg).update(data).digest());
},
hashAlg: "sha-256",
saltGenerator: async () => crypto.randomBytes(16).toString("base64url"),
});
const issuanceToken = await sdJwt.issue(evtPayload, undefined, {
header: {
alg: "EdDSA",
kid: PRIVATE_KEY_JWK.kid,
typ: "evt+jwt",
},
});
return sendResponse({ issuance_token: issuanceToken, }, 200);
El cuerpo de respuesta resultante es similar al siguiente:
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
Después de crear y firmar el token de verificación por correo electrónico, el navegador lo pasa al sitio del verificador para su validación.
Solución de problemas
Si el navegador no se comunica con tus extremos o rechaza los tokens emitidos, verifica los siguientes problemas comunes:
El navegador nunca llama a accounts_endpoint ni a issuance_endpoint
- Estado de acceso no establecido: Chrome solo consulta tus extremos si sabe que el
usuario accedió. Asegúrate de que tu flujo de acceso establezca el
Set-Login: logged-inencabezado HTTP o llame anavigator.login.setStatus("logged-in"). - Cookies de sesión bloqueadas (
SameSite=None): El navegador recupera tuaccounts_endpointyissuance_endpointde una entidad emisora en un sitio diferente. Debido a que se trata de solicitudes entre sitios, tu cookie de sesión debe incluirSameSite=None; Secure. Una cookieSameSite=Laxfunciona cuando se prueba en un verificador del mismo sitio, pero se omite en las solicitudes entre sitios. - Desajuste de descubrimiento o de cuenta: Verifica que
_email-verification.<email-domain>muestre un solo registro TXT con un nombre de host canónico en minúsculas (iss=<issuer-domain>, sinhttps://, un puerto, una ruta ni caracteres en mayúsculas), que ambos extremos.well-knownmuestrenContent-Type: application/json, que.well-known/email-verificationtenga unissuerque coincida conhttps://<issuer-domain>byte por byte y que laaccounts_endpointrespuesta incluya una cuenta cuyoemailcoincida con la dirección ingresada. - Algoritmo de firma no compatible en
.well-known/email-verification: Chrome 154 y 155 requieren"EdDSA"ensigning_alg_values_supported, mientras que Chrome 156+ y la especificación de IETF admiten"Ed25519". Anuncia["Ed25519", "EdDSA"]durante la transición para que Chrome Stable no rechace tus metadatos de descubrimiento.
Falla la validación de la solicitud de emisión
Sec-Fetch-Destortografía del encabezado: Chrome 154+ envíaSec-Fetch-Dest: email-verification(con un guion), mientras que Chrome 153 envióemailverification(sin guion). Acepta ambos valores durante el lanzamiento.- Desajuste de la firma de mensajes HTTP (
@authority) detrás de un proxy: Cuando se verifica la firma RFC 9421, el componente@authorityrefleja el host público. Si tu servidor se encuentra detrás de un proxy inverso o un balanceador de cargas, reconstruye la URL de verificación conX-Forwarded-Host(o tu origen público) en lugar del nombre de host interno y calculaContent-Digestsobre los bytes del cuerpo de la solicitud sin procesar antes del análisis JSON.
El navegador rechaza el issuance_token que se muestra
- Declaración
emailmodificada o canonizada: A partir de Chrome 156, el navegador verifica que la declaraciónemailde EVT coincida con elemailbyte por byte. Si tu backend normaliza la dirección a un formato de cuenta canónico (como mostrarFirst.Last@example.comcuando se solicitófirst.LAST@example.com), Chrome descarta el token. Haz coincidir la solicitud con la cuenta del usuario, pero muestra la cadenaemailexacta que se recibió en el cuerpo de la solicitud. - Falta la tilde final (
~): Incluso con cero divulgaciones, elissuance_tokendebe ser un SD-JWT válido que termine con una tilde final (<Issuer-signed-JWT>~) para que el navegador pueda agregar el<KB-JWT>. - No coinciden
issocnf.jwk: Asegúrate de que la declaraciónissde EVT sea el origen HTTPS exacto (https://<issuer-domain>, sin barra diagonal final) que coincida con tus metadatos.well-known/email-verificationy quecnf.jwkincorpore la clave pública efímera del navegador del encabezadoSignature-Key.