Implementacja strony ufającej

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.

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 (lub https://app.issuer.example z 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" i autocomplete="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.

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:

  1. Przeanalizuj token za pomocą biblioteki SD-JWT.
  2. Sprawdź, czy wartości i deklaracje sesji są zgodne z oczekiwaniami.
  3. Zweryfikuj delegację DNS.
  4. Odkryj metadane wydawcy i pobierz JWKS.
  5. 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) i exp (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ę:

  1. Weryfikowanie podpisu wydawcy w EVT na podstawie pobranego JWKS.
  2. Weryfikowanie podpisu przeglądarki w KB-JWT za pomocą efemerycznego klucza publicznego w cnf.jwk.
  3. Weryfikowanie powiązania kluczy (aud, nonce i skrótu sd_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-Trial lub 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 ), a nonce nie 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: deklaracja kid (identyfikator klucza) w nagłówku EVT i JWKS jest opcjonalna (np. Gmail pomija kid). Jeśli kid jest nieobecny, przejdź przez wszystkie klucze kandydujące w jwks_uri wydawcy, zamiast kończyć działanie z powodu nieznalezienia identyfikatora klucza.
  • Identyfikatory algorytmów (Ed25519 i EdDSA): od Chrome 156 Chrome używa w pełni określonego identyfikatora algorytmu Ed25519 (RFC 9864) w przypadku nagłówków cnf.jwk i KB-JWT, natomiast wydawcy i biblioteki mogą określić Ed25519 lub EdDSA (obok ES256). 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 deklaracja iss w 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 prefiks https://.

Nie udało się zweryfikować powiązania kluczy (KB-JWT)

  • Niezgodny lub wygasły nonce: upewnij się, że nonce renderowany 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): deklaracja aud to 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ę email bajt 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.com zamiast first.last@example.com). Podczas dopasowywania deklaracji email tokena do wartości przesłanej w formularzu używaj porównania bez uwzględniania wielkości liter.