Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

透過原始碼試用測試電子郵件驗證通訊協定

Rowan Merewood

發布日期：2026 年 7 月 8 日

在註冊、登入、訂閱、結帳、帳戶復原或其他程序中收集電子郵件地址時，一般做法是確認電子郵件地址屬於輸入者本人。現有的驗證方法 (例如一次性密碼或電子郵件驗證連結 (神奇連結))，都需要使用者離開網站。這個干擾性程序可能會增加使用者 (無論是真人或代理程式) 完全放棄工作階段，且永遠不會完成驗證程序的風險。

電子郵件驗證 API 提案可讓瀏覽器直接與電子郵件供應商通訊，驗證使用者是否擁有該電子郵件地址。使用者從瀏覽器的自動填入或自動完成建議中選取電子郵件地址，提交表單，網站就會向供應商驗證電子郵件地址，不會傳送電子郵件或中斷使用者的流程。

電子郵件驗證 API 使用者提示試用版 — 電子郵件驗證 API 使用者提示範例

收集電子郵件地址是使用者歷程中的重要轉換點，Chrome 希望能收到網站、可執行驗證的電子郵件服務供應商，以及體驗過這項程序的使用者提供的意見。您今天就能申請參與原始碼試用計畫，並按照這裡的實作說明操作。如需一般來源試用計畫設定，請參閱「開始使用來源試用計畫」。

您可以透過示範帳戶試用流程：

發行者試用版提供模擬電子郵件帳戶和工作階段
驗證器示範會驗證任何參與的供應商

電子郵件驗證流程

以下各節說明您和使用者啟動電子郵件驗證流程時必須完成的事項，以及使用電子郵件驗證通訊協定時的完整工作流程。

重要詞彙

Email Verification API 的主要字詞如下：

驗證者：收集電子郵件地址並想驗證該地址的網站。驗證者也稱為「信賴方」。
電子郵件供應商：提供使用者電子郵件地址的服務，例如 gmail.com。
核發機構：管理使用者電子郵件帳戶的服務，例如 accounts.google.com。發行者也稱為「身分識別提供者」。

在某些情況下，電子郵件服務供應商和發行者可能來自相同網域。不過，請務必區分電子郵件地址和相關聯帳戶的有效工作階段。

必要條件

