Чтобы реализовать проверку адреса электронной почты на своем сайте, обновите разметку формы, чтобы запрашивать токен, и добавьте проверку входящих токенов на стороне сервера.
Зарегистрируйтесь для участия в эксперименте с источником
На сайтах, выполняющих проверку, должен быть настроен эксперимент с источником.
- Как зарегистрироваться для участия в эксперименте с источником
- Как передать токен эксперимента с источником
Начиная с Chrome 154 поддерживаются эксперименты со сторонними источниками, но с важной оговоркой: зарегистрированный источник для эксперимента должен быть тем же сайтом, что и эмитент. Пример:
- Домен издателя:
issuer.example - Регистрант OT:
https://issuer.example - Источник JavaScript:
https://issuer.example(илиhttps://app.issuer.exampleс сопоставлением субдоменов).
Как настроить поля формы
Добавьте скрытое поле токена в форму отправки электронных писем:
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
Требования к полям
- Поле адреса электронной почты. Задайте
type="email"иautocomplete="email", чтобы Chrome мог распознавать адрес и автоматически заполнять поле. - Атрибуты поля токена:
- Set
autocomplete="email-verification-token": Chrome identifies this field to populate the token on submission. - Установите
nonce="<VALUE>": сайт должен предоставлять уникальный одноразовый код, связанный с сеансом, чтобы подтвердить отправку формы.
- Set
Проверьте токен подтверждения адреса электронной почты (EVT)
Когда пользователь отправляет форму, ваш сервер получает адрес электронной почты и токен из скрытого поля. Пустое поле токена означает, что браузер или поставщик не поддерживает EVP или пользователь пропустил проверку. В этом случае вернитесь к существующему процессу подтверждения, например отправке одноразового кода или волшебной ссылки.
Если токен есть, проверьте его следующим образом:
- Проанализируйте токен с помощью библиотеки SD-JWT.
- Проверьте ожидаемые значения и утверждения сеанса.
- Проверьте делегирование DNS.
- Получение метаданных издателя и JWKS.
- Проверьте криптографические подписи и привязку ключей.
1. Как анализировать токен
Токен использует формат RFC 9901: Selective Disclosure JWT (SD-JWT+KB). Для синтаксического анализа и проверки токена используйте библиотеки, подходящие для вашей платформы.
Например, для Node можно использовать @sd-jwt/core и jose. В необработанном виде это выглядит так: подписанный издателем токен JWT, за которым следует ноль или более раскрытий, а затем токен JWT для связывания ключей. Каждый компонент разделен тильдой:
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
В текущей реализации токен не содержит раскрытия информации (<Issuer-signed EVT>~<Key Binding JWT>). Однако в будущем это может измениться.
Расшифруйте токен с помощью библиотеки:
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;
Если verifier.example подтверждает demo@provider.example, декодированный токен выглядит примерно так:
{
"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. Как проверить ожидаемые значения и утверждения сеанса
Убедитесь, что основные значения в полезной нагрузке соответствуют предоставленным и ожидаемым значениям:
email_verified: должно бытьtrue.email: должен совпадать с адресом электронной почты, указанным в форме.aud(аудитория) – должно совпадать с источником вашего сайта.nonce: должно совпадать с одноразовым кодом, указанным в форме.iat(время выпуска) иexp(срок действия). Убедитесь, что токен действителен и срок его действия не истек.
3. Проверьте делегирование DNS
Проверьте запись DNS _email-verification для домена адреса электронной почты. Например, для demo@gmail.com запросите запись TXT _email-verification.gmail.com. Для этого поставщика запрос возвращает местоположение поставщика аккаунта, то есть accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
Убедитесь, что схема издателя – https:// и что значение https://<domain> совпадает с утверждением iss в EVT.
4. Проверка подписи EVT
Получите метаданные обнаружения эмитента из 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"]
}
Если в метаданных есть поле issuer, убедитесь, что оно полностью совпадает с утверждением iss в EVT. Получите набор веб-ключей JSON из jwks_uri.
Используйте библиотеку SD-JWT, чтобы проверить пакет токенов. Библиотека координирует проверку:
- Проверка подписи издателя в EVT на соответствие полученному JWKS.
- Проверка подписи браузера в KB-JWT с помощью временного открытого ключа в
cnf.jwk. - Проверка привязки ключа (
aud,nonceи хеш дайджестаsd_hash).
Пример логики проверки в 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");
}
Если все шаги выполнены успешно, вы подтвердили адрес электронной почты у поставщика. Если подтверждение не удалось, отправьте пользователю письмо с подтверждением, как обычно.
Устранение неполадок
Если подтверждение не удалось или браузер не предоставил токен, проверьте, нет ли у вас следующих распространенных проблем:
Поле токена не заполнено.
- Регистрация пробной версии источника. Убедитесь, что на странице есть заголовок
Origin-Trialили тег<meta>и что срок действия токена не истек (токены, созданные до выхода расширения Chrome 160, перестанут действовать 17 ноября 2026 г.). Для сторонних экспериментов с источником (Chrome 154 и более поздних версий) зарегистрированный источник эксперимента должен быть того же сайта, что и издатель (https://<issuer-domain>). Вы можете проверить статус эксперимента с источником и срок действия токена на сайте в инструментах разработчика в разделе Приложение > Фреймы > (выберите нужный фрейм) > Эксперименты с источником. - Разметка формы. Теги
<input type="email" autocomplete="email">и<input type="hidden" autocomplete="email-verification-token" nonce="...">должны находиться в одном элементе<form>(не изолированном границами Shadow DOM), а тегnonceне должен быть пустым. - Ранняя отправка или повторное использование страницы. Браузер получает токен в фоновом режиме после того, как адрес электронной почты введен или подставлен автоматически. Если отправить форму до завершения запроса, токен останется пустым. Это может произойти, если пользователь нажмет клавишу возврата, чтобы отправить форму после ввода адреса электронной почты.
- Требования к браузеру и поставщику. Пользователь должен войти в аккаунт у участвующего поставщика в том же профиле браузера, а в настройках Chrome (
chrome://settings/contactInfo) должен быть включен параметр Подтвержденный адрес электронной почты.
Не удается проверить подпись эмитента.
- Отсутствует заголовок
kid. Утверждениеkid(идентификатор ключа) в заголовке EVT и JWKS необязательно (например, Gmail опускаетkid). Еслиkidотсутствует, переберите все ключи-кандидаты вjwks_uriиздателя, а не останавливайтесь на поиске идентификатора ключа. - Идентификаторы алгоритмов (
Ed25519иEdDSA). Начиная с Chrome 156, Chrome использует полностью указанный идентификатор алгоритмаEd25519(RFC 9864) для заголовковcnf.jwkиKB-JWT, а издатели и библиотеки могут указыватьEd25519илиEdDSA(наряду сES256). Убедитесь, что логика импорта и проверки JWK принимает оба идентификатора. - Формат источника Issuer (
iss). Запись DNS TXT (_email-verification.<domain>) содержит только имя хоста (iss=accounts.issuer.example), а утверждение EVTiss– полный источник HTTPS (https://accounts.issuer.example, без косой черты в конце). Перед сравнением добавьте к значению записи DNS префиксhttps://.
Не удалось выполнить проверку привязки ключа (KB-JWT)
- Несоответствие или истечение срока действия одноразового кода. Убедитесь, что код
nonce, отрисованный в теге<input>, соответствует одноразовому коду активного сеанса на вашем сервере и не был перезаписан другой вкладкой или использован в предыдущем запросе. - Несоответствие аудитории (
aud). Утверждениеaud– это источник HTTPS верификатора (https://verifier.exampleбез пути или косой черты в конце).
Не удалось сравнить утверждение адреса электронной почты (email)
- Регистр и канонизация. Chrome 156 и более поздние версии возвращают утверждение
emailв том виде, в котором оно было введено в форму, но более ранние версии браузера или поставщики могут возвращать канонизированный адрес (например,First.Last@example.comвместоfirst.last@example.com). При сопоставлении утвержденияemailтокена со значением, указанным в форме, используйте сравнение без учета регистра.