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 żądaniaPOSTdotyczą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-Keyi sprawdźContent-Digest. Od Chrome 156 nagłówekSignature-Keyzawieraalg="Ed25519"w parametrachhwk; akceptuj"Ed25519"i"EdDSA"oraz zezwalaj na pomijaniealgprzez starsze wersje Chrome. - Ładunek: treść JSON zawiera ciąg znaków
emailwymagany 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-inHTTP lub wywołujenavigator.login.setStatus("logged-in"). - Zablokowane pliki cookie sesji (
SameSite=None): przeglądarka pobieraaccounts_endpointiissuance_endpointz witryny strony ufającej w innej witrynie. Ponieważ są to żądania z innej witryny, plik cookie sesji musi zawieraćSameSite=None; Secure. Plik cookieSameSite=Laxdział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>, bezhttps://, portu, ścieżki ani wielkich liter), oba punkty końcowe.well-knownzwracająContent-Type: application/json,.well-known/email-verificationmaissuerpasujący dohttps://<issuer-domain>bajt po bajcie, aaccounts_endpointodpowiedź zawiera konto, któregoemailpasuje do wpisanego adresu. - Nieobsługiwany algorytm podpisywania w
.well-known/email-verification: Chrome 154 i 155 wymagają"EdDSA"wsigning_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-Destbłąd w pisowni nagłówka: Chrome 154+ wysyłaSec-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@authorityodzwierciedla 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 obliczContent-Digestna 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 roszczenieemailw EVT jest dokładnie takie samo jak żądaneemail. Jeśli backend normalizuje adres do kanonicznego formatu konta (np. zwracaFirst.Last@example.com, gdy zażądanofirst.LAST@example.com), Chrome odrzuca token. Dopasuj żądanie do konta użytkownika, ale zwróć dokładny ciąg znakówemailotrzymany w treści żądania. - Brak tyldy na końcu (
~): nawet w przypadku braku ujawnieńissuance_tokenmusi być prawidłowym tokenem SD-JWT kończącym się tyldą (<Issuer-signed-JWT>~), aby przeglądarka mogła dołączyć<KB-JWT>. - Niezgodność
isslubcnf.jwk: upewnij się, że roszczenieissw 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, acnf.jwkzawiera efemeryczny klucz publiczny przeglądarki z nagłówkaSignature-Key.