การใช้งาน Relying Party

หากต้องการใช้การยืนยันอีเมลในเว็บไซต์ ให้อัปเดตมาร์กอัปของแบบฟอร์มเพื่อขอโทเค็นและเพิ่มการตรวจสอบฝั่งเซิร์ฟเวอร์สำหรับโทเค็นขาเข้า

ลงทะเบียนเข้าร่วมช่วงทดลองใช้จากต้นทาง

เว็บไซต์ที่ยืนยันแล้วต้องมีการกำหนดค่าช่วงทดลองใช้จากต้นทางในเว็บไซต์

Chrome 154 เป็นต้นไปรองรับ ช่วงทดลองใช้จากต้นทางของบุคคลที่สาม โดยมี ข้อควรระวังที่สำคัญคือ ต้นทางที่ลงทะเบียนสำหรับช่วงทดลองใช้ต้องเป็นเว็บไซต์เดียวกันกับ ผู้ออก เช่น

  • โดเมนของผู้ออก: issuer.example
  • ผู้จดทะเบียน: 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 หรือ Magic Link

หากมีโทเค็น ให้ตรวจสอบโทเค็นดังนี้

  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 รายการขึ้นไป และปิดท้ายด้วย KB-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

ยืนยันระเบียน DNS _email-verification สำหรับโดเมนอีเมล เช่น สำหรับ demo@gmail.com ให้ค้นหาระเบียน TXT _email-verification.gmail.com สำหรับผู้ให้บริการรายนี้ การค้นหาจะแสดงตำแหน่งของผู้ให้บริการบัญชี ซึ่งก็คือ accounts.google.com

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

ยืนยันว่ารูปแบบของผู้ออกคือ https:// และ https://<domain> ตรงกับ การอ้างสิทธิ์ iss ใน EVT

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 ให้ยืนยันว่าฟิลด์ดังกล่าวตรงกับการอ้างสิทธิ์ iss ใน EVT แบบไบต์ต่อไบต์ ดึงข้อมูล JSON Web Key Set จาก jwks_uri

ใช้ไลบรารี SD-JWT เพื่อยืนยันแพ็กเกจโทเค็น ไลบรารีจะประสานงานการตรวจสอบดังนี้

  1. ตรวจสอบลายเซ็นของผู้ออกใน EVT กับ JWKS ที่ดึงข้อมูลมา
  2. ตรวจสอบลายเซ็นของเบราว์เซอร์ใน KB-JWT โดยใช้คีย์สาธารณะชั่วคราวใน cnf.jwk
  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 จะหมดอายุในวันที่ 17 พฤศจิกายน 2026) สำหรับช่วงทดลองใช้จากต้นทางของบุคคลที่สาม (Chrome 154 ขึ้นไป) ต้นทางที่ลงทะเบียนสำหรับช่วงทดลองใช้ ต้องเป็นเว็บไซต์เดียวกันกับผู้ออก (https://<issuer-domain>) คุณสามารถ ตรวจสอบสถานะช่วงทดลองใช้จากต้นทางและการหมดอายุของโทเค็นในเว็บไซต์ได้ใน DevTools ในส่วน แอปพลิเคชัน > เฟรม > (เลือกเฟรมที่เกี่ยวข้อง) > ช่วงทดลองใช้ จากต้นทาง
  • มาร์กอัปของแบบฟอร์ม: ทั้ง <input type="email" autocomplete="email"> และ <input type="hidden" autocomplete="email-verification-token" nonce="..."> ต้องอยู่ในองค์ประกอบ <form> เดียวกัน (ไม่แยกกันตามขอบเขต Shadow DOM boundaries) และ nonce ต้องไม่ว่างเปล่า
  • การส่งก่อนกำหนดหรือหน้าเว็บที่ใช้ซ้ำ: เบราว์เซอร์จะดึงข้อมูลโทเค็นใน เบื้องหลังหลังจากป้อนหรือป้อนข้อความอัตโนมัติในอีเมล การส่งก่อนที่คำขอจะเสร็จสมบูรณ์จะทำให้โทเค็นว่างเปล่า กรณีนี้อาจเกิดขึ้นหากผู้ใช้กด Return เพื่อส่งแบบฟอร์มหลังจากป้อนอีเมล
  • ข้อกำหนดเบื้องต้นของเบราว์เซอร์และผู้ให้บริการ: ผู้ใช้ต้องลงชื่อเข้าใช้ ผู้ให้บริการที่เข้าร่วมในโปรไฟล์เบราว์เซอร์เดียวกัน และเปิดใช้ อีเมล ที่ยืนยันแล้ว ในการตั้งค่า Chrome (chrome://settings/contactInfo)

การยืนยันลายเซ็นของผู้ออกไม่สำเร็จ

  • ไม่มีส่วนหัว kid: การอ้างสิทธิ์ kid (รหัสคีย์) ในส่วนหัว EVT และ JWKS เป็นตัวเลือก (เช่น Gmail ละเว้น kid) หากไม่มี kid ให้ วนซ้ำคีย์ผู้สมัครทั้งหมดใน jwks_uri ของผู้ออกแทนที่จะ ล้มเหลวในการค้นหารหัสคีย์
  • ตัวระบุอัลกอริทึม (Ed25519 และ EdDSA): ตั้งแต่ Chrome 156 เป็นต้นไป Chrome จะใช้ตัวระบุอัลกอริทึม Ed25519 ที่ระบุไว้อย่างครบถ้วน (RFC 9864) สำหรับส่วนหัว cnf.jwk และ KB-JWT ในขณะที่ผู้ออกและไลบรารีอาจระบุ Ed25519 หรือ EdDSA (พร้อมกับ ES256) ตรวจสอบว่าตรรกะการนำเข้าและการยืนยัน JWK ยอมรับตัวระบุทั้ง 2 รายการ
  • รูปแบบต้นทางของผู้ออก (iss): ระเบียน DNS TXT (_email-verification.<domain>) มีชื่อโฮสต์เปล่า (iss=accounts.issuer.example) ในขณะที่การอ้างสิทธิ์ iss ของ EVT เป็นต้นทาง HTTPS แบบเต็ม (https://accounts.issuer.example โดยไม่มีเครื่องหมายทับปิดท้าย) เติมคำนำหน้า https:// ให้กับค่าระเบียน DNS ก่อนทำการเปรียบเทียบ

การตรวจสอบการผูกคีย์ (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 ของโทเค็นกับค่าแบบฟอร์มที่ส่ง