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

Rowan Merewood

發布日期：2026 年 7 月 8 日，上次更新日期：2026 年 10 月 5 日

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

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

Email Verification API 使用者提示試用版
電子郵件驗證 API 使用者提示示範

收集電子郵件地址是使用者歷程中的重要轉換點，因此 Chrome 希望能收到意見回饋，瞭解網站 (想驗證電子郵件地址)、電子郵件服務供應商 (可執行驗證) 和使用者 (體驗這個程序) 對這項提案的看法。您可以立即申請加入來源試用，並按照此處的實作說明操作。如需來源試用計畫的一般設定，請參閱「開始使用來源試用計畫」。

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

電子郵件驗證流程

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

重要詞彙

電子郵件驗證 API 的主要字詞如下：

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

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

電子郵件驗證流程架構
電子郵件驗證流程架構

必要條件

  • 使用者必須在同一個瀏覽器設定檔中登入電子郵件服務供應商或發卡機構。舉例來說，如果他們使用 Gmail，就必須登入 Google 帳戶。
  • 參與驗證的網站必須註冊原始碼試用，並在電子郵件表單所在的頁面提供權杖。

  • 使用者必須從自動填入或自動完成的下拉式選單中選取電子郵件地址。

    • 如果使用者先前曾在欄位中輸入電子郵件地址，系統會透過自動完成功能提供該地址。

    • 如果使用者已透過 Chrome 設定的「自動填入和密碼」頁面 (chrome://settings/autofill) 新增電子郵件地址，系統就會透過自動填入功能提供該地址。

  • 使用者首次提供電子郵件地址進行驗證時，系統會顯示權限提示。每個電子郵件地址只會收到一次。

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

  1. 在含有電子郵件地址欄位的表單中，使用者可以從自動完成下拉式選單中選取電子郵件地址。驗證者網站會在表單中提供隱藏欄位，並使用每個例項的隨機值來驗證這項要求。

  2. 瀏覽器接著會擷取電子郵件網域的電子郵件驗證 DNS 記錄。這會將瀏覽器指向簽發者。發行者隨後會確認該電子郵件地址是否處於有效工作階段。

  3. 發行者隨後會提供地址的電子郵件驗證權杖 (EVT)。瀏覽器會將這些資訊與 EVT、網站來源和輸入表單中的隨機值合併為繫結金鑰的 JWT。

  4. 表單提交後，EVT 套件會新增至隱藏欄位，並傳送至網站。

  5. 驗證者網站接著會驗證各項詳細資料：預期電子郵件地址、隨機數，以及來自瀏覽器和發行者的簽章。

  6. 使用者會看到一則簡短通知，指出電子郵件供應商已驗證其地址。

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

使用者可以依序前往「設定」 >「自動填入和密碼」 >「聯絡資訊」 >「已驗證的電子郵件」 (或開啟 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"。瀏覽器會使用這項屬性，找出要填入的欄位。

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

驗證 EVT

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

  1. 剖析權杖。
  2. 驗證預期值。
  3. 驗證按鍵繫結。
  4. 驗證 DNS 記錄。
  5. 找出簽發者並驗證 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"
    }
  ]
}

整合 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 會收到包含 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 存放區：

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

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

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

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