メール プロバイダ(発行者)の実装

詳細については、モックメール プロバイダのデモコードを確認し、メール確認 API と メール確認 Protocol の提案に記載されている発行者の手順を参照してください。

発行元は、オリジン トライアルに登録したり、トークンを提供したりする必要はありません。これは、証明書利用者サイトがブラウザの動作をトリガーするためです。これらのリクエストに応答するようにエンドポイントが構成されていることを確認します。

発行者の検出を構成する

ドメインに属するメールアドレスが選択されたときに、ブラウザが検証エンドポイントを自動的に検出できるようにするには、DNS と .well-known HTTP エンドポイントを使用して構成を公開します。

DNS 委任レコードを構成する

発行者 ID に検証権限を委任する DNS TXT レコードをメールドメインに構成します。これらの識別子は、インフラストラクチャに応じて同じドメインを使用できます。

レコード形式: _email-verification.<email-domain>

ゾーンファイルの例:

_email-verification.example.com IN TXT "iss=accounts.issuer.example"

iss= 値は、スキーム(https://)、ポート、パス、大文字を含まない、正規の小文字のホスト名(例: iss=accounts.issuer.example)にする必要があります。Chrome は、ホスト名以外のコンポーネントを含むレコードを拒否します。

.well-known/email-verification エンドポイントをホストする

/.well-known/ パスの発行元ドメインで JSON メタデータ ファイルをホストします。このファイルには、発行機能と、インフラストラクチャがサポートする暗号署名アルゴリズムの概要が記載されています。

エンドポイント: 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: トークン発行 POST リクエストを受信する HTTPS URL。
  • jwks_uri: 公開 JSON Web Key Set(JWKS)を提供する HTTPS URL。
  • signing_alg_values_supported: サポートされている JWS 署名アルゴリズムの配列。

.well-known/web-identity エンドポイントをホストする

Federated Credentials(FedCM)API の一部として、追加の .well-known JSON リソースをすでに実装している可能性があります。このリソースは、アカウント エンドポイントとログイン URL へのリンクを提供します。

エンドポイント: https://<domain>/.well-known/web-identity

レスポンスの例:

{
  "accounts_endpoint": "https://accounts.issuer.example/accounts",
  "login_url": "https://accounts.issuer.example/login"
}

accounts エンドポイントを使用する

FedCM API のアカウント エンドポイントは、現時点でログインしているアカウントのリストを提供します。次の例は、最小限のレスポンスを示しています。詳しくは、ID プロバイダの実装ガイドをご覧ください。

エンドポイント: .well-known/web-identity で指定

レスポンスの例を次に示します。

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

ログイン ステータス API と統合する

ユーザーはプロバイダとのアクティブなセッションを保持している必要があり、ログイン ステータス API を使用してブラウザにそのことを通知する必要があります。

ユーザーがログインまたはログアウトに成功したら、一致する HTTP レスポンス ヘッダーを返します。

Set-Login: logged-in
Set-Login: logged-out

または、ウェブ アプリケーションのコンテキストで JavaScript を使用してステータスを更新します。

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

発行リクエストを処理する

issuance_endpoint は、email キーと Signature、Signature-Input、Signature-Key の HTTP メッセージ署名ヘッダーを含む application/json POST リクエストを受信します。

環境で構造化ヘッダーと 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 ヘッダーの hwk パラメータに alg="Ed25519" が含まれます。"Ed25519" と "EdDSA" を受け入れ、以前の Chrome バージョンで alg を省略できるようにします。
  • ペイロード: JSON 本文には、検証用にリクエストされた email 文字列が含まれています。

発行レスポンス

セッションとリクエスト トークンの検証が成功したら、プラットフォームに適したライブラリを使用して、JSON として返される署名付きの選択的開示 JWT(SD-JWT)を生成します。たとえば、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 は、ユーザーがログインしていることがわかっている場合にのみエンドポイントにクエリを実行します。ログインフローで Set-Login: logged-in HTTP ヘッダーが設定されるか、navigator.login.setStatus("logged-in") が呼び出されるようにします。
  • セッション Cookie がブロックされている(SameSite=None): ブラウザは、別のサイトの証明書利用者から accounts_endpoint と issuance_endpoint を取得します。これらはクロスサイト リクエストであるため、セッション Cookie に SameSite=None; Secure を含める必要があります。SameSite=Lax Cookie は、同じサイトの検証ツールでテストすると機能しますが、クロスサイト リクエストでは省略されます。
  • 検出またはアカウントの不一致: _email-verification.<email-domain> が正規の小文字のホスト名(iss=<issuer-domain>、https://、ポート、パス、大文字なし)を含む単一の TXT レコードを返すこと、両方の .well-known エンドポイントが Content-Type: application/json を返すこと、.well-known/email-verification に https://<issuer-domain> とバイト単位で一致する issuer があること、accounts_endpoint レスポンスに email が入力されたアドレスと一致するアカウントが含まれていることを確認します。
  • .well-known/email-verification でサポートされていない署名アルゴリズム: Chrome 154 と 155 では signing_alg_values_supported で "EdDSA" が必要ですが、Chrome 156 以降と IETF 仕様では "Ed25519" がサポートされています。 移行中は両方の ["Ed25519", "EdDSA"] をアドバタイズして、Chrome Stable が検出メタデータを拒否しないようにします。

発行リクエストの検証が失敗する

  • Sec-Fetch-Dest ヘッダーのスペル: Chrome 154 以降では Sec-Fetch-Dest: email-verification(ハイフンあり)が送信されますが、Chrome 153 では emailverification(ハイフンなし)が送信されていました。ロールアウト中に両方の値を受け入れます。
  • プロキシの背後での HTTP メッセージ署名(@authority)の不一致: RFC 9421 署名を検証するときに、@authority コンポーネントは一般公開ホストを反映します。サーバーがリバース プロキシまたはロードバランサの背後にある場合は、内部ホスト名ではなく X-Forwarded-Host(または公開オリジン)を使用して確認用 URL を再構築し、JSON 解析の前に未加工のリクエスト本文のバイトに対して Content-Digest を計算します。

ブラウザが返された issuance_token を拒否する

  • 変更または正規化された email クレーム: Chrome 156 以降、ブラウザは EVT email クレームがリクエストされた email とバイト単位で一致することを確認します。バックエンドがアドレスを正規のアカウント形式に正規化する場合(first.LAST@example.com がリクエストされたときに First.Last@example.com を返すなど)、Chrome はトークンを破棄します。リクエストをユーザーのアカウントと照合しますが、リクエスト本文で受信した正確な email 文字列を返します。
  • 末尾のチルダ(~)がない: 開示が 1 つもない場合でも、issuance_token は末尾にチルダ(<Issuer-signed-JWT>~)が付いた有効な SD-JWT でなければなりません。そうすることで、ブラウザが <KB-JWT> を追加できるようになります。
  • iss または cnf.jwk の不一致: EVT iss クレームが、.well-known/email-verification メタデータと一致する正確な HTTPS オリジン(https://<issuer-domain>、末尾のスラッシュなし)であり、cnf.jwk が Signature-Key ヘッダーからブラウザの一時的な公開鍵を埋め込んでいることを確認します。