Implementatie van e-mailprovider (uitgever)

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 die POST-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 op email-verification.
  • HTTP-berichtenhandtekeningen: Verifieer de verzoekhandtekening met de tijdelijke openbare sleutel in Signature-Key en valideer de Content-Digest. Vanaf Chrome 156 bevat de Signature-Key header alg="Ed25519" in de hwk parameters. Accepteer "Ed25519" en "EdDSA" en sta toe dat alg wordt weggelaten door eerdere Chrome-versies.
  • Payload: De json-body bevat de email tekenreeks 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-in HTTP-header instelt of navigator.login.setStatus("logged-in") aanroept.
  • Sessiecookies geblokkeerd (SameSite=None): De browser haalt uw accounts_endpoint en issuance_endpoint op van een vertrouwende partij op een andere site. Omdat dit cross-site verzoeken zijn, moet uw sessiecookie SameSite=None; Secure bevatten. Een SameSite=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>, zonder https://, een poort, een pad of hoofdletters), beide .well-known-eindpunten Content-Type: application/json retourneren, .well-known/email-verification een issuer heeft die byte voor byte overeenkomt met https://<issuer-domain> en de accounts_endpoint-reactie een account bevat waarvan de email overeenkomt met het ingevoerde adres.
  • Niet-ondersteund ondertekeningsalgoritme in .well-known/email-verification: Chrome 154 en 155 vereisen "EdDSA" in signing_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-Dest spelling van de header: Chrome 154+ stuurt Sec-Fetch-Dest: email-verification (met een streepje), terwijl Chrome 153 emailverification stuurde (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 met X-Forwarded-Host (of uw openbare oorsprong) in plaats van de interne hostnaam en berekent u Content-Digest voor de onbewerkte bytes van de verzoekbody vóór de json-parsing.

De browser wijst het geretourneerde issuance_token af

  • Gewijzigde of gecanoniseerde email claim: Vanaf Chrome 156 controleert de browser of de EVT email claim byte voor byte overeenkomt met de aangevraagde email. Als uw backend het adres normaliseert naar een canonieke accountindeling (zoals First.Last@example.com retourneren als first.LAST@example.com is aangevraagd), laat Chrome het token vallen. Vergelijk het verzoek met het account van de gebruiker, maar retourneer de exacte email-tekenreeks die in de verzoekbody is ontvangen.
  • Ontbrekende afsluitende tilde (~): Zelfs met 0 onthullingen moet de issuance_token een geldige SD-JWT zijn die eindigt met een afsluitende tilde (<Issuer-signed-JWT>~), zodat de browser de <KB-JWT> kan toevoegen.
  • Niet-overeenkomende iss of cnf.jwk: Zorg dat de EVT iss-claim de exacte HTTPS-oorsprong is (https://<issuer-domain>, geen afsluitende slash) die overeenkomt met uw .well-known/email-verification-metadata en dat cnf.jwk de tijdelijke openbare sleutel van de browser insluit vanuit de Signature-Key-header.