Implémentation du fournisseur de messagerie (émetteur)

Pour en savoir plus, vous pouvez consulter le code de démonstration du fournisseur de messagerie fictif et vous reporter aux étapes de l'émetteur dans les propositions d'API et de protocole de validation de l'adresse e-mail.

En tant qu'émetteur, vous n'avez pas besoin de vous inscrire à l'essai Origin Trial ni de fournir de jeton, car le site de la partie utilisatrice déclenche le comportement du navigateur. Assurez-vous que vos points de terminaison sont configurés pour répondre à ces requêtes.

Configurer la découverte de l'émetteur

Pour permettre aux navigateurs de découvrir automatiquement vos points de terminaison de validation lorsqu'une adresse e-mail appartenant à votre domaine est sélectionnée, exposez votre configuration à l'aide du DNS et d'un point de terminaison HTTP .well-known.

Configurer l'enregistrement de délégué DNS

Configurez un enregistrement TXT DNS sur votre domaine de messagerie qui délègue l'autorité de validation à votre identifiant d'émetteur. Ces identifiants peuvent utiliser le même domaine en fonction de votre infrastructure.

Format de l'enregistrement : _email-verification.<email-domain>

Exemple de fichier de zone :

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

La valeur iss= doit être un nom d'hôte en minuscules canonique et simple (par exemple, iss=accounts.issuer.example) sans schéma (https://), port, chemin d'accès ni caractères majuscules. Chrome rejette les enregistrements qui incluent des composants autres que le nom d'hôte.

Héberger un point de terminaison .well-known/email-verification

Hébergez un fichier de métadonnées JSON sur votre domaine d'émetteur sous le chemin d'accès /.well-known/. Ce fichier décrit vos capacités d'émission et les algorithmes de signature cryptographique compatibles avec votre infrastructure.

Point de terminaison : https://<issuer-domain>/.well-known/email-verification

Exemple de réponse :

{
  "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"]
}