使用者必須在同一個瀏覽器設定檔中登入電子郵件供應商或發行者。舉例來說，如果他們使用 Gmail，就必須登入 Google 帳戶。
參與驗證的網站必須註冊原始碼試用計畫，並在電子郵件表單所在的頁面提供權杖。
使用者必須從自動填入或自動完成的下拉式選單中選取電子郵件地址。
- 如果使用者先前曾在該欄位輸入電子郵件地址，系統會透過自動完成功能提供該地址。
- 如果使用者已透過 Chrome 設定「自動填入和密碼」新增電子郵件地址 (chrome://settings/autofill)，系統會透過自動填入功能提供該地址。
  
  注意： 我們預計在日後推出的版本中，支援手動輸入地址。
使用者首次提供電子郵件地址進行驗證時，會看到權限提示。每個電子郵件地址只會發生一次。

使用者在瀏覽器中啟動有效工作階段後，即可開始進行以下程序：

在含有電子郵件欄位的表單中，使用者可以從自動完成下拉式選單中選取電子郵件地址。驗證者網站會在表單中提供隱藏欄位，並附上每個例項的隨機數，以驗證這項要求。
然後，瀏覽器會擷取電子郵件網域的電子郵件驗證 DNS 記錄。這會將瀏覽器指向簽發機構。發卡機構隨後會確認該電子郵件地址是否處於有效工作階段。

注意： 這些要求不會揭露使用者的任何其他資訊。驗證者網站不會在這個步驟中收到資訊。發行者只會看到驗證使用者是否存在的請求，不會看到發出請求的網站。
發行者隨後會提供地址的電子郵件驗證權杖 (EVT)。瀏覽器會將這些資訊與 EVT、網站來源和輸入表單中的隨機值合併為金鑰繫結 JWT。
表單提交後，EVT 套件會新增至隱藏欄位，並傳送至網站。
驗證者網站接著會驗證這些詳細資料：預期的電子郵件地址、隨機數，以及來自瀏覽器和發行者的簽章。
使用者會看到小型通知，告知電子郵件供應商已驗證地址。

這個程序會向驗證網站確認電子郵件地址有效且屬於目前使用者，因此網站可以略過傳送驗證電子郵件的步驟。

使用者可以依序前往「設定」 >「自動填入和密碼」 >「聯絡資訊」 >「已驗證的電子郵件地址」 (或開啟 chrome://settings/contactInfo)，管理已驗證的電子郵件地址。

使用注意事項

電子郵件驗證是現有流程的漸進式強化功能，可讓使用者不必離開網站即可擷取一次性密碼或點選連結。網站可以在所有相關表單中加入電子郵件驗證欄位，例如登入、訂閱電子報、建立帳戶和密碼復原表單。只有在瀏覽器支援的情況下，才會觸發 EVP。如果提交後未收到驗證碼，或任何驗證步驟失敗，您可以改用預設的電子郵件確認流程。這也表示系統不會偵測 API 的功能；驗證網站會將 EVT 視為選用項目，如果要求中含有 EVT，就會處理該項目。

電子郵件驗證可確認使用者是否與電子郵件地址供應商有有效的工作階段。但不會驗證電子郵件是否送達使用者。您可能仍想傳送現有的歡迎或新手上路電子郵件，並可能想或需要提示使用者檢查垃圾郵件設定。

實作驗證網站

如需更多詳細資料，請參閱端對端示範程式碼，並參考「電子郵件驗證 API」和「電子郵件驗證通訊協定」提案中的驗證步驟。

設定表單欄位

確認表單欄位具有正確的屬性：

<input
  name="email-address"
  type="email"
  autocomplete="email">
<input
  type="hidden"
  name="token"
  nonce="rAnD0m-VaLuE"
  autocomplete="email-verification-token">

將 email 輸入內容的 type 和 autocomplete 屬性設為 email，讓瀏覽器提供電子郵件地址的自動完成功能。

提交表單後，新的 hidden 欄位會填入電子郵件驗證權杖。必要屬性包括：

設定 type="hidden"，因為這個欄位不需要使用者輸入內容。
請設定 nonce="rAnD0m-VaLuE"。網站必須提供與工作階段綁定的專屬隨機碼，以驗證表單提交。
請設定 autocomplete="email-verification-token"。瀏覽器會使用這項屬性來識別要填入的欄位。

在開發人員工具中檢查「網路」面板，驗證表單元素。選取電子郵件地址後，瀏覽器會觸發 DNS，並隨後對電子郵件供應商和發行者發出帳戶查詢。這些是瀏覽器內部要求，網站不會收到任何內容，直到表單提交為止。

驗證 EVT

驗證 EVT 套件的每個元件需要五個步驟。

剖析權杖。
驗證預期值。
驗證金鑰繫結。
驗證 DNS 記錄。
找出核發者並驗證 EVT 簽章。

1. 剖析權杖

表單提交的原始資料包含 EVT 和簽署的聲明，以半形波浪號 (~ 字元) 分隔，並採用選擇性揭露 JSON Web Token (SD-JWT+KB) 格式。您需要將這些標頭和酬載分開，並解碼 JavaScript 物件簽署和加密 (JOSE) 標頭和酬載 (例如使用 Node.js 的 jose)。

如果 example.com 驗證 demo@gmail.com，解碼後的酬載會類似以下範例：

{
  "evtJwtDecodedPayload": {
    "cnf": {
      "jwk": {
        "crv": "Ed25519",
        "kty": "OKP",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@gmail.com",
    "email_verified": true,
    "iat": 1782911685,
    "iss": "https://accounts.google.com"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://example.com",
    "iat": 1782911685,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  }
}

2. 驗證預期值

確認酬載中的基本值與您提供的值相符：

確認 email_verified 已設為 true。
確認 email 與您在表單中提供的電子郵件地址相符。
確認 nonce 與表單中提供的隨機值相符。
確認 aud 與網站來源相符。
確認 iat 的時間戳記相對較新，例如在表單算繪後。

3. 驗證金鑰繫結

瀏覽器會為交易建立暫時性金鑰，確認已簽署權杖。從 EVT 的 cnf (確認) 聲明中擷取這組金鑰，然後用來驗證與金鑰綁定的 JWT。

接著，計算預期雜湊並與 sd_hash 聲明比較。以下 Node.js 範例說明如何執行這項計算：

const calculatedHash = createHash("sha256")
        .update(evtJwt + "~")
        .digest("base64url");

4. 驗證 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"

5. 找出核發者並驗證 EVT 簽章

請確認簽發者提供 /.well-known/email-verification 資源，其中包含核發權杖的端點、網站的 JSON Web Key (JWK)，以及支援的簽署演算法。

$ curl https://accounts.google.com/.well-known/email-verification
{
  "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": ["EdDSA"]
}

使用 JWK 驗證從權杖擷取的 EVT JWT。大多數 JOSE 程式庫都提供處理這項驗證的函式。

如果這五個步驟都成功，表示您已向供應商驗證電子郵件地址。如果不是，請按照一般流程傳送確認電子郵件給使用者。

導入電子郵件提供者和發行者服務

如需更多詳細資料，您可以逐步瞭解模擬電子郵件服務供應商的程式碼，並參閱「電子郵件驗證 API」和「電子郵件驗證通訊協定」提案中的簽發者步驟。

身為發行者，您不需要註冊原始碼試用或提供權杖，因為瀏覽器行為是由信賴方網站觸發。您只需要確保有預期的端點，可回應這些要求。

設定簽發機構探索

如要讓瀏覽器在選取網域所屬的電子郵件地址時，自動探索驗證端點，請使用 DNS 和 .well-known HTTP 端點公開設定。

設定 DNS 委派記錄

在電子郵件網域中設定 DNS TXT 記錄，將驗證授權委派給發行者 ID。視基礎架構而定，這些 ID 可以使用相同網域。

記錄格式：_email-verification.<email-domain>

區域檔案範例：

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

代管 `.well-known/email-verification` 端點

在發行者網域的 /.well-known/ 路徑下代管 JSON 中繼資料檔案。這個檔案會列出您的發行功能，以及基礎架構支援的密碼編譯簽署演算法。

端點：https://<issuer-domain>/.well-known/email-verification

回應範例：

{
  "issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
  "jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["EdDSA", "ES256"]
}

代管 `.well-known/web-identity` 端點

您可能已實作額外的 .well-known JSON 資源，做為聯邦憑證 (FedCM) API 的一部分。這會提供帳戶端點和登入網址的連結。

端點：https://<domain>/.well-known/web-identity

回應範例：

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

使用帳戶端點

FedCM API 的帳戶端點目前會提供已登入帳戶的清單。以下範例顯示最少的回應。詳情請參閱身分識別提供者導入指南。

端點：如 .well-known/web-identity 中所述

以下是回應範例：

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

整合登入狀態 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 會收到包含 request_token 的 application/x-www-form-urlencoded POST 要求。

以下各節說明處理核發要求的完整程序。

1. 驗證核發要求

剖析及驗證傳入的瀏覽器酬載：

方法： POST
工作階段驗證：驗證與要求一併傳輸的使用者第一方 Cookie，確保存在有效的授權身分環境。session/authentication
參數驗證：擷取 request_token 參數 (瀏覽器產生的已簽署 JWT)。確認其中包含預期的暫時公開金鑰、目標電子郵件、正確的目標對象和有效時間戳記。

解碼後的權杖應如下所示：

{
  "decodedHeader": {
    "alg": "ES256",
    "typ": "JWT",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "decodedPayload": {
    "iss": "https://accounts.issuer.example",
    "sub": "demo@example.com",
    "email": "demo@example.com",
    "iat": 1780272000,
    "exp": 1780272300
  },
  "signature": "SIGnatURE-123_SIGnatURE-123_SIGnatURE-123"
}

2. 使用權杖回覆

成功驗證工作階段和要求權杖後，請使用酬載產生已簽署的選擇性揭露 JWT (SD-JWT)：

{
  "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
}

使用私密金鑰和支援的演算法簽署酬載。舉例來說，在 Node.js 中使用 jose：

const evtJwt = await new SignJWT(evtPayload)
   .setProtectedHeader({
     alg: "EdDSA",
     kid: PRIVATE_KEY_JWK.kid, // Key ID corresponding to our JWKS keys
     typ: "evt+jwt", // Standard Token Type for EVTs
   })
   .sign(privateKey);

 // Standard SD-JWT compatibility requires appending a trailing tilde "~"
 // to separate the signed token from the key binding section.
 const issuanceToken = `${evtJwt}~`;

成功回應範例 (HTTP 200)：

{
  "issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}

來源試用注意事項

原始碼試用是為了收集意見回饋而進行的實驗，因此如果您以信賴方或身分識別提供者的身分參與，您的意見就非常重要。如要回報問題，請使用下列 GitHub 存放區：

瀏覽器電子郵件驗證 API：WICG/email-verification
電子郵件驗證通訊協定：dickhardt/email-verification

如果 Chrome 實作項目發生錯誤，請針對下列元件提出錯誤報告：

新問題：Chromium > Blink > Identity > EVP

您可透過納入 OT 權杖，逐一控制是否啟用原始碼試用功能。也就是說，如果您只想開放部分使用者存取這項功能，就能精細控管。舉例來說，如果您已有 A/B 測試架構，可以將原始碼試用整合至該架構，以控制實驗族群。或者，如果您有 Beta 版測試或搶先預覽使用者群組，可能需要為他們啟用這項功能。在這種情況下，請先根據提供的電子郵件地址進行檢查，再核發或驗證權杖。

來源試用程序也有流量限制，可盡量減少網站在上線前依賴這項功能。發行者 API 仍在開發階段，因此隨著 Chrome 使用者體驗更新，您可能會遇到不相容的變更。

開發作業有任何進展，我們都會在這個網誌和 evp-announce@chromium.org 郵寄清單中發布最新消息。