Implementación del proveedor de correo electrónico (entidad emisora)

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 solicitudes POST de 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 en email-verification.
  • Firmas de mensajes HTTP: Verifica la firma de la solicitud con la clave pública efímera en Signature-Key y valida el Content-Digest. A partir de Chrome 156, el Signature-Key encabezado incluye alg="Ed25519" en sus hwk parámetros. Acepta "Ed25519" y "EdDSA", y permite que las versiones anteriores de Chrome omitan alg.
  • Carga útil: El cuerpo JSON contiene la cadena email solicitada 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-in encabezado HTTP o llame a navigator.login.setStatus("logged-in").
  • Cookies de sesión bloqueadas (SameSite=None): El navegador recupera tu accounts_endpoint y issuance_endpoint de una entidad emisora en un sitio diferente. Debido a que se trata de solicitudes entre sitios, tu cookie de sesión debe incluir SameSite=None; Secure. Una cookie SameSite=Lax funciona 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>, sin https://, un puerto, una ruta ni caracteres en mayúsculas), que ambos extremos .well-known muestren Content-Type: application/json, que .well-known/email-verification tenga un issuer que coincida con https://<issuer-domain> byte por byte y que la accounts_endpoint respuesta incluya una cuenta cuyo email coincida con la dirección ingresada.
  • Algoritmo de firma no compatible en .well-known/email-verification: Chrome 154 y 155 requieren "EdDSA" en signing_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-Dest ortografía del encabezado: Chrome 154+ envía Sec-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 @authority refleja 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 con X-Forwarded-Host (o tu origen público) en lugar del nombre de host interno y calcula Content-Digest sobre 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 email modificada o canonizada: A partir de Chrome 156, el navegador verifica que la declaración email de EVT coincida con el email byte por byte. Si tu backend normaliza la dirección a un formato de cuenta canónico (como mostrar First.Last@example.com cuando se solicitó first.LAST@example.com), Chrome descarta el token. Haz coincidir la solicitud con la cuenta del usuario, pero muestra la cadena email exacta que se recibió en el cuerpo de la solicitud.
  • Falta la tilde final (~): Incluso con cero divulgaciones, el issuance_token debe 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 iss o cnf.jwk: Asegúrate de que la declaración iss de EVT sea el origen HTTPS exacto (https://<issuer-domain>, sin barra diagonal final) que coincida con tus metadatos .well-known/email-verification y que cnf.jwk incorpore la clave pública efímera del navegador del encabezado Signature-Key.