Implementierung der vertrauenden Partei

Wenn Sie die E‑Mail-Bestätigung auf Ihrer Website implementieren möchten, aktualisieren Sie das Formular-Markup, um das Token anzufordern, und fügen Sie die serverseitige Validierung für eingehende Tokens hinzu.

Für den Ursprungstest registrieren

Auf Websites, die überprüft werden sollen, muss der Ursprungstest konfiguriert sein.

Ab Chrome 154 werden Ursprungstests von Drittanbietern mit einer wichtigen Einschränkung unterstützt: Der registrierte Ursprung für den Test muss für den Aussteller derselbe sein. Beispiel:

  • Ausstellerdomain: issuer.example
  • Registrierter für den Ursprungstest: https://issuer.example
  • JavaScript-Ursprung: https://issuer.example (oder https://app.issuer.example mit Subdomain-Abgleich)

Formularfelder konfigurieren

Fügen Sie Ihrem Formular für die E‑Mail-Einreichung ein ausgeblendetes Tokenfeld hinzu:

<input
  type="email"
  name="email-address"
  autocomplete="email">
<input
  type="hidden"
  name="token"
  autocomplete="email-verification-token"
  nonce="rAnD0m-VaLuE">

Feldanforderungen:

  • E‑Mail-Feld: Legen Sie type="email" und autocomplete="email" fest, damit Chrome die Adresse automatisch ausfüllen und erkennen kann.
  • Attribute des Tokenfelds:
    • Legen Sie autocomplete="email-verification-token" fest: Chrome erkennt dieses Feld, um das Token bei der Einreichung einzufügen.
    • Legen Sie nonce="<VALUE>" fest: Die Website muss eine eindeutige sitzungsgebundene Nonce bereitstellen, um die Formulareinreichung zu bestätigen.

E‑Mail-Bestätigungstoken (EVT) validieren

Wenn der Nutzer das Formular einreicht, erhält Ihr Server die E‑Mail-Adresse und das Token aus dem ausgeblendeten Feld. Ein leeres Tokenfeld bedeutet, dass der Browser oder Anbieter EVP nicht unterstützt oder der Nutzer die Bestätigung übersprungen hat. In diesem Fall sollten Sie auf Ihr vorhandenes Bestätigungsverfahren zurückgreifen, z. B. das Senden eines Einmalpassworts oder eines Magic Link.

Wenn ein Token vorhanden ist, validieren Sie es so:

  1. Analysieren Sie das Token mit einer SD-JWT-Bibliothek.
  2. Validieren Sie die erwarteten Werte und Sitzungsansprüche.
  3. Überprüfen Sie die DNS-Delegierung.
  4. Suchen Sie nach Metadaten des Ausstellers und rufen Sie JWKS ab.
  5. Überprüfen Sie kryptografische Signaturen und die Schlüsselbindung.

1. Token analysieren

Das Token verwendet das Format RFC 9901: Selective Disclosure JWT (SD-JWT+KB). Verwenden Sie die entsprechenden Bibliotheken für Ihre Plattform, um das Token zu analysieren und zu validieren. Für Node können Sie beispielsweise @sd-jwt/core und jose verwenden. In der Rohform sieht das so aus: ein vom Aussteller signiertes JWT, gefolgt von null oder mehr Offenlegungen und einem Key Binding JWT. Die einzelnen Komponenten sind durch eine Tilde getrennt:

<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

In der aktuellen Implementierung enthält das Token keine Offenlegungen (<Issuer-signed EVT>~<Key Binding JWT>). Das kann sich in Zukunft jedoch ändern.

Decodieren Sie das Token mit der Bibliothek:

import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;

Wenn verifier.example demo@provider.example bestätigt, sieht das decodierte Token so aus:

