サイトでメール確認を実装するには、フォームのマークアップを更新してトークンをリクエストし、受信したトークンのサーバー側の検証を追加します。
オリジン トライアルに登録する
サイトを検証するには、サイトでオリジン トライアルが構成されている必要があります。
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 やマジックリンクの送信など、既存の確認プロセスに戻ります。
トークンが存在する場合は、次のように検証します。
- SD-JWT ライブラリを使用してトークンを解析します。
- 想定される値とセッション クレームを検証します。
- DNS 委任を確認します。
- 発行元のメタデータを検出して JWKS を取得します。
- 暗号署名と鍵のバインディングを確認します。
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 ライブラリを使用してトークン パッケージを検証します。ライブラリは検証を調整します。
- 取得した JWKS に対して EVT の発行元の署名を検証します。
cnf.jwkの一時的な公開鍵を使用して、KB-JWT のブラウザの署名を検証します。- 鍵のバインディング(
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)が含まれますが、EVTissクレームは完全な 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クレームを送信されたフォームの値と照合する場合は、大文字と小文字を区別しない比較を使用します。