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, diePOST-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: Aufemail-verificationsetzen.- HTTP Message Signatures: Überprüfen Sie die Anfragesignatur mit dem
kurzlebigen öffentlichen Schlüssel in
Signature-Keyund validieren SieContent-Digest. Ab Chrome 156 enthält derSignature-KeyHeaderalg="Ed25519"in seinenhwkParametern. Akzeptieren Sie"Ed25519"und"EdDSA"und lassen Sie zu, dassalgin früheren Chrome-Versionen weggelassen wird. - Nutzlast: Der JSON-Textkörper enthält den
emailString, 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-inHTTP-Header festgelegt odernavigator.login.setStatus("logged-in")aufgerufen wird. - Sitzungscookies blockiert (
SameSite=None): Der Browser ruft Ihrenaccounts_endpointundissuance_endpointvon einer vertrauenden Seite auf einer anderen Website ab. Da es sich um websiteübergreifende Anfragen handelt, muss Ihr SitzungscookieSameSite=None; Secureenthalten. EinSameSite=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>, ohnehttps://, Port, Pfad oder Großbuchstaben), beide.well-known-EndpunkteContent-Type: application/jsonzurückgeben,.well-known/email-verificationeinenissuerhat, der Byte für Byte mithttps://<issuer-domain>übereinstimmt, und dieaccounts_endpoint-Antwort ein Konto enthält, dessenemailmit der eingegebenen Adresse übereinstimmt. - Nicht unterstützter Signaturalgorithmus in
.well-known/email-verification: In Chrome 154 und 155 ist"EdDSA"insigning_alg_values_supportederforderlich, 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-DestRechtschreibung des Headers: Chrome 154 und höher sendenSec-Fetch-Dest: email-verification(mit Bindestrich), während Chrome 153emailverification(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@authorityden öffentlich zugänglichen Host wider. Wenn sich Ihr Server hinter einem Reverse-Proxy oder Load-Balancer befindet, rekonstruieren Sie die Bestätigungs-URL mitX-Forwarded-Host(oder Ihrer öffentlichen Origin) anstelle des internen Hostnamens und berechnen SieContent-Digestfür die Rohbytes des Anfragetextkörpers vor dem JSON-Parsing.
Browser lehnt das zurückgegebene issuance_token ab
- Geänderter oder kanonisierter
emailAnspruch: Ab Chrome 156 prüft der Browser, ob deremailAnspruch des EVT Byte für Byte mit der angefordertenemailübereinstimmt. Wenn Ihr Back-End die Adresse in ein kanonisches Kontoformat normalisiert (z. B.First.Last@example.comzurückgibt, wennfirst.LAST@example.comangefordert wurde), verwirft Chrome das Token. Gleichen Sie die Anfrage mit dem Konto des Nutzers ab, geben Sie aber den genauenemail-String zurück, der im Anfragetextkörper empfangen wurde. - Fehlende nachgestellte Tilde (
~): Auch ohne Offenlegungen muss dasissuance_tokenein gültiges SD-JWT sein, das mit einer nachgestellten Tilde (<Issuer-signed-JWT>~) endet, damit der Browser das<KB-JWT>anhängen kann. - Abweichende
issodercnf.jwk: Achten Sie darauf, dass deriss-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 dasscnf.jwkden kurzlebigen öffentlichen Schlüssel des Browsers aus dem HeaderSignature-Keyeinbettet.