{
  "evtJwtDecodedHeader": {
    "typ": "evt+jwt",
    "alg": "EdDSA",
    "kid": "issuer-key-id"
  },
  "evtJwtDecodedPayload": {
    "iss": "https://provider.example",
    "iat": 12345678901,
    "exp": 12345679901,
    "cnf": {
      "jwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@provider.example",
    "email_verified": true
  },
  "kbJwtDecodedHeader": {
    "alg": "EdDSA",
    "typ": "kb+jwt"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://verifier.example",
    "iat": 12345678901,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  },
  "disclosures": []
}

2. Erwartete Werte und Sitzungsansprüche validieren

Prüfen Sie, ob die grundlegenden Werte in der Nutzlast mit den von Ihnen angegebenen und erwarteten Werten übereinstimmen:

  • email_verified: Muss true sein.
  • email: Muss mit der im Formular eingereichten E‑Mail-Adresse übereinstimmen.
  • aud (Zielgruppe): Muss mit dem Ursprung Ihrer Website übereinstimmen.
  • nonce: Muss mit der in Ihrem Formular angegebenen Nonce übereinstimmen.
  • iat (ausgestellt am) und exp (Ablaufdatum): Prüfen Sie, ob das Token innerhalb des gültigen Zeitraums liegt und nicht abgelaufen ist.

3. DNS-Delegierung überprüfen

Überprüfen Sie den DNS-Eintrag _email-verification für die E‑Mail-Adressdomain. Für demo@gmail.com fragen Sie beispielsweise den TXT-Eintrag _email-verification.gmail.com ab. Für diesen Anbieter gibt die Abfrage den Standort des Kontos zurück, also accounts.google.com.

$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"

Prüfen Sie, ob das Ausstellerschema https:// ist und ob https://<domain> mit dem iss Anspruch im EVT übereinstimmt.

4. EVT-Signatur überprüfen

Rufen Sie die Metadaten des Ausstellers unter https://<issuer>/.well-known/email-verification ab:

{
  "issuer": "https://accounts.google.com",
  "issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
  "jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["Ed25519", "EdDSA"]
}

Wenn die Metadaten ein Feld issuer enthalten, prüfen Sie, ob es bytegenau mit dem iss Anspruch im EVT übereinstimmt. Rufen Sie das JSON Web Key Set unter jwks_uri ab.

Verwenden Sie Ihre SD-JWT-Bibliothek, um das Tokenpaket zu überprüfen. Die Bibliothek koordiniert die Validierung:

  1. Die Signatur des Ausstellers im EVT wird mit dem abgerufenen JWKS validiert.
  2. Die Signatur des Browsers im KB-JWT wird mit dem kurzlebigen öffentlichen Schlüssel in cnf.jwk validiert.
  3. Die Schlüsselbindung (aud, nonce und der Digest-Hash sd_hash) wird überprüft.

Beispiel für die Bestätigungslogik in Node.js:

import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
  throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
  hasher,
  // Verifier for the Issuer-signed EVT
  verifier: async (data, sig) => {
    const token = `${data}.${sig}`;
    const header = decoded.jwt.header;
    // Match by kid if present, or iterate across matching algorithm keys
    const keysToTry = header.kid
      ? jwksData.keys.filter(k => k.kid === header.kid)
      : jwksData.keys;
    for (const jwk of keysToTry) {
      try {
        const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
        await compactVerify(token, pubKey);
        return true;
      } catch {
        // Try next candidate key
      }
    }
    return false;
  },
  // Verifier for the Key Binding JWT (KB-JWT)
  kbVerifier: async (data, sig) => {
    try {
      const browserJwkKey = evtPayload.cnf?.jwk;
      if (!browserJwkKey) return false;
      const pubKey = await importJWK(browserJwkKey, kbAlg);
      await compactVerify(`${data}.${sig}`, pubKey);
      return true;
    } catch {
      return false;
    }
  },
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
  kb: {
    expectedNonce: sessionNonce,
    expectedAudience: "https://example.com",
    required: true,
  },
});
const verifiedPayload = result.payload;
if (
  verifiedPayload.email_verified !== true ||
  verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
  throw new Error("Token email does not match submitted email");
}

Wenn alle Schritte erfolgreich sind, haben Sie die E‑Mail-Adresse beim Anbieter bestätigt. Wenn die Bestätigung fehlschlägt, senden Sie dem Nutzer über Ihren normalen Ablauf eine Bestätigungs-E‑Mail.

Fehlerbehebung

Wenn die Bestätigung fehlschlägt oder der Browser kein Token bereitstellt, prüfen Sie die folgenden häufigen Probleme:

