証明書利用者の実装

サイトでメール確認を実装するには、フォームのマークアップを更新してトークンをリクエストし、受信したトークンのサーバー側の検証を追加します。

オリジン トライアルに登録する

サイトを検証するには、サイトでオリジン トライアルが構成されている必要があります。

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 が アドレスを自動入力して認識できるようにします。
  • トークン フィールドの属性:
    • autocomplete="email-verification-token" を設定します。Chrome はこの フィールドを識別して、送信時にトークンを入力します。
    • nonce="<VALUE>" を設定します。サイトは、フォームの送信を検証するために、セッションにバインドされた一意の nonce を提供する必要があります。

メール確認トークン(EVT)を検証する

ユーザーがフォームを送信すると、サーバーはメールアドレスと非表示フィールドのトークンを受け取ります。トークン フィールドが空の場合、ブラウザまたはプロバイダが EVP をサポートしていないか、ユーザーが確認をスキップしたことを示します。この場合は、OTP やマジックリンクの送信など、既存の確認プロセスに戻ります。

トークンが存在する場合は、次のように検証します。

  1. SD-JWT ライブラリを使用してトークンを解析します。
  2. 想定される値とセッション クレームを検証します。
  3. DNS 委任を確認します。
  4. 発行元のメタデータを検出して JWKS を取得します。
  5. 暗号署名と鍵のバインディングを確認します。

1. トークンを解析する

トークンは、RFC 9901: Selective Disclosure JWT (SD-JWT+KB)形式を使用します。トークンの解析と検証には、プラットフォームに適したライブラリを使用します。 たとえば、Node の場合は @sd-jwt/core と jose を使用できます。生の形式は次のようになります。発行元が署名した JWT の後に、0 個以上の開示が続き、チルダで区切られた各コンポーネントを含む鍵バインディング 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: フォームで指定された nonce と一致する必要があります。
  • iat (発行時刻)と exp(有効期限): トークンが有効期間内であり、期限切れになっていないことを確認します。

3. DNS 委任を確認する

メールアドレスのドメインの _email-verification DNS レコードを確認します。たとえば、demo@gmail.com の場合は、_email-verification.gmail.com TXT レコードをクエリします。このプロバイダの場合、クエリはアカウント プロバイダの場所(accounts.google.com)を返します。

$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"

発行元のスキームが https:// であり、https://<domain> が EVT の iss クレームと一致していることを確認します。

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 フィールドが含まれている場合は、EVT の iss クレームとバイト単位で一致していることを確認します。jwks_uri から JSON Web Key Set を取得します。

SD-JWT ライブラリを使用してトークン パッケージを検証します。ライブラリは検証を調整します。

  1. 取得した JWKS に対して EVT の発行元の署名を検証します。
  2. cnf.jwk の一時的な公開鍵を使用して、KB-JWT のブラウザの署名を検証します。
  3. 鍵のバインディング(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 拡張機能の前に生成されたトークンは 11 月 17 日 2026 年に期限切れになります)。サードパーティのオリジン トライアル(Chrome 154 以降)の場合、登録されたトライアルの オリジンは発行元(https://<issuer-domain>)と同じサイトである必要があります。オリジン トライアルのステータスとトークンの有効期限は、デベロッパー ツールで [Application] > [Frames] >(関連するフレームを選択)> [Origin trials] で確認できます。
  • フォームのマークアップ: <input type="email" autocomplete="email"> と <input type="hidden" autocomplete="email-verification-token" nonce="..."> の両方が同じ <form> 要素内にある必要があります(Shadow DOM の境界を越えて分離されていない)。また、nonce は空にできません。
  • 早期送信または再利用されたページ: メールが入力または自動入力された後、ブラウザは バックグラウンドでトークンを取得します。リクエストが完了する前に送信すると、トークンが空になります。これは、ユーザーがメールを入力した後、Return キーを押してフォームを送信した場合に発生する可能性があります。
  • ブラウザとプロバイダの前提条件: ユーザーは、同じブラウザ プロファイルで 参加プロバイダにログインし、Chrome の設定(chrome://settings/contactInfo)で [Verified Email] を有効にする必要があります。

発行元の署名の検証に失敗する

  • kid ヘッダーがない: EVT ヘッダーと JWKS の kid(鍵 ID)クレームは省略可能です(たとえば、Gmail では kid が省略されます)。kid がない場合は、 鍵 ID の検索に失敗するのではなく、発行元の jwks_uri の候補となるすべての鍵を反復処理します。
  • アルゴリズム識別子(Ed25519 と EdDSA): Chrome 156 以降では、Chrome は cnf.jwk ヘッダーと KB-JWT ヘッダーに完全に指定された Ed25519 アルゴリズム識別子(RFC 9864)を使用しますが、発行元とライブラリは Ed25519 または EdDSA(ES256 とともに)を指定できます。JWK のインポートと検証のロジックで両方の識別子を受け入れるようにしてください。
  • 発行元(iss)のオリジン形式: DNS TXT レコード (_email-verification.<domain>)にはベアホスト名 (iss=accounts.issuer.example)が含まれますが、EVT iss クレームは完全な HTTPS オリジン(https://accounts.issuer.example、末尾のスラッシュなし)です。比較する前に、DNS レコード値に https:// を追加します。

鍵バインディング(KB-JWT)の検証に失敗する

  • nonce が一致しないか期限切れになっている: nonce でレンダリングされた <input> がサーバーのアクティブなセッション nonce と一致し、別のタブで上書きされていないか 、以前のリクエストで使用されていないことを確認します。
  • オーディエンス(aud)が一致しない: aud クレームは、検証者の HTTPS オリジン(https://verifier.example、パスまたは末尾のスラッシュなし)です。

メール クレーム(email)の比較に失敗する

  • 大文字と小文字の区別と正規化: Chrome 156 以降では、フォームに入力されたとおりに email クレームがバイト単位で返されますが、以前のブラウザ バージョンまたはプロバイダでは、正規化されたアドレス(たとえば、First.Last@example.com の場合は first.last@example.com など)が返されることがあります。トークンの email クレームを送信されたフォームの値と照合する場合は、大文字と小文字を区別しない比較を使用します。