E‑Mail-Bestätigungsprotokoll mit einem Origin-Trial testen

Rowan Merewood

Veröffentlicht am 8. Juli 2026

Wenn Sie im Rahmen einer Registrierung, Anmeldung, eines Abos, einer Kaufabwicklung, einer Kontowiederherstellung oder eines anderen Prozesses eine E‑Mail-Adresse erheben, ist es üblich, zu bestätigen, dass die Person, die sie eingibt, auch Inhaber der E‑Mail-Adresse ist. Bei bestehenden Bestätigungsmethoden wie Einmalpasswörtern oder E‑Mail-Bestätigungslinks (Magic Links) muss der Nutzer Ihre Website verlassen. Dieser störende Prozess kann das Risiko erhöhen, dass der Nutzer, ob Mensch oder Agent, die Sitzung ganz abbricht und den Bestätigungsprozess nie abschließt.

Die Email Verification API ist ein Vorschlag, mit dem der Browser direkt mit dem E‑Mail-Anbieter kommunizieren kann, um zu bestätigen, dass der Nutzer Inhaber der E‑Mail-Adresse ist. Nutzer wählen eine E‑Mail-Adresse aus dem Vorschlag für das automatische Ausfüllen oder die automatische Vervollständigung des Browsers aus, senden das Formular ab und die Website bestätigt die E‑Mail-Adresse beim Anbieter, ohne eine E‑Mail zu senden oder den Ablauf für den Nutzer zu unterbrechen.

E-Mail Verification API – Demo für Nutzeraufforderung
Demo der Nutzeraufforderung der Email Verification API

Die Erhebung von E‑Mail-Adressen ist ein wichtiger Conversion-Punkt im Nutzerprozess. Chrome freut sich über Feedback zu diesem Vorschlag von Websites, die E‑Mail-Adressen bestätigen möchten, von E‑Mail-Anbietern, die die Bestätigung durchführen können, und von Nutzern, die den Prozess durchlaufen. Sie können sich noch heute für den Ursprungstest registrieren und der Implementierungsanleitung hier folgen. Allgemeine Informationen zur Konfiguration von Ursprungstests finden Sie unter Erste Schritte mit Ursprungstests.

Sie können den Ablauf mit einem Demokonto testen:

Ablauf der E‑Mail-Bestätigung

In den folgenden Abschnitten wird erläutert, was Sie und Ihre Nutzer benötigen, um den Ablauf der E‑Mail-Bestätigung zu starten, und wie der gesamte Workflow bei Verwendung des Email Verification Protocol aussieht.

Wichtige Begriffe

Wichtige Begriffe für die Email Verification API:

  • Bestätiger: Die Website, die die E‑Mail-Adresse erhebt und bestätigen möchte sie. Der Bestätiger wird auch als vertrauende Partei bezeichnet.
  • E‑Mail-Anbieter: Der Dienst, der die E‑Mail-Adresse des Nutzers bereitstellt, z. B. gmail.com.
  • Aussteller: Der Dienst, der das Konto für die E‑Mail-Adresse des Nutzers verwaltet, z. B. accounts.google.com. Der Aussteller wird auch als Identitäts Anbieter bezeichnet.

In einigen Fällen können der E‑Mail-Anbieter und der Aussteller von derselben Domain aus agieren. Es ist jedoch wichtig, zwischen einer E‑Mail-Adresse und einer aktiven Sitzung für das zugehörige Konto zu unterscheiden.

Architektur des E-Mail-Bestätigungsprozesses
Architektur des E‑Mail-Bestätigungsablaufs

