Implementacja dostawcy poczty e-mail (wydawcy)

Więcej informacji znajdziesz w przykładowym kodzie demonstracyjnym dostawcy poczty e-mail oraz w propozycjach interfejsu Email Verification API i protokołu Email Verification Protocol.

Jako wydawca nie musisz rejestrować się w testowaniu origin ani podawać tokena, ponieważ zachowanie przeglądarki jest wywoływane przez witrynę strony ufającej. Upewnij się, że punkty końcowe są skonfigurowane tak, aby odpowiadać na te żądania.

Konfigurowanie wykrywania wystawcy

Aby umożliwić przeglądarkom automatyczne wykrywanie punktów końcowych weryfikacji, gdy wybierany jest adres e-mail należący do Twojej domeny, udostępnij konfigurację za pomocą DNS i punktu końcowego HTTP .well-known.

Konfigurowanie rekordu delegowania DNS

Skonfiguruj rekord DNS typu TXT w domenie e-mail, który deleguje uprawnienia do weryfikacji na identyfikator wystawcy. W zależności od infrastruktury te identyfikatory mogą korzystać z tej samej domeny.

Format rekordu: _email-verification.<email-domain>

Przykładowy plik strefy:

_email-verification.example.com IN TXT "iss=accounts.issuer.example"

