Реализация поставщика услуг электронной почты (эмитента)

Дополнительную информацию можно найти в демокоде имитации поставщика услуг электронной почты, а также в предложениях по 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. Файл cookie SameSite=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.