Дополнительную информацию можно найти в демокоде имитации поставщика услуг электронной почты, а также в предложениях по API подтверждения адреса электронной почты и протоколу подтверждения адреса электронной почты.
Как эмитенту, вам не нужно регистрироваться в эксперименте с источником или предоставлять токен, поскольку поведение браузера запускается сайтом доверяющей стороны. Убедитесь, что ваши конечные точки настроены на ответы на эти запросы.
Как настроить обнаружение эмитентов
Чтобы браузеры могли автоматически обнаруживать ваши конечные точки проверки при выборе адреса электронной почты, принадлежащего вашему домену, предоставьте доступ к конфигурации с помощью DNS и конечной точки HTTP .well-known.
Как настроить запись делегирования DNS
Настройте запись DNS TXT в домене электронной почты, которая делегирует полномочия по проверке вашему идентификатору издателя. Эти идентификаторы могут использовать один и тот же домен в зависимости от вашей инфраструктуры.
Формат записи: _email-verification.<email-domain>
Пример файла зоны:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
Значение iss= должно быть каноническим именем хоста в нижнем регистре (например, iss=accounts.issuer.example) без схемы (https://), порта, пути или символов в верхнем регистре. Chrome отклоняет записи, содержащие компоненты, отличные от имени хоста.
Разместите конечную точку .well-known/email-verification
Разместите файл JSON с метаданными в домене эмитента по пути /.well-known/.
В этом файле описываются ваши возможности по выпуску сертификатов и алгоритмы криптографической подписи, которые поддерживает ваша инфраструктура.
Конечная точка: https://<issuer-domain>/.well-known/email-verification
Пример ответа:
{
"issuer": "https://accounts.issuer.example",
"issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
"jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["Ed25519", "EdDSA", "ES256"]
}
Свойства метаданных:
issuer: источник эмитента (https://<issuer-domain>без косой черты в конце). Должен совпадать с источником, из которого передается файл метаданных, байт в байт.issuance_endpoint– URL по HTTPS, на который поступают запросыPOSTна выпуск токенов.jwks_uri– URL по HTTPS, по которому размещен ваш общедоступный набор ключей JSON Web Key Set (JWKS).signing_alg_values_supported: массив поддерживаемых алгоритмов подписи JWS.
Разместите конечную точку .well-known/web-identity
Возможно, вы уже реализовали дополнительный ресурс JSON .well-known в рамках Federated Credentials (FedCM) API. Этот ресурс содержит ссылки на конечную точку аккаунтов и URL входа.
Конечная точка: https://<domain>/.well-known/web-identity
Пример ответа:
{
"accounts_endpoint": "https://accounts.issuer.example/accounts",
"login_url": "https://accounts.issuer.example/login"
}
Использование конечной точки accounts
Конечная точка accounts из FedCM API предоставляет список аккаунтов, в которые выполнен вход. Ниже приведен пример минимального ответа. Дополнительную информацию можно найти в руководстве по внедрению поставщика идентификационной информации.
Конечная точка: как указано в .well-known/web-identity.
Ниже приведен пример ответа.
{
"accounts": [
{
"id": "demo-example",
"name": "Demo User",
"email": "demo@example.com",
"given_name": "Demo"
}
]
}
Интеграция с Login Status API
У пользователя должен быть активный сеанс с поставщиком, и вы должны сообщить об этом браузеру с помощью Login Status API.
Когда пользователь выполняет вход или выход, отправляйте соответствующий заголовок HTTP-ответа:
Set-Login: logged-in
Set-Login: logged-out
Вы также можете обновить статус с помощью JavaScript в контексте веб-приложения:
navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");
Как обрабатывать запросы на выпуск
Ваш issuance_endpoint получает запрос application/json POST, который содержит ключ email и заголовки подписей HTTP-сообщений для Signature, Signature-Input и Signature-Key.
Используйте библиотеку, которая поддерживает структурированные заголовки и подписи HTTP-сообщений для вашей среды. В Node.js можно использовать structured-headers и http-message-sig.
Полный формат запроса:
POST /email-verification/issuance HTTP/1.1
Host: provider.example
Accept: application/json
Content-Digest: sha-256=:aBc123aBc123aBc123aBc123aBc123=:
Content-Type: application/json
Sec-Fetch-Dest: email-verification
Signature: sig=:+dEf567dEf567/dEf567dEf567dEf567/dEf567==:
Signature-Input: sig=("@method" "@authority" "@path" "content-digest" "signature-key");created=1786455840
Signature-Key: sig=hwk;alg="Ed25519";crv="Ed25519";kty="OKP";x="gHi890_gHi890_gHi890"
{email: "demo@example.com"}
Проанализируйте и проверьте запрос:
- Аутентификация сеанса. Проверьте собственные файлы cookie сеанса, отправленные вместе с запросом. Пользователь должен пройти аутентификацию.
- Заголовок
Sec-Fetch-Dest: задайте значениеemail-verification. - Подписи HTTP-сообщений. Проверьте подпись запроса, используя временный открытый ключ в
Signature-Key, и подтвердитеContent-Digest. Начиная с Chrome 156 заголовокSignature-Keyвключаетalg="Ed25519"в параметрахhwk. Принимайте"Ed25519"и"EdDSA"и разрешайте опускатьalgв более ранних версиях Chrome. - Полезная нагрузка. Тело JSON содержит строку
email, запрошенную для подтверждения.
Ответ на запрос о выпуске
После успешной проверки сеанса и токена запроса сгенерируйте подписанный веб-токен JSON с выборочным раскрытием (SD-JWT), возвращаемый в формате JSON, используя подходящие библиотеки для вашей платформы. Например, для Node можно использовать @sd-jwt/core и jose.
Формат необработанной полезной нагрузки должен выглядеть примерно так:
{
"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
}
Создайте, подпишите и верните токен:
import { importJWK, CompactSign } from "jose";
import { SDJwtInstance } from "@sd-jwt/core";
import crypto from "node:crypto";
// Issuer private key from secure storage
const privateKey = await importJWK(PRIVATE_KEY_JWK, "EdDSA");
const origin = url.origin;
const currentTime = Math.floor(Date.now() / 1000);
const evtPayload = {
iss: origin,
iat: currentTime,
exp: currentTime + 300, // 5 minutes
cnf: {
jwk: browserJwk,
},
email: payload.email, // exactly as received in payload
email_verified: true,
};
const sdJwt = new SDJwtInstance({
signer: async (data) => {
const [headerB64, payloadB64] = data.split(".");
const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
const payload = Buffer.from(payloadB64, "base64url");
const signed = await new CompactSign(payload).setProtectedHeader(header).sign(privateKey);
return signed.split(".").pop()!;
},
signAlg: "EdDSA",
hasher: async (data, alg) => {
const nodeAlg = alg.replace("-", "");
return new Uint8Array(crypto.createHash(nodeAlg).update(data).digest());
},
hashAlg: "sha-256",
saltGenerator: async () => crypto.randomBytes(16).toString("base64url"),
});
const issuanceToken = await sdJwt.issue(evtPayload, undefined, {
header: {
alg: "EdDSA",
kid: PRIVATE_KEY_JWK.kid,
typ: "evt+jwt",
},
});
return sendResponse({ issuance_token: issuanceToken, }, 200);
Тело ответа будет выглядеть примерно так:
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
После того как вы создадите и подпишете токен подтверждения адреса электронной почты, браузер передаст его на сайт верификатора для проверки.
Устранение неполадок
Если браузер не связывается с вашими конечными точками или отклоняет выпущенные токены, проверьте, не возникли ли следующие распространенные проблемы:
Браузер не вызывает accounts_endpoint или issuance_endpoint
- Статус входа не задан. Chrome отправляет запросы к конечным точкам, только если пользователь вошел в аккаунт. Убедитесь, что в процессе входа задается HTTP-заголовок
Set-Login: logged-inили вызываетсяnavigator.login.setStatus("logged-in"). - Сеансовые файлы cookie заблокированы (
SameSite=None). Браузер получает ваши файлыaccounts_endpointиissuance_endpointот проверяющей стороны на другом сайте. Поскольку это межсайтовые запросы, файл cookie сеанса должен содержатьSameSite=None; Secure. Файл cookieSameSite=Laxработает при тестировании на верификаторе того же сайта, но опускается при межсайтовых запросах. - Несоответствие аккаунта или ошибки обнаружения. Убедитесь, что
_email-verification.<email-domain>возвращает одну запись TXT с каноническим именем хоста в нижнем регистре (iss=<issuer-domain>безhttps://, порта, пути или символов в верхнем регистре), оба конечных пункта.well-knownвозвращаютContent-Type: application/json,.well-known/email-verificationсодержитissuer, который полностью совпадает сhttps://<issuer-domain>, а ответaccounts_endpointвключает аккаунт,emailкоторого соответствует введенному адресу. - Неподдерживаемый алгоритм подписи в
.well-known/email-verification: В Chrome 154 и 155 требуется"EdDSA"вsigning_alg_values_supported, а в Chrome 156 и более поздних версиях, а также в спецификации IETF поддерживается"Ed25519". Во время перехода используйте оба значения["Ed25519", "EdDSA"], чтобы стабильная версия Chrome не отклоняла метаданные обнаружения.
Не удалось подтвердить запрос на выпуск
Sec-Fetch-Dest: Chrome 154 и более поздние версии отправляют заголовокSec-Fetch-Dest: email-verification(с дефисом), а Chrome 153 отправлял заголовокemailverification(без дефиса). Во время развертывания принимайте оба значения.- Несоответствие подписи сообщения HTTP (
@authority) за прокси-сервером. При проверке подписи RFC 9421 компонент@authorityотражает общедоступный хост. Если ваш сервер находится за обратным прокси-сервером или балансировщиком нагрузки, восстановите URL подтверждения, используяX-Forwarded-Host(или ваш общедоступный источник), а не внутреннее имя хоста, и вычислитеContent-Digestпо необработанным байтам тела запроса перед синтаксическим анализом JSON.
Браузер отклоняет возвращенный файл issuance_token
- Измененное или канонизированное утверждение
email. Начиная с версии Chrome 156 браузер проверяет, что утверждениеemailв EVT побайтово совпадает с запрошеннымemail. Если ваш сервер нормализует адрес до канонического формата аккаунта (например, возвращаетFirst.Last@example.com, когда запрашиваетсяfirst.LAST@example.com), Chrome удаляет токен. Сопоставьте запрос с аккаунтом пользователя, но верните точную строкуemail, полученную в теле запроса. - Отсутствует завершающая тильда (
~). Даже если раскрытия информации не происходит,issuance_tokenдолжен быть действительным SD-JWT, заканчивающимся тильдой (<Issuer-signed-JWT>~), чтобы браузер мог добавить<KB-JWT>. - Несоответствие
issилиcnf.jwk. Убедитесь, что утверждениеissв EVT – это точный источник HTTPS (https://<issuer-domain>, без косой черты в конце), соответствующий вашим метаданным.well-known/email-verification, аcnf.jwkсодержит временный открытый ключ браузера из заголовкаSignature-Key.