Opublikowano: 8 lipca 2026 r., ostatnia aktualizacja: 5 października 2026 r.
Gdy zbierasz adres e-mail w ramach rejestracji, logowania, subskrypcji, płatności, odzyskiwania konta lub innego procesu, powszechną praktyką jest potwierdzanie, że adres e-mail należy do osoby, która go wpisuje. Obecne metody weryfikacji, takie jak jednorazowe hasła (OTP) czy linki weryfikacyjne w e-mailu (magic linki), wymagają od użytkownika opuszczenia Twojej witryny. Ten proces może zwiększyć ryzyko, że użytkownik (człowiek lub agent) całkowicie porzuci sesję i nigdy nie dokończy procesu uwierzytelniania.
Email Verification API to propozycja, która umożliwia przeglądarce bezpośrednią komunikację z dostawcą poczty e-mail w celu sprawdzenia, czy użytkownik jest właścicielem adresu e-mail. Użytkownicy wybierają adres e-mail z sugestii autouzupełniania lub automatycznego uzupełniania w przeglądarce, przesyłają formularz, a witryna weryfikuje adres e-mail u dostawcy bez wysyłania e-maila i bez przerywania procesu użytkownika.
Zbieranie adresów e-mail to kluczowy punkt konwersji na ścieżce użytkownika, dlatego Chrome prosi witryny, które chcą weryfikować adresy e-mail, dostawców poczty e-mail, którzy mogą przeprowadzać weryfikację, oraz użytkowników, którzy przechodzą ten proces, o opinię na temat tej propozycji. Możesz już dziś zarejestrować się w programie testów origin i postępować zgodnie z instrukcjami wdrażania. Ogólne informacje o konfigurowaniu testów origin znajdziesz w artykule Pierwsze kroki z testami origin.
Możesz przetestować ten proces na koncie demonstracyjnym:
- Wersja demonstracyjna wydawcy zapewnia przykładowe konto e-mail i sesję.
- Wersja demonstracyjna weryfikatora zweryfikuje dowolnego dostawcę usług, który bierze udział w programie.
Proces potwierdzania adresu e-mail
W kolejnych sekcjach znajdziesz informacje o tym, co musisz zrobić Ty i Twoi użytkownicy, aby rozpocząć proces weryfikacji adresu e-mail, oraz opis całego procesu w przypadku korzystania z protokołu weryfikacji adresu e-mail.
Kluczowe terminy
Najważniejsze terminy związane z interfejsem Email Verification API:
- Weryfikator: witryna, która zbiera adres e-mail i chce go zweryfikować. Weryfikator jest też nazywany stroną zależną.
- Dostawca poczty e-mail: usługa, która udostępnia adres e-mail użytkownika, np.
gmail.com. - Wystawca: usługa, która zarządza kontem e-mail użytkownika, np.
accounts.google.com. Wydawca jest też nazywany dostawcą tożsamości.
W niektórych przypadkach dostawca poczty e-mail i wydawca mogą działać w tej samej domenie. Ważne jest jednak, aby odróżniać posiadanie adresu e-mail od aktywnej sesji na powiązanym koncie.
Wymagania wstępne
- Użytkownik musi być zalogowany u dostawcy poczty e-mail lub wystawcy w tym samym profilu przeglądarki. Jeśli na przykład korzystają z Gmaila, muszą zalogować się na konto Google.
- Jako uczestnicząca witryna weryfikująca musisz zarejestrować się w programie testów pochodzenia i podać token na tej samej stronie co formularz e-mail.
Użytkownik musi wybrać swój adres e-mail z menu autouzupełniania.
- Jeśli użytkownik wpisał wcześniej adres e-mail w tym polu, zostanie on zaproponowany w ramach autouzupełniania.
Jeśli użytkownik dodał swój adres e-mail w ustawieniach Chrome w sekcji „Autouzupełnianie i hasła” (
chrome://settings/autofill), będzie on dostępny w autouzupełnianiu.
Gdy użytkownik po raz pierwszy poda adres e-mail do weryfikacji, zobaczy prośbę o przyznanie uprawnień. Dzieje się tak tylko raz w przypadku każdego adresu e-mail.
Gdy użytkownik ma aktywną sesję w przeglądarce, może rozpocząć proces:
- W formularzu z polem adresu e-mail użytkownik wybiera swój adres e-mail z rozwijanego menu autouzupełniania. Witryna weryfikująca udostępnia w formularzu ukryte pole z wartością nonce dla każdej instancji, aby zweryfikować to żądanie.
Przeglądarka pobierze wtedy rekord DNS potwierdzania adresu e-mail dla domeny adresu e-mail. Wskazuje to przeglądarce wystawcę. Wydawca potwierdzi wtedy, że ma aktywną sesję dla tego adresu e-mail.
Wystawca poda wtedy token weryfikacji adresu e-mail (EVT). Przeglądarka łączy te informacje w kluczowy token JWT z EVT, pochodzeniem witryny i wartością nonce z formularza wejściowego.
Po przesłaniu formularza pakiet EVT jest dodawany do ukrytego pola i wysyłany do witryny.
Witryna weryfikująca sprawdza następnie wszystkie te szczegóły: oczekiwany adres e-mail, wartość nonce oraz podpisy z przeglądarki i od wystawcy.
Użytkownik zobaczy małe powiadomienie z informacją, że dostawca poczty e-mail potwierdził jego adres.
Ten proces potwierdza w witrynie weryfikującej, że adres e-mail jest prawidłowy i należy do bieżącego użytkownika, co oznacza, że witryna może pominąć wysyłanie e-maila weryfikacyjnego.
Użytkownicy mogą zarządzać zweryfikowanymi adresami e-mail w sekcji Ustawienia > Autouzupełnianie i hasła > Informacje kontaktowe > Zweryfikowany adres e-mail (lub otworzyć chrome://settings/contactInfo).
Kwestie dotyczące przypadków użycia
Potwierdzanie adresu e-mail to progresywne ulepszanie istniejącego procesu, które eliminuje konieczność opuszczania witryny przez użytkownika w celu pobrania hasła jednorazowego lub kliknięcia linku. Witryny mogą dodawać pola potwierdzania adresu e-mail do wszystkich odpowiednich formularzy, takich jak logowanie, rejestracja w newsletterze, tworzenie konta i odzyskiwanie hasła. EVP jest wywoływany tylko wtedy, gdy przeglądarka go obsługuje. Jeśli po przesłaniu nie otrzymasz kodu lub którykolwiek z etapów weryfikacji się nie powiedzie, możesz wrócić do domyślnego procesu potwierdzania adresu e-mail. Oznacza to również, że nie ma wykrywania funkcji interfejsu API. Witryna weryfikująca traktuje EVT jako opcjonalny i przetwarza go, jeśli jest obecny w żądaniu.
Potwierdzanie adresu e-mail potwierdza, że użytkownik ma aktywną sesję u dostawcy adresu e-mail. Nie potwierdza to, że e-mail dotarł do użytkownika. Możesz nadal wysyłać dotychczasowe e-maile powitalne lub wprowadzające, a także zachęcać użytkownika do sprawdzenia ustawień spamu.
Wdrażanie witryny weryfikatora
Więcej informacji znajdziesz w kompleksowym kodzie demonstracyjnym oraz w krokach weryfikacji w propozycjach interfejsu Email Verification API i protokołu Email Verification.
Konfigurowanie pól formularza
Sprawdź, czy pola formularza mają prawidłowe atrybuty:
<input
name="email-address"
type="email"
autocomplete="email">
<input
type="hidden"
name="token"
nonce="rAnD0m-VaLuE"
autocomplete="email-verification-token">
Ustaw atrybuty type i autocomplete elementu wejściowego email na email, aby umożliwić przeglądarce oferowanie autouzupełniania adresu e-mail.
Nowe pole hidden zostanie wypełnione tokenem weryfikacji adresu e-mail po przesłaniu formularza. Wymagane atrybuty to:
- Ustaw wartość
type="hidden", ponieważ to pole nie wymaga wprowadzania danych wejściowych użytkownika. - Ustaw
nonce="rAnD0m-VaLuE". Witryna musi udostępniać niepowtarzalny nonce powiązany z sesją, aby weryfikować przesłanie formularza. - Ustaw
autocomplete="email-verification-token". Przeglądarka używa tego atrybutu do identyfikowania pola, które ma zostać wypełnione.
Sprawdź elementy formularza, otwierając panel Sieć w Narzędziach deweloperskich. Gdy wybierzesz adres e-mail, przeglądarka wyśle zapytania DNS, a następnie zapytania o konto do dostawcy poczty e-mail i wydawcy. Są to wewnętrzne żądania przeglądarki. Twoja witryna nie otrzymuje niczego, dopóki nie zostanie przesłany formularz.
Weryfikowanie EVT
Weryfikacja każdego komponentu pakietu EVT składa się z 5 kroków.
- Przeanalizuj token.
- Sprawdź oczekiwane wartości.
- Sprawdź powiązanie klucza.
- Sprawdź rekord DNS.
- odkryć wystawcę i zweryfikować podpis EVT.
1. Analizowanie tokena
Surowe dane z przesłanego formularza zawierają EVT i podpisane roszczenia w selektywnym ujawnianiu tokena internetowego JSON (SD-JWT+KB) oddzielone tyldą (~). Musisz je rozdzielić i zdekodować nagłówki oraz ładunki Javascript Object Signing and Encryption (JOSE) (np. za pomocą biblioteki jose dla Node.js).
Jeśli example.com zweryfikuje demo@gmail.com, zdekodowany ładunek będzie wyglądać podobnie do tego przykładu:
{
"evtJwtDecodedPayload": {
"cnf": {
"jwk": {
"crv": "Ed25519",
"kty": "OKP",
"x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
}
},
"email": "demo@gmail.com",
"email_verified": true,
"iat": 1782911685,
"iss": "https://accounts.google.com"
},
"kbJwtDecodedPayload": {
"aud": "https://example.com",
"iat": 1782911685,
"nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
"sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
}
}
2. Sprawdzanie oczekiwanych wartości
Sprawdź, czy podstawowe wartości w ładunku odpowiadają podanym przez Ciebie wartościom:
- Sprawdź, czy
email_verifiedma wartośćtrue. - Sprawdź, czy
emailodpowiada adresowi e-mail podanemu w formularzu. - Sprawdź, czy
nonceodpowiada wartości nonce podanej w formularzu. - Sprawdź, czy
audpasuje do źródła Twojej witryny. - Sprawdź, czy
iatma stosunkowo niedawną sygnaturę czasową, np. po wyrenderowaniu formularza.
3. Weryfikowanie powiązania klucza
Przeglądarka tworzy tymczasowy, efemeryczny klucz transakcji, aby potwierdzić, że podpisała token. Wyodrębnij ten klucz z deklaracji cnf (potwierdzenie) w EVT, a następnie użyj go do zweryfikowania tokena JWT powiązanego z kluczem.
Następnie oblicz oczekiwany skrót i porównaj go z roszczeniem sd_hash. Poniższy przykład w Node.js pokazuje, jak wykonać to obliczenie:
const calculatedHash = createHash("sha256")
.update(evtJwt + "~")
.digest("base64url");
4. Weryfikacja rekordu DNS
Sprawdź _email-verification rekord DNS domeny adresu e-mail. Na przykład w przypadku demo@gmail.com wyszukaj rekord _email-verification.gmail.com TXT. W przypadku tego dostawcy zapytanie zwraca lokalizację dostawcy konta, czyli accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
5. Wykrywanie wystawcy i weryfikowanie podpisu EVT
Upewnij się, że wydawca udostępnia zasób /.well-known/email-verification, który zawiera punkty końcowe do wydawania tokena, klucz internetowy JSON (JWK) witryny i obsługiwane algorytmy podpisywania.
$ curl https://accounts.google.com/.well-known/email-verification
{
"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": ["EdDSA"]
}
Użyj JWK, aby zweryfikować token JWT EVT wyodrębniony z tokena. Większość bibliotek JOSE udostępnia funkcje do obsługi tej weryfikacji.
Jeśli wszystkie 5 kroków się powiedzie, adres e-mail zostanie zweryfikowany u dostawcy. Jeśli nie, wyślij użytkownikowi e-maila z potwierdzeniem zgodnie z normalnym procesem.
Wdrożenie usługi dostawcy poczty e-mail i wystawcy
Więcej informacji znajdziesz w przykładzie kodu demonstracyjnego dostawcy poczty e-mail oraz w propozycjach interfejsu Email Verification API i protokołu Email Verification.
Jako wydawca nie musisz rejestrować się w programie testów origin ani podawać tokena, ponieważ działanie przeglądarki jest wywoływane przez witrynę podmiotu ufającego. Musisz tylko zadbać o to, aby oczekiwane punkty końcowe były dostępne i mogły odpowiadać na te żądania.
Konfigurowanie wykrywania wystawcy
Aby umożliwić przeglądarkom automatyczne wykrywanie punktów końcowych weryfikacji po wybraniu adresu e-mail należącego do Twojej domeny, udostępnij konfigurację za pomocą DNS i punktu końcowego HTTP .well-known.
Konfigurowanie rekordu delegowania DNS
Skonfiguruj rekord DNS TXT w domenie poczty e-mail, który przekazuje uprawnienia do weryfikacji identyfikatorowi wystawcy. W zależności od infrastruktury identyfikatory te mogą używać tej samej domeny.
Format rekordu: _email-verification.<email-domain>
Przykładowy plik strefy:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
Hostowanie punktu końcowego .well-known/email-verification
Umieść plik JSON z metadanymi w domenie wydawcy 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ź:
{
"issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
"jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["EdDSA", "ES256"]
}
Hostowanie punktu końcowego .well-known/web-identity
Dodatkowy zasób JSON .well-known, który możesz mieć już zaimplementowany w ramach interfejsu Federated Credentials (FedCM) API.
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 konta w interfejsie FedCM API udostępnia obecnie listę zalogowanych kont. Poniższy przykład pokazuje minimalną odpowiedź. Więcej informacji znajdziesz w przewodniku po implementacji dostawcy tożsamości.
Punkt końcowy: zgodnie z informacjami 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 poinformować o tym przeglądarkę 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 próśb o wydanie
Urządzenie issuance_endpoint otrzymuje żądanie application/x-www-form-urlencoded POST, które zawiera request_token.
W sekcjach poniżej znajdziesz pełny proces obsługi żądań wydania.
1. Weryfikowanie prośby o wydanie
Analizowanie i weryfikowanie przychodzących ładunków przeglądarki:
- Metoda:
POST - Weryfikacja sesji: sprawdź własne pliki cookie użytkownika
session/authenticationprzesyłane wraz z żądaniem, aby upewnić się, że istnieje aktywny, autoryzowany kontekst tożsamości. - Weryfikacja parametru: wyodrębnij parametr
request_token(podpisany token JWT wygenerowany przez przeglądarkę). Sprawdź, czy zawiera oczekiwany efemeryczny klucz publiczny, docelowy adres e-mail, właściwych odbiorców i prawidłową sygnaturę czasową.
Zdekodowany token powinien wyglądać mniej więcej tak:
{
"decodedHeader": {
"alg": "ES256",
"typ": "JWT",
"jwk": {
"kty": "EC",
"crv": "P-256",
"x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
"y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
}
},
"decodedPayload": {
"iss": "https://accounts.issuer.example",
"sub": "demo@example.com",
"email": "demo@example.com",
"iat": 1780272000,
"exp": 1780272300
},
"signature": "SIGnatURE-123_SIGnatURE-123_SIGnatURE-123"
}
2. Odpowiadanie za pomocą tokena
Po pomyślnej weryfikacji sesji i tokena żądania wygeneruj podpisany token JWT z wybiórczym ujawnianiem (SD-JWT) przy użyciu ładunku:
{
"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
}
Podpisz ładunek za pomocą klucza prywatnego i obsługiwanego algorytmu. Na przykład używając jose w Node.js:
const evtJwt = await new SignJWT(evtPayload)
.setProtectedHeader({
alg: "EdDSA",
kid: PRIVATE_KEY_JWK.kid, // Key ID corresponding to our JWKS keys
typ: "evt+jwt", // Standard Token Type for EVTs
})
.sign(privateKey);
// Standard SD-JWT compatibility requires appending a trailing tilde "~"
// to separate the signed token from the key binding section.
const issuanceToken = `${evtJwt}~`;
Przykładowa odpowiedź o powodzeniu (HTTP 200):
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
Wskazówki dotyczące testowania origin
Wersje próbne origin to eksperymenty, które mają na celu zbieranie opinii, więc Twoje zdanie jest bardzo ważne, jeśli uczestniczysz w nich jako strona ufająca lub dostawca tożsamości. Aby zgłosić problemy, skorzystaj z tych repozytoriów GitHub:
- Browser Email Verification API: WICG/email-verification
- Protokół weryfikacji adresu e-mail: dickhardt/email-verification
Jeśli w implementacji Chrome napotkasz błędy, zgłoś je w komponencie:
Włączenie funkcji testowania origin jest kontrolowane w przypadku każdej odpowiedzi przez uwzględnienie tokena testowania origin. Oznacza to, że masz szczegółową kontrolę, jeśli wolisz ograniczyć funkcjonalność do części użytkowników. Jeśli na przykład masz już platformę do testów A/B, możesz zintegrować z nią testowanie origin, aby uzyskać kontrolowaną populację eksperymentalną. Jeśli masz grupę użytkowników, którzy testują wersję beta lub korzystają z wcześniejszego dostępu, możesz włączyć dla nich tę funkcję. W takim przypadku przed wydaniem lub zweryfikowaniem tokena sprawdź, czy podany adres e-mail jest prawidłowy.
Wersje próbne origin mają też limity ruchu, aby zminimalizować liczbę witryn korzystających z funkcji przed jej wprowadzeniem. Interfejs API wydawcy jest w trakcie opracowywania, więc wraz z aktualizacjami interfejsu Chrome mogą pojawiać się zmiany, które nie są wstecznie kompatybilne.
W miarę postępów w pracach będziemy publikować kolejne aktualizacje na tym blogu i na liście mailingowej evp-announce@chromium.org.