Propriétés des métadonnées :

  • issuer : origine de votre émetteur (https://<issuer-domain>, sans barre oblique à la fin). Doit correspondre à l'origine à partir de laquelle le fichier de métadonnées est diffusé, octet par octet.
  • issuance_endpoint: URL HTTPS qui reçoit les requêtes POST d'émission de jeton.
  • jwks_uri : URL HTTPS qui diffuse votre ensemble de clés Web JSON publiques (JWKS).
  • signing_alg_values_supported : tableau des algorithmes de signature JWS compatibles.

Héberger un point de terminaison .well-known/web-identity

Vous avez peut-être déjà implémenté une ressource JSON .well-known supplémentaire dans le cadre de l'API Federated Credentials (FedCM). Cette ressource fournit des liens vers votre point de terminaison de comptes et votre URL de connexion.

Point de terminaison : https://<domain>/.well-known/web-identity

Exemple de réponse :

{
  "accounts_endpoint": "https://accounts.issuer.example/accounts",
  "login_url": "https://accounts.issuer.example/login"
}

Utiliser un point de terminaison de comptes

Le point de terminaison de comptes de l'API FedCM fournit une liste des comptes connectés pour le moment. L'exemple suivant montre une réponse minimale. Pour en savoir plus, consultez le guide d'implémentation du fournisseur d'identité.

Point de terminaison : tel que spécifié dans .well-known/web-identity

Voici un exemple de réponse :

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

Intégrer l'API Login Status

L'utilisateur doit avoir une session active avec le fournisseur, et vous devez le signaler au navigateur à l'aide de l'API Login Status.

Lorsqu'un utilisateur se connecte ou se déconnecte, diffusez l'en-tête de réponse HTTP correspondant :

Set-Login: logged-in
Set-Login: logged-out

Vous pouvez également mettre à jour l'état à l'aide de JavaScript dans le contexte de votre application Web :

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

Gérer les requêtes d'émission

Votre issuance_endpoint reçoit une requête POST application/json qui contient la clé email et les en-têtes HTTP Message Signatures pour Signature, Signature-Input et Signature-Key.

Utilisez une bibliothèque compatible avec les en-têtes structurés et les signatures de messages HTTP pour votre environnement. Dans Node.js, vous pouvez utiliser structured-headers et http-message-sig.

Format complet de la requête :

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

Analysez et validez la requête :

  • Authentification de la session : validez les cookies de session propriétaires envoyés avec la requête. L'utilisateur doit être authentifié.
  • En-tête Sec-Fetch-Dest : défini sur email-verification.
  • Signatures de messages HTTP : vérifiez la signature de la requête à l'aide de la clé publique éphémère dans Signature-Key et validez le Content-Digest. À partir de Chrome 156, l'en-tête Signature-Key inclut alg="Ed25519" dans ses hwk paramètres. Acceptez "Ed25519" et "EdDSA", et autorisez l'omission de alg par les versions antérieures de Chrome.
  • Charge utile : le corps JSON contient la chaîne email demandée pour la validation.

Réponse d'émission

Une fois la session et le jeton de requête validés, générez un JWT de divulgation sélective (SD-JWT) signé renvoyé au format JSON à l'aide des bibliothèques appropriées pour votre plate-forme. Par exemple, pour Node, vous pouvez utiliser @sd-jwt/core et jose.

Le format brut de la charge utile doit se présenter comme suit :

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

Créez, signez et renvoyez le jeton :

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

Le corps de la réponse obtenue se présente comme suit :

{
  "issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}

Une fois que vous avez créé et signé le jeton de validation de l'adresse e-mail, le navigateur le transmet au site du validateur pour validation.

Dépannage

Si le navigateur ne contacte pas vos points de terminaison ou rejette les jetons émis, vérifiez les problèmes courants suivants :

Le navigateur n'appelle jamais accounts_endpoint ni issuance_endpoint

  • État de connexion non défini : Chrome n'interroge vos points de terminaison que s'il sait que l' utilisateur est connecté. Assurez-vous que votre flux de connexion définit l'en-tête Set-Login: logged-in HTTP ou appelle navigator.login.setStatus("logged-in").
  • Cookies de session bloqués (SameSite=None) : le navigateur récupère votre accounts_endpoint et votre issuance_endpoint à partir d'une partie utilisatrice sur un autre site. Comme il s'agit de requêtes intersites, votre cookie de session doit inclure SameSite=None; Secure. Un cookie SameSite=Lax fonctionne lors des tests sur un validateur du même site, mais il est omis dans les requêtes intersites.
  • Incompatibilité de la découverte ou du compte : vérifiez que _email-verification.<email-domain> renvoie un seul enregistrement TXT avec un nom d'hôte en minuscules canonique (iss=<issuer-domain>, sans https://, port, chemin d'accès ni caractères majuscules), que les deux points de terminaison .well-known renvoient Content-Type: application/json, que .well-known/email-verification comporte un issuer correspondant à https://<issuer-domain> octet par octet, et que la réponse accounts_endpoint inclut un compte dont l'email correspond à l'adresse saisie.
  • Algorithme de signature non compatible dans .well-known/email-verification: Chrome 154 et 155 nécessitent "EdDSA" dans signing_alg_values_supported, tandis que Chrome 156 et versions ultérieures, ainsi que la spécification IETF, sont compatibles avec "Ed25519". Annoncez les deux ["Ed25519", "EdDSA"] pendant la transition afin que Chrome Stable ne rejette pas vos métadonnées de découverte.

Échec de la validation de la requête d'émission

  • Sec-Fetch-Dest orthographe de l'en-tête : Chrome 154 et versions ultérieures envoient Sec-Fetch-Dest: email-verification (avec un trait d'union), tandis que Chrome 153 envoyait emailverification (sans trait d'union). Acceptez les deux valeurs lors du déploiement.
  • Incompatibilité de la signature de message HTTP (@authority) derrière un proxy : lors de la vérification de la signature RFC 9421, le composant @authority reflète l'hôte public. Si votre serveur se trouve derrière un proxy inverse ou un équilibreur de charge, reconstruisez l'URL de validation à l'aide de X-Forwarded-Host (ou de votre origine publique) plutôt que du nom d'hôte interne, et calculez Content-Digest sur les octets bruts du corps de la requête avant l'analyse JSON.

Le navigateur rejette le issuance_token renvoyé

  • Revendication email modifiée ou canonisée : à partir de Chrome 156, le navigateur vérifie que la revendication email de l'EVT correspond à l'email octet par octet. Si votre backend normalise l'adresse au format de compte canonique (par exemple, en renvoyant First.Last@example.com lorsque first.LAST@example.com a été demandé), Chrome supprime le jeton. Faites correspondre la requête au compte de l'utilisateur, mais renvoyez la chaîne email exacte reçue dans le corps de la requête.
  • Tilde de fin (~) manquant : même avec zéro divulgation, le issuance_token doit être un SD-JWT valide se terminant par un tilde (<Issuer-signed-JWT>~) afin que le navigateur puisse ajouter le <KB-JWT>.
  • Incompatibilité de iss ou cnf.jwk : assurez-vous que la revendication iss de l'EVT correspond à l'origine HTTPS exacte (https://<issuer-domain>, sans barre oblique à la fin) correspondant à vos métadonnées .well-known/email-verification, et que cnf.jwk intègre la clé publique éphémère du navigateur à partir de l'en-tête Signature-Key.