Vorbereitung

  • Der Nutzer muss im selben Browserprofil beim E‑Mail-Anbieter oder Aussteller angemeldet sein. Wenn er beispielsweise Gmail verwendet, muss er in seinem Google-Konto angemeldet sein.
  • Als teilnehmende Bestätiger-Website müssen Sie sich für den Ursprungstest registrieren und das Token auf derselben Seite wie Ihr E‑Mail-Formular angeben.

  • Der Nutzer muss seine E‑Mail-Adresse aus dem Drop-down-Menü für das automatische Ausfüllen oder die automatische Vervollständigung auswählen.

    • Wenn der Nutzer zuvor eine E‑Mail-Adresse in das Feld eingegeben hat, wird sie über die automatische Vervollständigung angeboten.

    • Wenn der Nutzer seine E‑Mail-Adresse über die Chrome-Einstellungen „Automatische Vervollständigung und Passwörter“ (chrome://settings/autofill) hinzugefügt hat, wird sie über das automatische Ausfüllen angeboten.

  • Wenn ein Nutzer zum ersten Mal eine E‑Mail-Adresse zur Bestätigung angibt, wird er um Erlaubnis gefragt. Dies geschieht nur einmal pro E‑Mail-Adresse.

Sobald der Nutzer diese aktive Sitzung in seinem Browser hat, kann er den Prozess starten:

  1. In einem Formular mit einem E‑Mail-Feld wählt der Nutzer seine E‑Mail-Adresse aus dem Drop-down-Menü für die automatische Vervollständigung aus. Die Bestätiger-Website stellt im Formular ein ausgeblendetes Feld mit einer einmaligen Nonce pro Instanz bereit, um diese Anfrage zu validieren.

  2. Der Browser ruft dann den DNS-Eintrag für die E‑Mail-Bestätigung für die E‑Mail-Domain ab. Dadurch wird der Browser zum Aussteller weitergeleitet. Der Aussteller bestätigt dann, dass er eine aktive Sitzung für diese E‑Mail-Adresse hat.

  3. Der Aussteller stellt dann sein E‑Mail-Bestätigungstoken (Email Verification Token, EVT) für die Adresse bereit. Der Browser kombiniert es zu einem schlüsselgebundenen JWT mit dem EVT, dem Ursprung der Website und der Nonce aus dem Eingabeformular.

  4. Wenn das Formular gesendet wird, wird das EVT-Paket dem ausgeblendeten Feld hinzugefügt und an die Website gesendet.

  5. Die Bestätiger-Website überprüft dann alle diese Details: die erwartete E‑Mail-Adresse, die Nonce und die Signaturen des Browsers und des Ausstellers.

  6. Der Nutzer sieht eine kleine Benachrichtigung, dass sein E‑Mail-Anbieter seine Adresse bestätigt hat.

Durch diesen Prozess erhält die Bestätiger-Website die Bestätigung, dass die E‑Mail-Adresse gültig ist und dem aktuellen Nutzer gehört. Das bedeutet, dass die Website keine Bestätigungs-E‑Mail senden muss.

Nutzer können ihre bestätigten E‑Mail-Adressen unter Einstellungen > Automatische Vervollständigung und Passwörter > Kontaktdaten > Bestätigte E‑Mail-Adresse verwalten oder chrome://settings/contactInfo öffnen.

Überlegungen zu Anwendungsfällen

Die E‑Mail-Bestätigung ist eine progressive Verbesserung Ihres bestehenden Ablaufs, bei der der Nutzer Ihre Website nicht verlassen muss, um ein Einmalpasswort abzurufen oder auf einen Link zu klicken. Websites können die Felder für die E‑Mail-Bestätigung allen relevanten Formularen hinzufügen, z. B. Anmeldungen, Newsletter-Registrierungen, Kontoerstellung und Passwortwiederherstellung. Das Email Verification Protocol wird nur ausgelöst, wenn der Browser es unterstützt. Wenn nach dem Senden kein Code empfangen wird oder einer der Validierungsschritte fehlschlägt, können Sie auf Ihren Standardablauf für die E‑Mail-Bestätigung zurückgreifen. Das bedeutet auch, dass es keine Feature-Erkennung für die API gibt. Die Bestätiger-Website behandelt das EVT als optional und verarbeitet es, wenn es in der Anfrage vorhanden ist.

Die E‑Mail-Bestätigung bestätigt, dass der Nutzer eine aktive Sitzung beim Anbieter seiner E‑Mail-Adresse hat. Es wird nicht bestätigt, dass Ihre E‑Mail den Nutzer erreicht hat. Möglicherweise möchten Sie weiterhin vorhandene Begrüßungs- oder Onboarding-E‑Mails senden und den Nutzer auffordern, seine Spameinstellungen zu überprüfen.

Bestätiger-Website implementieren

Weitere Informationen finden Sie im End-to-End-Democode und in den Validierungsschritten in den Vorschlägen für die E‑Mail-Bestätigung API und das E‑Mail-Bestätigungsprotokoll.

Formularfelder konfigurieren

Achten Sie darauf, dass Ihre Formularfelder die richtigen Attribute haben:

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

Legen Sie die Attribute type und autocomplete der email-Eingabe auf email fest, damit der Browser die automatische Vervollständigung für die E‑Mail-Adresse anbieten kann.

Das neue hidden-Feld wird beim Senden des Formulars mit dem E‑Mail-Bestätigungstoken gefüllt. Die erforderlichen Attribute sind:

  • Legen Sie type="hidden" fest, da für dieses Feld keine Nutzereingabe erforderlich ist.
  • Legen Sie nonce="rAnD0m-VaLuE" fest. Die Website muss eine eindeutige sitzungsgebundene Nonce bereitstellen, um das Senden des Formulars zu bestätigen.
  • Legen Sie autocomplete="email-verification-token" fest. Der Browser verwendet dieses Attribut, um das Feld zu identifizieren, das gefüllt werden soll.

Validieren Sie Ihre Formularelemente, indem Sie das Steuerfeld „Netzwerk“ in den Entwicklertools prüfen. Wenn Sie eine E‑Mail-Adresse auswählen, sehen Sie, dass der Browser die DNS- und nachfolgenden Kontosuchanfragen für den E‑Mail-Anbieter und den Aussteller auslöst. Dies sind interne Browseranfragen. Ihre Website erhält erst nach dem Senden des Formulars etwas.

EVT validieren

Es gibt fünf Schritte, um jede Komponente des EVT-Pakets zu validieren.

  1. Token parsen.
  2. Erwartete Werte validieren.
  3. Schlüsselbindung validieren.
  4. DNS-Eintrag validieren.
  5. Aussteller ermitteln und EVT-Signatur bestätigen.

1. Token parsen

Die Rohdaten aus dem Senden des Formulars enthalten das EVT und signierte Ansprüche in einem JSON Web Token (SD-JWT+KB) mit selektiver Offenlegung, getrennt durch eine Tilde (~ ). Sie müssen diese trennen und die JOSE-Header (JavaScript Object Signing and Encryption) und -Nutzlasten decodieren, z. B. mit jose für Node.js.

Wenn example.com die Adresse demo@gmail.com bestätigt, sieht die decodierte Nutzlast in etwa so aus:

{
  "evtJwtDecodedPayload": {
    "cnf": {
      "jwk": {
        "crv": "Ed25519",
        "kty": "OKP",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@gmail.com",
    "email_verified": true,
    "iat": 1782911685,
    "iss": "https://accounts.google.com"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://example.com",
    "iat": 1782911685,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  }
}

2. Erwartete Werte validieren

Prüfen Sie, ob die grundlegenden Werte in der Nutzlast mit Ihren angegebenen Werten übereinstimmen:

  • Prüfen Sie, ob email_verified auf true gesetzt ist.
  • Prüfen Sie, ob email mit der im Formular angegebenen E‑Mail-Adresse übereinstimmt.
  • Prüfen Sie, ob nonce mit der im Formular angegebenen Nonce übereinstimmt.
  • Prüfen Sie, ob aud mit dem Ursprung Ihrer Website übereinstimmt.
  • Prüfen Sie, ob iat einen relativ aktuellen Zeitstempel hat, z. B. nachdem das Formular gerendert wurde.

3. Schlüsselbindung validieren

Der Browser erstellt einen temporären, kurzlebigen Schlüssel für die Transaktion, um zu bestätigen, dass er das Token signiert hat. Extrahieren Sie diesen Schlüssel aus dem Anspruch cnf (Bestätigung) im EVT und verwenden Sie ihn dann, um das schlüsselgebundene JWT zu bestätigen.

Berechnen Sie dann den erwarteten Hash und vergleichen Sie ihn mit dem Anspruch sd_hash. Das folgende Node.js-Beispiel zeigt, wie diese Berechnung durchgeführt wird:

const calculatedHash = createHash("sha256")
        .update(evtJwt + "~")
        .digest("base64url");

4. DNS-Eintrag validieren

Bestätigen Sie den DNS-Eintrag _email-verification für die Domain der E‑Mail-Adresse. 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 an, also accounts.google.com.

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

5. Aussteller ermitteln und EVT-Signatur bestätigen

Achten Sie darauf, dass der Aussteller die Ressource /.well-known/email-verification bereitstellt, die die Endpunkte für die Ausstellung des Tokens, den JSON Web Key (JWK) für die Website und die unterstützten Signaturalgorithmen enthält.

$ curl https://accounts.google.com/.well-known/email-verification
{
  "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": ["EdDSA"]
}

Verwenden Sie die JWKs, um das EVT-JWT zu bestätigen, das Sie aus dem Token extrahiert haben. Die meisten JOSE-Bibliotheken bieten Funktionen zur Verarbeitung dieser Bestätigung.

Wenn alle fünf Schritte erfolgreich sind, haben Sie die E‑Mail-Adresse beim Anbieter bestätigt. Andernfalls senden Sie dem Nutzer wie gewohnt eine Bestätigungs-E‑Mail.

E‑Mail-Anbieter- und Ausstellerservice implementieren

Weitere Informationen finden Sie im Democode für den fiktiven E‑Mail-Anbieter und in den Schritten für den Aussteller in den Vorschlägen für die Email Verification API und das Email Verification Protocol.

Als Aussteller müssen Sie sich nicht für den Ursprungstest registrieren oder ein Token bereitstellen, da das Browserverhalten von der Website der vertrauenden Partei ausgelöst wird. Sie müssen nur dafür sorgen, dass die erwarteten Endpunkte vorhanden sind, um auf diese Anfragen zu 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-Delegierungseintrag konfigurieren

Konfigurieren Sie einen DNS-TXT-Eintrag in Ihrer E‑Mail-Domain, der die Bestätigungsautorität an Ihre Aussteller-ID delegiert. Je nach 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"

.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:

{
  "issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
  "jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["EdDSA", "ES256"]
}

.well-known/web-identity-Endpunkt hosten

Eine zusätzliche .well-known JSON-Ressource, die Sie möglicherweise bereits im Rahmen der Federated Credentials API (FedCM) implementiert haben. Sie enthält Links zu Ihrem Kontoendpunkt und Ihrer Anmelde-URL.

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

Beispielantwort:

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

Kontoendpunkt verwenden

Der Kontoendpunkt der FedCM API enthält eine Liste der derzeit 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 beim Anbieter haben und Sie müssen dies dem Browser mit der Login Status API signalisieren.

Wenn sich ein Nutzer erfolgreich anmeldet 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/x-www-form-urlencoded-POST-Anfrage, die das request_token enthält.

In den folgenden Abschnitten wird der vollständige Prozess der Verarbeitung von Ausstellungsanfragen beschrieben.

1. Ausstellungsanfrage validieren

Eingehende Browsernutzlasten parsen und validieren:

  • Methode:POST
  • Sitzungsbestätigung:Bestätigen Sie die Erstanbieter-session/authentication-Cookies des Nutzers, die zusammen mit der Anfrage übertragen werden, um sicherzustellen, dass ein aktiver, autorisierter Identitätskontext vorhanden ist.
  • Parameterbestätigung:Extrahieren Sie den Parameter request_token (ein vom Browser generiertes signiertes JWT). Prüfen Sie, ob er den erwarteten kurzlebigen öffentlichen Schlüssel, die Ziel-E‑Mail-Adresse, die richtige Zielgruppe und einen gültigen Zeitstempel enthält.

Das decodierte Token sollte in etwa so aussehen:

{
  "decodedHeader": {
    "alg": "ES256",
    "typ": "JWT",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "decodedPayload": {
    "iss": "https://accounts.issuer.example",
    "sub": "demo@example.com",
    "email": "demo@example.com",
    "iat": 1780272000,
    "exp": 1780272300
  },
  "signature": "SIGnatURE-123_SIGnatURE-123_SIGnatURE-123"
}

2. Mit einem Token antworten

Nach erfolgreicher Bestätigung der Sitzung und des Anfragetokens generieren Sie mit der Nutzlast ein signiertes JWT mit selektiver Offenlegung (SD-JWT):

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

Signieren Sie die Nutzlast mit Ihrem privaten Schlüssel und dem unterstützten Algorithmus. Beispiel mit jose in Node.js:

const evtJwt = await new SignJWT(evtPayload)
   .setProtectedHeader({
     alg: "EdDSA",
     kid: PRIVATE_KEY_JWK.kid, // Key ID corresponding to our JWKS keys
     typ: "evt+jwt", // Standard Token Type for EVTs
   })
   .sign(privateKey);

 // Standard SD-JWT compatibility requires appending a trailing tilde "~"
 // to separate the signed token from the key binding section.
 const issuanceToken = `${evtJwt}~`;

Beispiel für eine Erfolgsantwort (HTTP 200):

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

Überlegungen zu Ursprungstests

Ursprungstests sind Experimente, um Feedback zu erhalten. Ihr Beitrag ist daher wichtig, wenn Sie als vertrauende Partei oder Identitätsanbieter teilnehmen. Verwenden Sie die folgenden GitHub-Repositories, um Probleme zu melden:

Wenn Sie Fehler in der Chrome-Implementierung finden, melden Sie sie für die Komponente:

Die Aktivierung der Ursprungstestfunktion wird pro Antwort durch die Einbeziehung des Ursprungstesttokens gesteuert. Das bedeutet, dass Sie die Funktion genau steuern können, wenn Sie sie auf einen Teil Ihrer Nutzer beschränken möchten. Wenn Sie beispielsweise bereits ein A/B-Test-Framework haben, können Sie den Ursprungstest dort für eine kontrollierte Testgruppe einbinden. Alternativ können Sie die Funktion für eine Betatest- oder Early-Access-Gruppe von Nutzern aktivieren. In diesem Fall prüfen Sie die angegebene E‑Mail-Adresse, bevor Sie das Token ausstellen oder bestätigen.

Für Ursprungstests gelten auch Traffic-Limits, um zu verhindern, dass Websites vor der Einführung zu stark auf die Funktion angewiesen sind. Die Aussteller-API wird derzeit entwickelt. Sie sollten mit abwärtsinkompatiblen Änderungen und Updates der Chrome-Benutzeroberfläche rechnen.

Wir werden weitere Updates im Blog und auf der evp-announce@chromium.org veröffentlichen, sobald die Entwicklung voranschreitet.