Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Testowanie protokołu weryfikacji adresu e-mail w ramach testu pochodzenia

Rowan Merewood

Opublikowano: 8 lipca 2026 r.

Gdy zbierasz adres e-mail w ramach rejestracji, logowania, subskrypcji, realizacji zakupu, odzyskiwania konta lub innego procesu, często potwierdzasz, że adres e-mail należy do osoby, która go wpisuje. Obecne metody weryfikacji, takie jak hasła jednorazowe czy linki weryfikacyjne (magiczne linki), wymagają od użytkownika opuszczenia Twojej witryny. Ten proces może zwiększyć ryzyko, że użytkownik (człowiek lub agent) całkowicie opuści sesję i 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 autouzupełniania lub podpowiedzi przeglądarki, przesyłają formularz, a witryna weryfikuje adres e-mail u dostawcy bez wysyłania e-maila i przerywania procesu użytkownika.

Prezentacja monitu użytkownika interfejsu Email Verification API — Demo monitu użytkownika w interfejsie Email Verification API

Zbieranie adresów e-mail to ważny punkt konwersji w ścieżce użytkownika. Chrome prosi o opinie na temat tej propozycji od witryn które chcą weryfikować adresy e-mail, dostawców poczty e-mail, którzy mogą przeprowadzić weryfikację, oraz użytkowników, którzy przechodzą ten proces. Możesz zarejestrować się w wersji próbnej origin już dziś i postępować zgodnie z instrukcjami implementacji. Ogólne informacje o konfigurowaniu wersji próbnej origin znajdziesz w artykule Pierwsze kroki z wersjami próbnymi origin origin.

Możesz wypróbować ten proces na koncie demonstracyjnym:

Demo wydawcy zapewnia fikcyjne konto e-mail i sesję.
Demo weryfikatora zweryfikuje dowolnego uczestniczącego dostawcę.

Proces weryfikacji adresu e-mail

Z poniższych sekcji dowiesz się, co musisz zrobić Ty i Twoi użytkownicy, aby rozpocząć proces weryfikacji adresu e-mail, oraz jak wygląda cały proces korzystania z protokołu weryfikacji adresu e-mail.

Kluczowe terminy

Kluczowe terminy w interfejsie Email Verification API:

Weryfikator: witryna, która zbiera adres e-mail i chce go zweryfikować. Weryfikator jest też nazywany stroną ufającą.
Dostawca poczty e-mail: usługa, która udostępnia adres e-mail użytkownika, np. gmail.com.
Wydawca: usługa, która zarządza kontem e-mail użytkownika, na przykład 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óżnić posiadanie adresu e-mail od aktywnej sesji na powiązanym koncie.

Architektura procesu weryfikacji adresu e-mail

Wymagania wstępne

Użytkownik musi być zalogowany u dostawcy poczty e-mail lub wydawcy w tym samym profilu przeglądarki. Jeśli na przykład korzysta z Gmaila, musi być zalogowany na konto Google.
Jako uczestnicząca witryna weryfikatora musisz zarejestrować się w wersji próbnej origin i podać token na tej samej stronie co formularz e-mail.
Użytkownik musi wybrać swój adres e-mail z menu autouzupełniania lub podpowiedzi.
- Jeśli użytkownik wcześniej wpisał adres e-mail w polu, zostanie on zaproponowany za pomocą autouzupełniania.
- Jeśli użytkownik dodał swój adres e-mail w ustawieniach Chrome „Autouzupełnianie i hasła” (chrome://settings/autofill), zostanie on zaproponowany za pomocą autouzupełniania.
  
  **Uwaga:** obsługa adresów wpisywanych ręcznie jest planowana w przyszłej wersji.
Gdy użytkownik po raz pierwszy poda adres e-mail do weryfikacji, zobaczy prośbę o przyznanie uprawnień. Występuje ona tylko raz na adres e-mail.

Gdy użytkownik ma aktywną sesję w przeglądarce, może rozpocząć proces:

W formularzu z polem e-mail użytkownik wybiera swój adres e-mail z menu autouzupełniania. Witryna weryfikatora udostępnia w formularzu ukryte pole z nonce na potrzeby weryfikacji tego żądania.
Przeglądarka pobierze rekord DNS weryfikacji adresu e-mail dla domeny e-mail. Kieruje to przeglądarkę do wydawcy. Wydawca potwierdzi, że ma aktywną sesję dla tego adresu e-mail.

Uwaga: te żądania nie ujawniają żadnych dodatkowych informacji o użytkowniku. Witryna weryfikatora nie otrzymuje informacji na tym etapie. Wydawca widzi tylko prośbę o sprawdzenie, czy użytkownik istnieje. Nie widzi, która witryna zainicjowała żądanie. Nie widzi, która witryna zainicjowała żądanie.
Wydawca udostępni token weryfikacji adresu e-mail (EVT) dla adresu. Przeglądarka łączy go z tokenem JWT powiązanym z kluczem, pochodzeniem witryny i nonce z formularza.
Po przesłaniu formularza pakiet EVT jest dodawany do ukrytego pola i wysyłany do witryny.
Witryna weryfikatora sprawdza wtedy każdy z tych szczegółów: oczekiwany adres e-mail, nonce oraz podpisy przeglądarki i wydawcy.
Użytkownik zobaczy małe powiadomienie informujące, że dostawca poczty e-mail zweryfikował jego adres.

Ten proces potwierdza witrynie weryfikatora, ż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).

