Voor meer informatie kunt u de democode van de e-mailprovider doorlopen en de stappen voor de uitgever raadplegen in de voorstellen voor de API voor e-mailverificatie en het Protocol voor e-mailverificatie.
Als uitgever hoeft u zich niet aan te melden voor de origin trial of een token te verstrekken, omdat de site van de vertrouwende partij het browsergedrag activeert. Zorg dat uw eindpunten zijn ingesteld om op die verzoeken te reageren.
Uitgeverdetectie instellen
Als u wilt dat browsers uw verificatie-eindpunten automatisch kunnen vinden als er een e-mailadres wordt geselecteerd dat bij uw domein hoort, stelt u uw configuratie beschikbaar via DNS en een .well-known-HTTP-eindpunt.
DNS-delegeringsrecord instellen
Stel een DNS TXT-record in voor uw e-maildomein dat de verificatiebevoegdheid delegeert aan uw uitgevers-ID. Deze ID's kunnen hetzelfde domein gebruiken, afhankelijk van uw infrastructuur.
Recordindeling: _email-verification.<email-domain>
Voorbeeld van zonebestand:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
De iss= waarde moet een kale, canonieke hostnaam in kleine letters zijn (bijvoorbeeld,
iss=accounts.issuer.example) zonder schema (https://), poort, pad of
hoofdletters. Chrome wijst records af die geen hostnaamcomponenten bevatten.
Een .well-known/email-verification-eindpunt hosten
Host een json-bestand met metadata in uw uitgeversdomein onder het pad /.well-known/.
In dit bestand staan uw uitgiftefunctionaliteit en de cryptografische ondertekeningsalgoritmen die uw infrastructuur ondersteunt.
Eindpunt: https://<issuer-domain>/.well-known/email-verification
Voorbeeldreactie:
{
"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"]
}
Eigenschappen van metadata:
issuer: Uw uitgeversoorsprong (https://<issuer-domain>, zonder afsluitende slash). Moet byte voor byte overeenkomen met de oorsprong van waaruit het metadatabestand wordt geleverd.issuance_endpoint: De HTTPS-URL diePOST-verzoeken voor tokenuitgifte ontvangt.jwks_uri: De HTTPS-URL die uw openbare JSON Web Key Set (JWKS) levert.signing_alg_values_supported: Array met ondersteunde JWS-ondertekeningsalgoritmen.
Een .well-known/web-identity-eindpunt hosten
U heeft misschien al een extra .well-known JSON-bron geïmplementeerd als
onderdeel van de API voor Federated Credentials (FedCM). Deze bron biedt links naar uw accountseindpunt en inlog-URL.
Eindpunt: https://<domain>/.well-known/web-identity
Voorbeeldreactie:
{
"accounts_endpoint": "https://accounts.issuer.example/accounts",
"login_url": "https://accounts.issuer.example/login"
}
Een accountseindpunt gebruiken
Het accountseindpunt van de FedCM API biedt op dit moment een lijst met ingelogde accounts. Het volgende voorbeeld toont een minimale reactie. Ga naar de implementatiehandleiding voor identiteitsproviders voor meer informatie.
Eindpunt: zoals vermeld in .well-known/web-identity
Hieronder staat een voorbeeld van een reactie:
{
"accounts": [
{
"id": "demo-example",
"name": "Demo User",
"email": "demo@example.com",
"given_name": "Demo"
}
]
}
Integreren met de API voor inlogstatus
De gebruiker moet een actieve sessie hebben bij de provider en u moet dat aan de browser doorgeven via de API voor inlogstatus.
Als een gebruiker succesvol in- of uitlogt, levert u de overeenkomende HTTP-reactieheader:
Set-Login: logged-in
Set-Login: logged-out
U kunt de status ook updaten met JavaScript in de context van uw web-app:
navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");
Verzoeken voor uitgifte verwerken
Uw issuance_endpoint ontvangt een application/json POST verzoek dat
de sleutel email en HTTP-berichten
handtekeningheaders voor Signature,
Signature-Input en Signature-Key bevat.
Gebruik een bibliotheek die gestructureerde headers en HTTP-berichtenhandtekeningen ondersteunt voor uw omgeving. In Node.js kunt u
structured-headers en
http-message-sig gebruiken.
Volledige verzoeksindeling:
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"}
Parse en valideer het verzoek:
- Sessie-authenticatie: Valideer uw first-party sessiecookies die met het verzoek zijn meegestuurd. De gebruiker moet worden geverifieerd.
Sec-Fetch-Dest-header: Stel in opemail-verification.- HTTP-berichtenhandtekeningen: Verifieer de verzoekhandtekening met de
tijdelijke openbare sleutel in
Signature-Keyen valideer deContent-Digest. Vanaf Chrome 156 bevat deSignature-Keyheaderalg="Ed25519"in dehwkparameters. Accepteer"Ed25519"en"EdDSA"en sta toe datalgwordt weggelaten door eerdere Chrome-versies. - Payload: De json-body bevat de
emailtekenreeks die voor verificatie is aangevraagd.
Reactie op uitgifte
Nadat de sessie en het verzoektoken zijn gevalideerd, maakt u een ondertekende Selective Disclosure JWT (SD-JWT) die als json wordt geretourneerd met de juiste bibliotheken voor uw platform. Voor Node kunt u bijvoorbeeld
@sd-jwt/core en
jose gebruiken.
De indeling van de onbewerkte payload moet er ongeveer zo uitzien:
{
"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
}
Maak, onderteken en retourneer het token:
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);
De resulterende reactiebody ziet er ongeveer zo uit:
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
Nadat u het token voor e-mailverificatie heeft gemaakt en ondertekend, geeft de browser dit door aan de verifieringssite voor validatie.
Problemen oplossen
Als de browser geen contact opneemt met uw eindpunten of uitgegeven tokens afwijst, controleert u de volgende veelvoorkomende problemen:
De browser roept accounts_endpoint of issuance_endpoint nooit aan
- Inlogstatus niet ingesteld: Chrome vraagt uw eindpunten alleen op als de browser weet dat de
gebruiker is ingelogd. Zorg dat uw inlogproces de
Set-Login: logged-inHTTP-header instelt ofnavigator.login.setStatus("logged-in")aanroept. - Sessiecookies geblokkeerd (
SameSite=None): De browser haalt uwaccounts_endpointenissuance_endpointop van een vertrouwende partij op een andere site. Omdat dit cross-site verzoeken zijn, moet uw sessiecookieSameSite=None; Securebevatten. EenSameSite=Lax-cookie werkt als u test op een verifieringssite op dezelfde site, maar wordt weggelaten bij cross-site verzoeken. - Onjuiste detectie of account: Controleer of
_email-verification.<email-domain>één TXT-record retourneert met een canonieke hostnaam in kleine letters (iss=<issuer-domain>, zonderhttps://, een poort, een pad of hoofdletters), beide.well-known-eindpuntenContent-Type: application/jsonretourneren,.well-known/email-verificationeenissuerheeft die byte voor byte overeenkomt methttps://<issuer-domain>en deaccounts_endpoint-reactie een account bevat waarvan deemailovereenkomt met het ingevoerde adres. - Niet-ondersteund ondertekeningsalgoritme in
.well-known/email-verification: Chrome 154 en 155 vereisen"EdDSA"insigning_alg_values_supported, terwijl Chrome 156+ en de IETF-specificatie"Ed25519"ondersteunen. Adverteer beide["Ed25519", "EdDSA"]tijdens de overgang, zodat Chrome Stable uw detectiemetadata niet afwijst.
Validatie van verzoek voor uitgifte mislukt
Sec-Fetch-Destspelling van de header: Chrome 154+ stuurtSec-Fetch-Dest: email-verification(met een streepje), terwijl Chrome 153emailverificationstuurde (zonder streepje). Accepteer beide waarden tijdens de uitrol.- Onjuiste HTTP-berichtenhandtekening (
@authority) achter een proxy: Bij de verificatie van de RFC 9421-handtekening geeft het@authority-component de openbare host weer. Als uw server zich achter een omgekeerde proxy of load balancer bevindt, reconstrueert u de verificatie-URL metX-Forwarded-Host(of uw openbare oorsprong) in plaats van de interne hostnaam en berekent uContent-Digestvoor de onbewerkte bytes van de verzoekbody vóór de json-parsing.
De browser wijst het geretourneerde issuance_token af
- Gewijzigde of gecanoniseerde
emailclaim: Vanaf Chrome 156 controleert de browser of de EVTemailclaim byte voor byte overeenkomt met de aangevraagdeemail. Als uw backend het adres normaliseert naar een canonieke accountindeling (zoalsFirst.Last@example.comretourneren alsfirst.LAST@example.comis aangevraagd), laat Chrome het token vallen. Vergelijk het verzoek met het account van de gebruiker, maar retourneer de exacteemail-tekenreeks die in de verzoekbody is ontvangen. - Ontbrekende afsluitende tilde (
~): Zelfs met 0 onthullingen moet deissuance_tokeneen geldige SD-JWT zijn die eindigt met een afsluitende tilde (<Issuer-signed-JWT>~), zodat de browser de<KB-JWT>kan toevoegen. - Niet-overeenkomende
issofcnf.jwk: Zorg dat de EVTiss-claim de exacte HTTPS-oorsprong is (https://<issuer-domain>, geen afsluitende slash) die overeenkomt met uw.well-known/email-verification-metadata en datcnf.jwkde tijdelijke openbare sleutel van de browser insluit vanuit deSignature-Key-header.