Tokenfeld bei der Einreichung leer

  • Registrierung für den Ursprungstest: Prüfen Sie, ob der Origin-Trial Header oder das <meta> Tag auf der Seite bereitgestellt wird und ob das Token nicht abgelaufen ist. Tokens, die vor der Verlängerung für Chrome 160 generiert wurden, laufen am 17. November 2026 ab. Bei Ursprungstests von Drittanbietern (Chrome 154 und höher) muss der registrierte Ursprung des Tests für den Aussteller derselbe sein (https://<issuer-domain>). Sie können den Status des Ursprungstests und das Ablaufdatum des Tokens auf einer Website in den Entwicklertools unter Anwendung > Frames > (entsprechenden Frame auswählen) > Ursprungstests prüfen.
  • Formular-Markup: Sowohl <input type="email" autocomplete="email"> als auch <input type="hidden" autocomplete="email-verification-token" nonce="..."> müssen sich im selben <form>-Element befinden (nicht isoliert über Shadow DOM -Grenzen hinweg) und nonce darf nicht leer sein.
  • Frühe Einreichung oder wiederverwendete Seite: Der Browser ruft das Token im Hintergrund ab, nachdem die E‑Mail-Adresse eingegeben oder automatisch ausgefüllt wurde. Wenn Sie das Formular einreichen, bevor die Anfrage abgeschlossen ist, bleibt das Token leer. Das kann passieren, wenn der Nutzer nach der Eingabe seiner E‑Mail-Adresse die Eingabetaste drückt, um das Formular einzureichen.
  • Voraussetzungen für Browser und Anbieter: Der Nutzer muss im selben Browserprofil bei einem teilnehmenden Anbieter angemeldet sein und in den Chrome-Einstellungen (chrome://settings/contactInfo) die Option Bestätigte E‑Mail-Adresse aktiviert haben.

Überprüfung der Ausstellersignatur schlägt fehl

  • Fehlender kid -Header: Der Anspruch kid (Schlüssel-ID) im EVT-Header und JWKS ist optional (z. B. wird kid in Gmail ausgelassen). Wenn kid fehlt, durchlaufen Sie alle Kandidatenschlüssel in der jwks_uri des Ausstellers, anstatt bei der Suche nach der Schlüssel-ID einen Fehler zu verursachen.
  • Algorithmuskennungen (Ed25519 und EdDSA): Ab Chrome 156 verwendet Chrome die vollständig angegebene Algorithmuskennung Ed25519 (RFC 9864) für cnf.jwk- und KB-JWT-Header, während Aussteller und Bibliotheken entweder Ed25519 oder EdDSA (zusammen mit ES256) angeben können. Achten Sie darauf, dass Ihre JWK-Import- und Bestätigungslogik beide Kennungen akzeptiert.
  • Format des Ausstellerursprungs (iss): Der DNS-TXT-Eintrag (_email-verification.<domain>) enthält einen einfachen Hostnamen (iss=accounts.issuer.example), während der EVT-iss-Anspruch ein vollständiger HTTPS- -Ursprung ist (https://accounts.issuer.example, ohne nachgestellten Schrägstrich). Fügen Sie dem DNS-Eintrag vor dem Vergleich https:// voran.

Validierung der Schlüsselbindung (KB-JWT) schlägt fehl

  • Nicht übereinstimmende oder abgelaufene Nonce: Prüfen Sie, ob die nonce in der <input> mit der aktiven Sitzungs-Nonce auf Ihrem Server übereinstimmt und nicht durch einen anderen Tab überschrieben oder durch eine vorherige Anfrage verwendet wurde.
  • Nicht übereinstimmende Zielgruppe (aud): Der Anspruch aud ist der HTTPS-Ursprung des Bestätigers (https://verifier.example ohne Pfad oder nachgestellten Schrägstrich).

Vergleich des E‑Mail-Anspruchs (email) schlägt fehl

  • Groß-/Kleinschreibung und Kanonisierung: In Chrome 156 und höher wird der Anspruch email bytegenau so zurückgegeben, wie er im Formular eingegeben wurde. In früheren Browserversionen oder bei Anbietern kann jedoch eine kanonisierte Adresse zurückgegeben werden (z. B. First.Last@example.com für first.last@example.com). Verwenden Sie beim Abgleich des email-Anspruchs des Tokens mit dem eingereichten Formularwert einen Vergleich ohne Berücksichtigung der Groß-/Kleinschreibung.