Względy dotyczące przypadków użycia

Weryfikacja adresu e-mail to ulepszenie 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 weryfikacji adresu e-mail do wszystkich odpowiednich formularzy, takich jak logowanie, rejestracja do newslettera, tworzenie konta i odzyskiwanie hasła. Protokół EVP jest uruchamiany tylko wtedy, gdy jest obsługiwany przez przeglądarkę. 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 weryfikatora traktuje token EVT jako opcjonalny i przetwarza go, jeśli jest obecny w żądaniu.

Weryfikacja adresu e-mail potwierdza, że użytkownik ma aktywną sesję u dostawcy swojego adresu e-mail. Nie potwierdza, że Twój e-mail dotarł do użytkownika. Możesz nadal wysyłać dotychczasowe e-maile powitalne lub wprowadzające oraz prosić użytkownika o sprawdzenie ustawień spamu.

Implementowanie witryny weryfikatora

Więcej informacji znajdziesz w kodzie demonstracyjnym end-to-end oraz w krokach weryfikacji w propozycjach interfejsu Email Verification API i protokołu Email Verification Protocol weryfikacji adresu e-mail.

Konfigurowanie pól formularza

Upewnij się, że 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 pola email na email, aby przeglądarka mogła oferować autouzupełnianie adresu e-mail.

Nowe pole hidden zostanie wypełnione tokenem weryfikacji adresu e-mail po przesłaniu formularza. Wymagane atrybuty:

Ustaw type="hidden", ponieważ to pole nie wymaga danych wejściowych od użytkownika.
Ustaw nonce="rAnD0m-VaLuE". Witryna musi podać unikalny nonce powiązany z sesją, aby zweryfikować 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, sprawdzając panel Sieć w Narzędziach deweloperskich. Gdy wybierzesz adres e-mail, zobaczysz, że przeglądarka uruchamia zapytania DNS i kolejne zapytania o konto do dostawcy poczty e-mail i wydawcy. Są to wewnętrzne żądania przeglądarki. Twoja witryna nie otrzymuje niczego do momentu przesłania formularza.

Weryfikowanie tokena EVT

Aby zweryfikować każdy komponent pakietu EVT, wykonaj 5 kroków.

Przeanalizuj token.
Sprawdź oczekiwane wartości.
Sprawdź powiązanie klucza.
Sprawdź rekord DNS.
Odkryj wydawcę i zweryfikuj podpis EVT.

1. Przeanalizuj token

Surowe dane z przesłania formularza zawierają token EVT i podpisane deklaracje w tokenie internetowym JSON z selektywnym ujawnianiem (SD-JWT+KB) oddzielone tyldą (~). Musisz je rozdzielić i zdekodować nagłówki oraz ładunki 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. Sprawdź oczekiwane wartości

Sprawdź, czy podstawowe wartości w ładunku odpowiadają podanym wartościom:

Sprawdź, czy email_verified ma wartość true.
Sprawdź, czy email odpowiada adresowi e-mail podanemu w formularzu.
Sprawdź, czy nonce odpowiada nonce podanemu w formularzu.
Sprawdź, czy aud odpowiada pochodzeniu Twojej witryny.
Sprawdź, czy iat ma stosunkowo niedawną sygnaturę czasową, np. po wyrenderowaniu formularza.

3. Sprawdź powiązanie klucza

Przeglądarka tworzy tymczasowy, efemeryczny klucz do transakcji, aby potwierdzić, że podpisała token. Wyodrębnij ten klucz z deklaracji cnf (potwierdzenie) w tokenie EVT, a następnie użyj go do zweryfikowania tokena JWT powiązanego z kluczem.

