Aby wdrożyć potwierdzanie adresu e-mail w swojej witrynie, zaktualizuj znaczniki formularza, aby wysyłać prośby o token, i dodaj weryfikację po stronie serwera dla przychodzących tokenów.
Rejestracja w testowaniu origin
Witryny, które mają być weryfikowane, muszą mieć skonfigurowane testowanie origin.
- Rejestracja w testowaniu origin
- Wyświetlanie tokena testowania origin
Od Chrome 154 testowanie origin innych firm jest obsługiwane z ważnym zastrzeżeniem: zarejestrowany origin testowania musi być w tej samej witrynie co wydawca. Na przykład:
- Domena wydawcy:
issuer.example - Rejestrujący testowanie origin:
https://issuer.example - Punkt początkowy JavaScript:
https://issuer.example(lubhttps://app.issuer.examplez dopasowaniem subdomeny)
Konfigurowanie pól formularza
Dodaj ukryte pole tokena do formularza przesyłania e-maili:
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
Wymagania dotyczące pól:
- Pole e-maila: ustaw
type="email"iautocomplete="email", aby Chrome mógł autouzupełniać adres i go rozpoznawać. - Atrybuty pola tokena:
- Ustaw
autocomplete="email-verification-token": Chrome identyfikuje to pole, aby wypełnić token podczas przesyłania. - Ustaw
nonce="<VALUE>": witryna musi podać unikalny nonce powiązany z sesją , aby zweryfikować przesłanie formularza.
- Ustaw
Weryfikowanie tokena potwierdzania adresu e-mail (EVT)
Gdy użytkownik prześle formularz, Twój serwer otrzyma adres e-mail i token z ukrytego pola. Puste pole tokena oznacza, że przeglądarka lub dostawca nie obsługuje EVP albo użytkownik pominął weryfikację. W takim przypadku wróć do dotychczasowego procesu weryfikacji, np. wysyłania hasła jednorazowego lub magicznego linku.
Jeśli token jest obecny, zweryfikuj go w ten sposób:
- Przeanalizuj token za pomocą biblioteki SD-JWT.
- Sprawdź, czy wartości i deklaracje sesji są zgodne z oczekiwaniami.
- Zweryfikuj delegację DNS.
- Odkryj metadane wydawcy i pobierz JWKS.
- Zweryfikuj podpisy kryptograficzne i powiązanie kluczy.
1. Przeanalizuj token
Token używa formatu RFC 9901: Selective Disclosure JWT
(SD-JWT+KB). Do analizowania i weryfikowania tokena używaj odpowiednich bibliotek dla swojej platformy.
Na przykład w przypadku Node możesz użyć
@sd-jwt/core i
jose. W postaci surowej wygląda to tak: token JWT podpisany przez wydawcę, po którym następuje zero lub więcej ujawnień, a na końcu token JWT powiązania kluczy. Każdy komponent jest oddzielony tyldą:
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
W obecnej implementacji token zawiera zero ujawnień
(<Issuer-signed EVT>~<Key Binding JWT>). Może się to jednak zmienić w
przyszłości.
Zdekoduj token za pomocą biblioteki:
import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
createHash(alg === "sha-256" ? "sha256" : alg)
.update(data)
.digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;
Jeśli verifier.example zweryfikuje demo@provider.example, zdekodowany token będzie wyglądać podobnie do tego:
{
"evtJwtDecodedHeader": {
"typ": "evt+jwt",
"alg": "EdDSA",
"kid": "issuer-key-id"
},
"evtJwtDecodedPayload": {
"iss": "https://provider.example",
"iat": 12345678901,
"exp": 12345679901,
"cnf": {
"jwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
}
},
"email": "demo@provider.example",
"email_verified": true
},
"kbJwtDecodedHeader": {
"alg": "EdDSA",
"typ": "kb+jwt"
},
"kbJwtDecodedPayload": {
"aud": "https://verifier.example",
"iat": 12345678901,
"nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
"sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
},
"disclosures": []
}
2. Sprawdź, czy wartości i deklaracje sesji są zgodne z oczekiwaniami
Sprawdź, czy podstawowe wartości w ładunku są zgodne z podanymi i oczekiwanymi wartościami:
email_verified: musi mieć wartośćtrue.email: musi być zgodny z adresem e-mail przesłanym w formularzu.aud(odbiorca): musi być zgodny z origin Twojej witryny.nonce: musi być zgodny z nonce podanym w formularzu.iat(issued at) iexp(expiry): potwierdź, że token mieści się w prawidłowym przedziale czasu i nie wygasł.
3. Zweryfikuj delegację DNS
Zweryfikuj rekord DNS _email-verification dla domeny adresu e-mail. Na przykład w przypadku demo@gmail.com zapytaj o rekord TXT _email-verification.gmail.com. W przypadku tego dostawcy zapytanie zwraca lokalizację dostawcy konta, czyli accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
Sprawdź, czy schemat wydawcy to https:// oraz czy https://<domain> jest zgodny z
deklaracją iss w EVT.
4. Zweryfikuj podpis EVT
Pobierz metadane wykrywania wydawcy z
https://<issuer>/.well-known/email-verification:
{
"issuer": "https://accounts.google.com",
"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": ["Ed25519", "EdDSA"]
}
Jeśli metadane zawierają pole issuer, sprawdź, czy jest ono zgodne z iss
deklaracją w EVT bajt po bajcie. Pobierz zestaw kluczy sieciowych JSON z jwks_uri.
Użyj biblioteki SD-JWT, aby zweryfikować pakiet tokena. Biblioteka koordynuje weryfikację:
- Weryfikowanie podpisu wydawcy w EVT na podstawie pobranego JWKS.
- Weryfikowanie podpisu przeglądarki w KB-JWT za pomocą efemerycznego klucza publicznego w
cnf.jwk. - Weryfikowanie powiązania kluczy (
aud,noncei skrótusd_hash).
Przykładowa logika weryfikacji w Node.js:
import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
createHash(alg === "sha-256" ? "sha256" : alg)
.update(data)
.digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
hasher,
// Verifier for the Issuer-signed EVT
verifier: async (data, sig) => {
const token = `${data}.${sig}`;
const header = decoded.jwt.header;
// Match by kid if present, or iterate across matching algorithm keys
const keysToTry = header.kid
? jwksData.keys.filter(k => k.kid === header.kid)
: jwksData.keys;
for (const jwk of keysToTry) {
try {
const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
await compactVerify(token, pubKey);
return true;
} catch {
// Try next candidate key
}
}
return false;
},
// Verifier for the Key Binding JWT (KB-JWT)
kbVerifier: async (data, sig) => {
try {
const browserJwkKey = evtPayload.cnf?.jwk;
if (!browserJwkKey) return false;
const pubKey = await importJWK(browserJwkKey, kbAlg);
await compactVerify(`${data}.${sig}`, pubKey);
return true;
} catch {
return false;
}
},
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
kb: {
expectedNonce: sessionNonce,
expectedAudience: "https://example.com",
required: true,
},
});
const verifiedPayload = result.payload;
if (
verifiedPayload.email_verified !== true ||
verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
throw new Error("Token email does not match submitted email");
}
Jeśli wszystkie kroki się powiodą, adres e-mail zostanie zweryfikowany u dostawcy. Jeśli weryfikacja się nie powiedzie, wróć do wysyłania e-maila z potwierdzeniem do użytkownika za pomocą zwykłego procesu.
Rozwiązywanie problemów
Jeśli weryfikacja się nie powiedzie lub przeglądarka nie poda tokena, sprawdź te typowe problemy:
Pole tokena jest puste podczas przesyłania
- Rejestracja w testowaniu origin: sprawdź, czy nagłówek
Origin-Triallub tag<meta>jest wyświetlany na stronie oraz czy token nie przekroczył daty ważności (tokeny wygenerowane przed przedłużeniem Chrome 160 wygasną 17 listopada 2026 r.). W przypadku testowania origin innych firm (Chrome 154+) zarejestrowany origin testowania musi być w tej samej witrynie co wydawca (https://<issuer-domain>). Stan testowania origin i datę ważności tokena możesz sprawdzić w Narzędziach dla deweloperów w sekcji Aplikacja > Ramki > (wybierz odpowiednią ramkę) > Testowanie origin. - Kod formularza: zarówno
<input type="email" autocomplete="email">jak i<input type="hidden" autocomplete="email-verification-token" nonce="...">muszą znajdować się w tym samym elemencie<form>(nie mogą być odizolowane od granic Shadow DOM ), anoncenie może być pusty. - Wczesne przesłanie lub ponowne użycie strony: przeglądarka pobiera token w tle po wpisaniu lub automatycznym uzupełnieniu adresu e-mail. Przesłanie przed zakończeniem żądania spowoduje, że token będzie pusty. Może się tak zdarzyć, jeśli użytkownik naciśnie Enter, aby przesłać formularz po wpisaniu adresu e-mail.
- Wymagania wstępne dotyczące przeglądarki i dostawcy: użytkownik musi być zalogowany u
uczestniczącego dostawcy w tym samym profilu przeglądarki i mieć włączoną opcję Zweryfikowany
adres e-mail w ustawieniach Chrome (
chrome://settings/contactInfo).
Nie udało się zweryfikować podpisu wydawcy
- Brak nagłówka
kid: deklaracjakid(identyfikator klucza) w nagłówku EVT i JWKS jest opcjonalna (np. Gmail pomijakid). Jeślikidjest nieobecny, przejdź przez wszystkie klucze kandydujące wjwks_uriwydawcy, zamiast kończyć działanie z powodu nieznalezienia identyfikatora klucza. - Identyfikatory algorytmów (
Ed25519iEdDSA): od Chrome 156 Chrome używa w pełni określonego identyfikatora algorytmuEd25519(RFC 9864) w przypadku nagłówkówcnf.jwkiKB-JWT, natomiast wydawcy i biblioteki mogą określićEd25519lubEdDSA(obokES256). Upewnij się, że logika importowania i weryfikacji JWK akceptuje oba identyfikatory. - Format origin wydawcy (
iss): rekord DNS TXT (_email-verification.<domain>) zawiera samą nazwę hosta (iss=accounts.issuer.example), natomiast deklaracjaissw EVT to pełny origin HTTPS (https://accounts.issuer.example, bez ukośnika na końcu). Przed porównaniem dodaj do wartości rekordu DNS prefikshttps://.
Nie udało się zweryfikować powiązania kluczy (KB-JWT)
- Niezgodny lub wygasły nonce: upewnij się, że
noncerenderowany w<input>jest zgodny z aktywnym nonce sesji na serwerze i nie został zastąpiony przez inną kartę ani wykorzystany przez poprzednie żądanie. - Niezgodność odbiorcy (
aud): deklaracjaaudto origin HTTPS weryfikatora (https://verifier.example, bez ścieżki i ukośnika na końcu).
Nie udało się porównać deklaracji e-maila (email)
- Wielkość liter i kanonizacja: Chrome 156+ zwraca deklarację
emailbajt po bajcie, tak jak została wpisana w formularzu, ale starsze wersje przeglądarki lub dostawcy mogą zwracać adres w postaci kanonicznej (np.First.Last@example.comzamiastfirst.last@example.com). Podczas dopasowywania deklaracjiemailtokena do wartości przesłanej w formularzu używaj porównania bez uwzględniania wielkości liter.