Implementierung durch den E‑Mail-Anbieter (Aussteller)

Weitere Informationen finden Sie im Democode für den Mock-E-Mail-Anbieter und in den Schritten für den Aussteller in den Vorschlägen für die E‑Mail-Bestätigung API und das E‑Mail-Bestätigung Protokoll.

Als Aussteller müssen Sie sich nicht für den Ursprungstest registrieren oder ein Token angeben, da die Website der vertrauenden Seite das Browserverhalten auslöst. Achten Sie darauf, dass Ihre Endpunkte so konfiguriert sind, dass sie auf diese Anfragen antworten.

Ausstellererkennung konfigurieren

Damit Browser Ihre Bestätigungsendpunkte automatisch erkennen können, wenn eine E-Mail-Adresse ausgewählt wird, die zu Ihrer Domain gehört, müssen Sie Ihre Konfiguration über DNS und einen .well-known-HTTP-Endpunkt verfügbar machen.

DNS-Delegatdatensatz konfigurieren

Konfigurieren Sie einen DNS-TXT-Eintrag in Ihrer E-Mail-Domain, der die Bestätigungsautorität an Ihre Aussteller-ID delegiert. Je nach Ihrer Infrastruktur können diese IDs dieselbe Domain verwenden.

Eintragsformat: _email-verification.<email-domain>

Beispiel für eine Zonendatei:

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