Wartość iss= musi być czystą, kanoniczną nazwą hosta zapisaną małymi literami (np. iss=accounts.issuer.example) bez schematu (https://), portu, ścieżki ani wielkich liter. Chrome odrzuca rekordy, które zawierają elementy inne niż nazwa hosta.

Hostowanie punktu końcowego .well-known/email-verification

Hostuj plik JSON z metadanymi w domenie wystawcy w ścieżce /.well-known/. Ten plik zawiera informacje o możliwościach wydawania i algorytmach podpisywania kryptograficznego obsługiwanych przez Twoją infrastrukturę.

Punkt końcowy: https://<issuer-domain>/.well-known/email-verification

Przykładowa odpowiedź:

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

Właściwości metadanych:

  • issuer: źródło wystawcy (https://<issuer-domain>, bez ukośnika na końcu ). Musi być dokładnie takie samo jak źródło, z którego jest udostępniany plik metadanych.
  • issuance_endpoint: adres URL HTTPS, który odbiera żądania POST dotyczące wydawania tokenów.
  • jwks_uri: adres URL HTTPS, który udostępnia publiczny zestaw kluczy internetowych JSON (JWKS).
  • signing_alg_values_supported: tablica obsługiwanych algorytmów podpisywania JWS.

Hostowanie punktu końcowego .well-known/web-identity

Być może masz już zaimplementowany dodatkowy .well-known zasób JSON jako część interfejsu Federated Credentials (FedCM) API. Ten zasób zawiera linki do punktu końcowego kont i adresu URL logowania.

Punkt końcowy: https://<domain>/.well-known/web-identity

Przykładowa odpowiedź:

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

Używanie punktu końcowego kont

Punkt końcowy kont z interfejsu FedCM API zawiera listę aktualnie zalogowanych kont. Poniższy przykład przedstawia minimalną odpowiedź. Więcej informacji, znajdziesz w przewodniku implementacji dostawcy tożsamości.

Punkt końcowy: zgodnie z definicją w .well-known/web-identity

Oto przykładowa odpowiedź:

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

Integracja z interfejsem Login Status API

Użytkownik musi mieć aktywną sesję u dostawcy, a Ty musisz zasygnalizować to przeglądarce za pomocą interfejsu Login Status API.

Gdy użytkownik zaloguje się lub wyloguje, wyświetl odpowiedni nagłówek odpowiedzi HTTP:

Set-Login: logged-in
Set-Login: logged-out

Możesz też zaktualizować stan za pomocą JavaScriptu w kontekście aplikacji internetowej:

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

Obsługa żądań wydania

Twój issuance_endpoint otrzymuje żądanie application/json POST, które zawiera klucz email i nagłówki podpisów wiadomości HTTP dla Signature, Signature-Input i Signature-Key.

Użyj biblioteki, która obsługuje nagłówki strukturalne i podpisy wiadomości HTTP w Twoim środowisku. W Node.js możesz użyć structured-headers i http-message-sig.

Pełny format żądania:

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

Przeanalizuj i zweryfikuj żądanie:

  • Uwierzytelnianie sesji: zweryfikuj własne pliki cookie sesji wysłane z żądaniem. Użytkownik musi być uwierzytelniony.
  • Nagłówek Sec-Fetch-Dest: ustaw wartość email-verification.
  • Podpisy wiadomości HTTP: zweryfikuj podpis żądania za pomocą efemerycznego klucza publicznego w Signature-Key i sprawdź Content-Digest. Od Chrome 156 nagłówek Signature-Key zawiera alg="Ed25519" w parametrach hwk; akceptuj "Ed25519" i "EdDSA" oraz zezwalaj na pomijanie alg przez starsze wersje Chrome.
  • Ładunek: treść JSON zawiera ciąg znaków email wymagany do weryfikacji.

Odpowiedź na żądanie wydania

Po pomyślnej weryfikacji sesji i tokena żądania wygeneruj podpisany token JWT z selektywnym ujawnianiem informacji (SD-JWT) zwrócony jako JSON przy użyciu odpowiednich bibliotek dla Twojej platformy. Na przykład w przypadku Node możesz użyć @sd-jwt/core i jose.

Format surowego ładunku powinien wyglądać podobnie do tego:

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

Utwórz, podpisz i zwróć 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);

Wynikowa treść odpowiedzi wygląda podobnie do tej:

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

Po utworzeniu i podpisaniu tokena potwierdzania adresu e-mail przeglądarka przekazuje go do witryny weryfikatora w celu sprawdzenia.

Rozwiązywanie problemów

Jeśli przeglądarka nie kontaktuje się z Twoimi punktami końcowymi lub odrzuca wydane tokeny, sprawdź te typowe problemy:

Przeglądarka nigdy nie wywołuje accounts_endpoint ani issuance_endpoint

  • Nie ustawiono stanu logowania: Chrome wysyła zapytania do Twoich punktów końcowych tylko wtedy, gdy wie, że użytkownik jest zalogowany. Upewnij się, że proces logowania ustawia nagłówek Set-Login: logged-in HTTP lub wywołuje navigator.login.setStatus("logged-in").
  • Zablokowane pliki cookie sesji (SameSite=None): przeglądarka pobiera accounts_endpoint i issuance_endpoint z witryny strony ufającej w innej witrynie. Ponieważ są to żądania z innej witryny, plik cookie sesji musi zawierać SameSite=None; Secure. Plik cookie SameSite=Lax działa podczas testowania na weryfikatorze w tej samej witrynie, ale jest pomijany w żądaniach z innej witryny.
  • Niezgodność wykrywania lub konta: sprawdź, czy _email-verification.<email-domain> zwraca pojedynczy rekord TXT z kanoniczną nazwą hosta zapisaną małymi literami (iss=<issuer-domain>, bez https://, portu, ścieżki ani wielkich liter), oba punkty końcowe .well-known zwracają Content-Type: application/json, .well-known/email-verification ma issuer pasujący do https://<issuer-domain> bajt po bajcie, a accounts_endpoint odpowiedź zawiera konto, którego email pasuje do wpisanego adresu.
  • Nieobsługiwany algorytm podpisywania w .well-known/email-verification: Chrome 154 i 155 wymagają "EdDSA" w signing_alg_values_supported, natomiast Chrome 156+ i specyfikacja IETF obsługują "Ed25519". Podczas przejścia reklamuj oba algorytmy ["Ed25519", "EdDSA"], aby stabilna wersja Chrome nie odrzucała metadanych wykrywania.

Weryfikacja żądania wydania nie powiodła się

  • Sec-Fetch-Dest błąd w pisowni nagłówka: Chrome 154+ wysyła Sec-Fetch-Dest: email-verification (z myślnikiem), a Chrome 153 wysyłał emailverification (bez myślnika). Podczas wdrażania akceptuj obie wartości.
  • Niezgodność podpisu wiadomości HTTP (@authority) za serwerem proxy: podczas weryfikowania podpisu RFC 9421 komponent @authority odzwierciedla publiczny host. Jeśli serwer znajduje się za odwrotnym serwerem proxy lub systemem równoważenia obciążenia, odtwórz URL do weryfikacji za pomocą X-Forwarded-Host (lub publicznego origin) zamiast wewnętrznej nazwy hosta i oblicz Content-Digest na podstawie surowych bajtów treści żądania przed analizowaniem JSON.

Przeglądarka odrzuca zwrócony issuance_token

  • Zmodyfikowane lub kanoniczne roszczenie email: od Chrome 156 przeglądarka sprawdza, czy roszczenie email w EVT jest dokładnie takie samo jak żądane email. Jeśli backend normalizuje adres do kanonicznego formatu konta (np. zwraca First.Last@example.com, gdy zażądano first.LAST@example.com), Chrome odrzuca token. Dopasuj żądanie do konta użytkownika, ale zwróć dokładny ciąg znaków email otrzymany w treści żądania.
  • Brak tyldy na końcu (~): nawet w przypadku braku ujawnień issuance_token musi być prawidłowym tokenem SD-JWT kończącym się tyldą (<Issuer-signed-JWT>~), aby przeglądarka mogła dołączyć <KB-JWT>.
  • Niezgodność iss lub cnf.jwk: upewnij się, że roszczenie iss w EVT jest dokładnym źródłem HTTPS (https://<issuer-domain> bez ukośnika na końcu) pasującym do metadanych .well-known/email-verification, a cnf.jwk zawiera efemeryczny klucz publiczny przeglądarki z nagłówka Signature-Key.