Następnie oblicz oczekiwany hash i porównaj go z deklaracją sd_hash. Poniższy przykład w Node.js pokazuje, jak wykonać to obliczenie:

const calculatedHash = createHash("sha256")
        .update(evtJwt + "~")
        .digest("base64url");

4. Sprawdź rekord DNS

Sprawdź 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"

5. Odkryj wydawcę i zweryfikuj podpis 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) dla witryny oraz 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 kluczy 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. W przeciwnym razie wróć do wysyłania e-maila z potwierdzeniem do użytkownika zgodnie ze standardowym procesem.

Implementowanie usługi dostawcy poczty e-mail i wydawcy

Więcej informacji znajdziesz w kodzie demonstracyjnym fikcyjnego dostawcy poczty e-mail oraz w krokach wydawcy w propozycjach interfejsu Email Verification API i protokołu Email Verification Protocol weryfikacji adresu e-mail.

Jako wydawca nie musisz rejestrować się w wersji próbnej origin ani podawać tokena, ponieważ zachowanie przeglądarki jest wywoływane przez witrynę strony ufającej. Musisz tylko upewnić się, że odpowiednie punkty końcowe są dostępne, aby odpowiadać na te żądania.

Konfigurowanie wykrywania wydawcy

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 TXT DNS w domenie e-mail, który deleguje uprawnienia do weryfikacji na identyfikator wydawcy. W zależności od infrastruktury te identyfikatory 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`

Hostuj plik JSON z metadanymi w domenie wydawcy w ścieżce /.well-known/. Ten plik zawiera informacje o możliwościach wydawania oraz 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 już mieć zaimplementowany w ramach interfejsu Federated Credentials (FedCM) API. Zawiera on 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 POST application/x-www-form-urlencoded, które zawiera request_token.

Z poniższych sekcji dowiesz się, jak w pełni obsługiwać żądania wydania.

1. Sprawdź żądanie wydania

Przeanalizuj i sprawdź przychodzące ładunki przeglądarki:

Metoda: POST
Weryfikacja sesji: sprawdź pliki cookie sesji/uwierzytelniania użytkownika przekazywane wraz z żądaniem, aby upewnić się, że istnieje aktywny, autoryzowany kontekst tożsamości.session/authentication
Weryfikacja parametru: wyodrębnij parametr request_token (podpisany token JWT wygenerowany przez przeglądarkę). Sprawdź, czy zawiera on oczekiwany efemeryczny klucz publiczny, docelowy adres e-mail, prawidłową grupę odbiorców i prawidłową sygnaturę czasową.

Zdekodowany token powinien wyglądać podobnie do tego:

{
  "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. Odpowiedz tokenem

Po pomyślnej weryfikacji sesji i tokena żądania wygeneruj podpisany token JWT z selektywnym ujawnianiem (SD-JWT) za pomocą ł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, za pomocą biblioteki 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...~"
}

Względy dotyczące wersji próbnej origin

Wersje próbne origin to eksperymenty, które mają na celu zbieranie opinii, dlatego Twoje opinie są bardzo ważne, jeśli bierzesz udział jako strona ufająca lub dostawca tożsamości. Aby zgłaszać problemy, użyj tych repozytoriów GitHub:

Interfejs Email Verification API w przeglądarce: WICG/email-verification
Protokół weryfikacji adresu e-mail: dickhardt/email-verification

Jeśli napotkasz błędy w implementacji Chrome, zgłoś je w komponencie:

Nowy problem: Chromium > Blink > Identity > EVP

Włączenie funkcji wersji próbnej origin jest kontrolowane w przypadku każdej odpowiedzi przez dodanie tokena OT. Oznacza to, że masz szczegółową kontrolę, jeśli chcesz ograniczyć funkcję do części użytkowników. Jeśli na przykład masz już platformę testów A/B, możesz zintegrować z nią wersję próbną origin, aby przeprowadzić kontrolowany eksperyment. Jeśli masz grupę użytkowników testujących wersję beta lub wczesną wersję, możesz włączyć dla nich tę funkcję. W takim przypadku przed wydaniem lub zweryfikowaniem tokena sprawdź podany adres e-mail.

Wersje próbne origin mają też limity ruchu, aby zminimalizować liczbę witryn korzystających z tej funkcji przed jej uruchomieniem. Interfejs API wydawcy jest w trakcie opracowywania i należy się spodziewać zmian powodujących brak zgodności wstecznej oraz aktualizacji interfejsu Chrome.

W miarę postępów prac będziemy publikować kolejne informacje na blogu oraz na evp-announce@chromium.org.