Der iss= Wert muss ein einfacher, kanonischer Hostname in Kleinbuchstaben sein (z. B. iss=accounts.issuer.example) ohne Schema (https://), Port, Pfad oder Großbuchstaben. Chrome lehnt Einträge ab, die keine Hostname-Komponenten enthalten.

.well-known/email-verification-Endpunkt hosten

Hosten Sie eine JSON-Metadatendatei in Ihrer Ausstellerdomain unter dem Pfad /.well-known/. In dieser Datei werden Ihre Ausstellungsfunktionen und die kryptografischen Signaturalgorithmen beschrieben, die von Ihrer Infrastruktur unterstützt werden.

Endpunkt: https://<issuer-domain>/.well-known/email-verification

Beispielantwort:

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

Metadateneigenschaften:

  • issuer: Ihre Aussteller-Origin (https://<issuer-domain>, ohne nachgestellten Schrägstrich). Muss Byte für Byte mit der Origin übereinstimmen, von der die Metadatendatei bereitgestellt wird.
  • issuance_endpoint: Die HTTPS-URL, die POST-Anfragen zur Tokenausstellung empfängt.
  • jwks_uri: Die HTTPS-URL, die Ihr öffentliches JSON Web Key Set (JWKS) bereitstellt.
  • signing_alg_values_supported: Array der unterstützten JWS-Signaturalgorithmen.

.well-known/web-identity-Endpunkt hosten

Möglicherweise haben Sie bereits eine zusätzliche .well-known JSON-Ressource im Rahmen der Federated Credentials (FedCM) API implementiert. Diese Ressource enthält Links zu Ihrem Kontenendpunkt und Ihrer Log-in-URL.

Endpunkt: https://<domain>/.well-known/web-identity

Beispielantwort:

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

Kontenendpunkt verwenden

Der Kontenendpunkt der FedCM API enthält derzeit eine Liste der angemeldeten Konten. Das folgende Beispiel zeigt eine minimale Antwort. Weitere Informationen finden Sie im Implementierungsleitfaden für Identitätsanbieter.

Endpunkt: wie in .well-known/web-identity angegeben

Hier ist ein Beispiel für eine Antwort:

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

In die Login Status API einbinden

Der Nutzer muss eine aktive Sitzung mit dem Anbieter haben und Sie müssen dies dem Browser mithilfe der Login Status API signalisieren.

Wenn sich ein Nutzer erfolgreich an- oder abmeldet, stellen Sie den entsprechenden HTTP-Antwortheader bereit:

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

Alternativ können Sie den Status mit JavaScript im Kontext Ihrer Webanwendung aktualisieren:

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

Ausstellungsanfragen verarbeiten

Ihr issuance_endpoint empfängt eine application/json POST Anfrage, die den Schlüssel email und HTTP Message Signatures Header für Signature, Signature-Input und Signature-Key enthält.

Verwenden Sie eine Bibliothek, die strukturierte Header und HTTP Message Signatures für Ihre Umgebung unterstützt. In Node.js können Sie structured-headers und http-message-sig verwenden.

Vollständiges Anfrageformat:

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

Anfrage parsen und validieren:

  • Sitzungsauthentifizierung: Validieren Sie Ihre eigenen Sitzungscookies, die mit der Anfrage gesendet wurden. Der Nutzer muss authentifiziert sein.
  • Sec-Fetch-Dest-Header: Auf email-verification setzen.
  • HTTP Message Signatures: Überprüfen Sie die Anfragesignatur mit dem kurzlebigen öffentlichen Schlüssel in Signature-Key und validieren Sie Content-Digest. Ab Chrome 156 enthält der Signature-Key Header alg="Ed25519" in seinen hwk Parametern. Akzeptieren Sie "Ed25519" und "EdDSA" und lassen Sie zu, dass alg in früheren Chrome-Versionen weggelassen wird.
  • Nutzlast: Der JSON-Textkörper enthält den email String, der zur Bestätigung angefordert wurde.

Ausstellungsantwort

Generieren Sie nach erfolgreicher Validierung des Sitzungs- und Anfragetokens ein signiertes SD-JWT (Selective Disclosure JWT), das als JSON zurückgegeben wird. Verwenden Sie dazu die entsprechenden Bibliotheken für Ihre Plattform. Für Node können Sie beispielsweise @sd-jwt/core und jose verwenden.

Das Rohformat der Nutzlast sollte so aussehen:

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

Token erstellen, signieren und zurückgeben:

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

Der resultierende Antworttext sieht etwa so aus:

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

Nachdem Sie das E-Mail-Bestätigungstoken erstellt und signiert haben, übergibt der Browser es zur Validierung an die Website des Bestätigers.

Fehlerbehebung

Wenn der Browser Ihre Endpunkte nicht kontaktiert oder ausgestellte Token ablehnt, prüfen Sie die folgenden häufigen Probleme:

Browser ruft accounts_endpoint oder issuance_endpoint nie auf

  • Anmeldestatus nicht festgelegt: Chrome fragt Ihre Endpunkte nur ab, wenn der Nutzer angemeldet ist. Achten Sie darauf, dass in Ihrem Anmeldeablauf der Set-Login: logged-in HTTP-Header festgelegt oder navigator.login.setStatus("logged-in") aufgerufen wird.
  • Sitzungscookies blockiert (SameSite=None): Der Browser ruft Ihren accounts_endpoint und issuance_endpoint von einer vertrauenden Seite auf einer anderen Website ab. Da es sich um websiteübergreifende Anfragen handelt, muss Ihr Sitzungscookie SameSite=None; Secure enthalten. Ein SameSite=Lax-Cookie funktioniert beim Testen auf einem Bestätiger derselben Website, wird aber bei websiteübergreifenden Anfragen weggelassen.
  • Erkennungs- oder Kontoabweichung: Prüfen Sie, ob _email-verification.<email-domain> einen einzelnen TXT-Eintrag mit einem kanonischen Hostnamen in Kleinbuchstaben zurückgibt (iss=<issuer-domain>, ohne https://, Port, Pfad oder Großbuchstaben), beide .well-known-Endpunkte Content-Type: application/json zurückgeben, .well-known/email-verification einen issuer hat, der Byte für Byte mit https://<issuer-domain> übereinstimmt, und die accounts_endpoint-Antwort ein Konto enthält, dessen email mit der eingegebenen Adresse übereinstimmt.
  • Nicht unterstützter Signaturalgorithmus in .well-known/email-verification: In Chrome 154 und 155 ist "EdDSA" in signing_alg_values_supported erforderlich, während Chrome 156 und höher sowie die IETF-Spezifikation "Ed25519" unterstützen. Geben Sie während der Umstellung sowohl ["Ed25519", "EdDSA"] an, damit Chrome Stable Ihre Erkennungsmetadaten nicht ablehnt.

Validierung der Ausstellungsanfrage fehlgeschlagen

  • Sec-Fetch-Dest Rechtschreibung des Headers: Chrome 154 und höher senden Sec-Fetch-Dest: email-verification (mit Bindestrich), während Chrome 153 emailverification (ohne Bindestrich) gesendet hat. Akzeptieren Sie während des Roll-outs beide Werte.
  • Abweichung der HTTP Message Signature (@authority) hinter einem Proxy: Beim Überprüfen der RFC 9421-Signatur spiegelt die Komponente @authority den öffentlich zugänglichen Host wider. Wenn sich Ihr Server hinter einem Reverse-Proxy oder Load-Balancer befindet, rekonstruieren Sie die Bestätigungs-URL mit X-Forwarded-Host (oder Ihrer öffentlichen Origin) anstelle des internen Hostnamens und berechnen Sie Content-Digest für die Rohbytes des Anfragetextkörpers vor dem JSON-Parsing.

Browser lehnt das zurückgegebene issuance_token ab

  • Geänderter oder kanonisierter email Anspruch: Ab Chrome 156 prüft der Browser, ob der email Anspruch des EVT Byte für Byte mit der angeforderten email übereinstimmt. Wenn Ihr Back-End die Adresse in ein kanonisches Kontoformat normalisiert (z. B. First.Last@example.com zurückgibt, wenn first.LAST@example.com angefordert wurde), verwirft Chrome das Token. Gleichen Sie die Anfrage mit dem Konto des Nutzers ab, geben Sie aber den genauen email-String zurück, der im Anfragetextkörper empfangen wurde.
  • Fehlende nachgestellte Tilde (~): Auch ohne Offenlegungen muss das issuance_token ein gültiges SD-JWT sein, das mit einer nachgestellten Tilde (<Issuer-signed-JWT>~) endet, damit der Browser das <KB-JWT> anhängen kann.
  • Abweichende iss oder cnf.jwk: Achten Sie darauf, dass der iss-Anspruch des EVT die genaue HTTPS-Origin (https://<issuer-domain> ohne nachgestellten Schrägstrich) ist, die mit Ihren .well-known/email-verification-Metadaten übereinstimmt, und dass cnf.jwk den kurzlebigen öffentlichen Schlüssel des Browsers aus dem Header Signature-Key einbettet.