การติดตั้งใช้งานผู้ให้บริการอีเมล (ผู้ออก)

ดูรายละเอียดเพิ่มเติมได้จากโค้ดเดโมของผู้ให้บริการอีเมลจำลองและดูขั้นตอนของผู้ให้บริการในข้อเสนอ Email Verification API และ Email Verification Protocol

ในฐานะผู้ออกบัตร คุณไม่จำเป็นต้องลงชื่อสมัครใช้ช่วงทดลองใช้จากต้นทาง หรือระบุโทเค็น เนื่องจากเว็บไซต์ Relying Party จะเป็นตัวกระตุ้นลักษณะการทำงานของเบราว์เซอร์ ตรวจสอบว่าได้กำหนดค่าอุปกรณ์ปลายทางให้ตอบสนองต่อคำขอเหล่านั้นแล้ว

กำหนดค่าการค้นพบผู้ให้บริการ

หากต้องการอนุญาตให้เบราว์เซอร์ค้นพบอุปกรณ์ปลายทางการยืนยันโดยอัตโนมัติเมื่อมีการเลือกอีเมลที่เป็นของโดเมนของคุณ ให้เปิดเผยการกำหนดค่าโดยใช้ DNS และอุปกรณ์ปลายทาง HTTP .well-known

กำหนดค่าระเบียนผู้รับมอบสิทธิ์ DNS

กำหนดค่าระเบียน TXT ของ DNS ในโดเมนอีเมลที่มอบสิทธิ์การยืนยันให้กับตัวระบุผู้ให้บริการ ตัวระบุเหล่านี้สามารถใช้โดเมนเดียวกันได้ ทั้งนี้ขึ้นอยู่กับโครงสร้างพื้นฐานของคุณ

รูปแบบระเบียน: _email-verification.<email-domain>

ไฟล์โซนตัวอย่าง

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

ค่า iss= ต้องเป็นชื่อโฮสต์ตัวพิมพ์เล็กแบบ Canonical ที่ไม่มีสกีม (https://), พอร์ต, เส้นทาง หรือ อักขระตัวพิมพ์ใหญ่ (เช่น iss=accounts.issuer.example) Chrome จะปฏิเสธระเบียนที่มีคอมโพเนนต์ที่ไม่ใช่ชื่อโฮสต์

โฮสต์อุปกรณ์ปลายทาง .well-known/email-verification

โฮสต์ไฟล์ข้อมูลเมตา JSON ในโดเมนผู้ให้บริการภายใต้เส้นทาง /.well-known/ ไฟล์นี้จะระบุความสามารถในการออกและอัลกอริทึมการลงนามด้วยการเข้ารหัสลับที่โครงสร้างพื้นฐานของคุณรองรับ

อุปกรณ์ปลายทาง: https://<issuer-domain>/.well-known/email-verification

คำตอบตัวอย่าง

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

พร็อพเพอร์ตี้ข้อมูลเมตา

  • issuer: ต้นทางของผู้ให้บริการ (https://<issuer-domain>, โดยไม่มีเครื่องหมายทับปิดท้าย ) ต้องตรงกับต้นทางที่ไฟล์ข้อมูลเมตาแสดงผลแบบไบต์ต่อไบต์
  • issuance_endpoint: HTTPS URL ที่รับคำขอ POST สำหรับการออกโทเค็น
  • jwks_uri: URL HTTPS ที่แสดงผล JSON Web Key Set (JWKS) สาธารณะ
  • signing_alg_values_supported: อาร์เรย์ของอัลกอริทึมการลงนาม JWS ที่รองรับ

โฮสต์อุปกรณ์ปลายทาง .well-known/web-identity

คุณอาจได้ติดตั้งใช้งานทรัพยากร JSON .well-known เพิ่มเติมเป็น ส่วนหนึ่งของ Federated Credentials (FedCM) API แล้ว แหล่งข้อมูลนี้มีลิงก์ไปยังปลายทางบัญชีและ URL สำหรับเข้าสู่ระบบ

อุปกรณ์ปลายทาง: 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 จะรับคำขอ POST application/json ที่ มีคีย์ email และส่วนหัวลายเซ็นข้อความ HTTP สำหรับ Signature, Signature-Input และ Signature-Key

ใช้ไลบรารีที่รองรับส่วนหัวที่มีโครงสร้างและลายเซ็นข้อความ HTTP สำหรับสภาพแวดล้อมของคุณ ใน Node.js คุณสามารถใช้ structured-headers และ http-message-sig

รูปแบบคำขอแบบเต็ม

POST /email-verification/issuance HTTP/1.1
Host: provider.example
Accept: application/json
Content-Digest: sha-256=:aBc123aBc123aBc123aBc123aBc123=:
Content-Type: application/json
Sec-Fetch-Dest: email-verification
Signature: sig=:+dEf567dEf567/dEf567dEf567dEf567/dEf567==:
Signature-Input: sig=("@method" "@authority" "@path" "content-digest" "signature-key");created=1786455840
Signature-Key: sig=hwk;alg="Ed25519";crv="Ed25519";kty="OKP";x="gHi890_gHi890_gHi890"

{email: "demo@example.com"}

แยกวิเคราะห์และตรวจสอบคำขอ

  • การตรวจสอบสิทธิ์เซสชัน: ตรวจสอบคุกกี้เซสชันของบุคคลที่หนึ่งที่ส่งมา พร้อมกับคำขอ ผู้ใช้ต้องได้รับการตรวจสอบสิทธิ์
  • ส่วนหัว Sec-Fetch-Dest: ตั้งค่าเป็น email-verification
  • ลายเซ็นข้อความ HTTP: ยืนยันลายเซ็นคำขอโดยใช้ คีย์สาธารณะชั่วคราวใน Signature-Key และตรวจสอบ Content-Digest ตั้งแต่ Chrome 156 เป็นต้นไป ส่วนหัว Signature-Key จะมี alg="Ed25519" ในพารามิเตอร์ hwk ยอมรับทั้ง "Ed25519" และ "EdDSA" และอนุญาตให้ละเว้น alg ได้ใน Chrome เวอร์ชันก่อนหน้า
  • เพย์โหลด: เนื้อหา JSON มีสตริง email ที่ขอให้ ยืนยัน

การตอบสนองการออกโทเค็น

เมื่อตรวจสอบเซสชันและโทเค็นคำขอสำเร็จแล้ว ให้สร้าง JWT (SD-JWT) ที่ลงนามแล้วสำหรับการเปิดเผยข้อมูลแบบเลือก ซึ่งแสดงผลเป็น JSON โดยใช้ไลบรารีที่เหมาะสมสำหรับแพลตฟอร์มของคุณ เช่น สำหรับ Node คุณสามารถใช้ @sd-jwt/core และ jose

รูปแบบเพย์โหลดดิบควรมีลักษณะดังนี้

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

สร้าง ลงนาม และแสดงผลโทเค็น

import { importJWK, CompactSign } from "jose";
import { SDJwtInstance } from "@sd-jwt/core";
import crypto from "node:crypto";
// Issuer private key from secure storage
const privateKey = await importJWK(PRIVATE_KEY_JWK, "EdDSA");
const origin = url.origin;
const currentTime = Math.floor(Date.now() / 1000);
const evtPayload = {
  iss: origin,
  iat: currentTime,
  exp: currentTime + 300, // 5 minutes
  cnf: {
    jwk: browserJwk,
  },
  email: payload.email, // exactly as received in payload
  email_verified: true,
};
const sdJwt = new SDJwtInstance({
  signer: async (data) => {
    const [headerB64, payloadB64] = data.split(".");
    const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
    const payload = Buffer.from(payloadB64, "base64url");
    const signed = await new CompactSign(payload).setProtectedHeader(header).sign(privateKey);
    return signed.split(".").pop()!;
  },
  signAlg: "EdDSA",
  hasher: async (data, alg) => {
    const nodeAlg = alg.replace("-", "");
    return new Uint8Array(crypto.createHash(nodeAlg).update(data).digest());
  },
  hashAlg: "sha-256",
  saltGenerator: async () => crypto.randomBytes(16).toString("base64url"),
});
const issuanceToken = await sdJwt.issue(evtPayload, undefined, {
  header: {
    alg: "EdDSA",
    kid: PRIVATE_KEY_JWK.kid,
    typ: "evt+jwt",
  },
});
return sendResponse({ issuance_token: issuanceToken, }, 200);

เนื้อหาการตอบสนองที่ได้จะมีลักษณะดังนี้

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

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

การแก้ปัญหา

หากเบราว์เซอร์ไม่ติดต่ออุปกรณ์ปลายทางของคุณหรือปฏิเสธโทเค็นที่ออก ให้ตรวจสอบปัญหาที่พบได้ทั่วไปต่อไปนี้

เบราว์เซอร์ไม่เคยเรียก accounts_endpoint หรือ issuance_endpoint

  • ไม่ได้ตั้งค่าสถานะการเข้าสู่ระบบ: Chrome จะค้นหาเฉพาะอุปกรณ์ปลายทางของคุณก็ต่อเมื่อทราบว่า ผู้ใช้ลงชื่อเข้าสู่ระบบแล้ว ตรวจสอบว่าโฟลว์การลงชื่อเข้าใช้ตั้งค่าส่วนหัว Set-Login: logged-in HTTP หรือเรียก navigator.login.setStatus("logged-in")
  • คุกกี้เซสชันถูกบล็อก (SameSite=None): เบราว์เซอร์จะดึงข้อมูล accounts_endpoint และ issuance_endpoint จาก Relying Party ในเว็บไซต์อื่น เนื่องจากคำขอเหล่านี้เป็นคำขอแบบข้ามเว็บไซต์ คุกกี้เซสชันจึงต้องมี SameSite=None; Secure คุกกี้ SameSite=Lax จะทำงานเมื่อทดสอบในตัวยืนยันเว็บไซต์เดียวกัน แต่จะถูกละเว้นในคำขอแบบข้ามเว็บไซต์
  • การค้นพบหรือบัญชีไม่ตรงกัน: ตรวจสอบว่า _email-verification.<email-domain> แสดงผลระเบียน TXT รายการเดียวที่มี ชื่อโฮสต์ตัวพิมพ์เล็กแบบ Canonical (iss=<issuer-domain> โดยไม่มี https:// พอร์ต เส้นทาง หรืออักขระตัวพิมพ์ใหญ่) อุปกรณ์ปลายทาง .well-known ทั้ง 2 รายการแสดงผล Content-Type: application/json และ .well-known/email-verification มี issuer ที่ตรงกับ https://<issuer-domain> แบบไบต์ต่อไบต์ และการตอบสนอง accounts_endpoint มีบัญชีที่มี email ตรงกับที่อยู่ที่ป้อน
  • อัลกอริทึมการลงนามที่ไม่รองรับใน .well-known/email-verification: Chrome 154 และ 155 ต้องมี "EdDSA" ใน signing_alg_values_supported, ในขณะที่ Chrome 156 ขึ้นไปและข้อกำหนดเฉพาะของ IETF รองรับ "Ed25519". โฆษณาทั้ง ["Ed25519", "EdDSA"] ในระหว่างการเปลี่ยนผ่านเพื่อให้ Chrome Stable ไม่ปฏิเสธข้อมูลเมตาการค้นพบ

การตรวจสอบคำขอออกโทเค็นไม่สำเร็จ

  • Sec-Fetch-Dest การสะกดส่วนหัว: Chrome 154 ขึ้นไปจะส่ง Sec-Fetch-Dest: email-verification (มีขีดกลาง) ในขณะที่ Chrome 153 ส่ง emailverification (ไม่มีขีดกลาง) ยอมรับทั้ง 2 ค่าในระหว่างการเปิดตัว
  • ลายเซ็นข้อความ HTTP (@authority) ไม่ตรงกันหลังพร็อกซี: เมื่อยืนยันลายเซ็น RFC 9421 คอมโพเนนต์ @authority จะแสดงโฮสต์ที่เปิดเผยต่อสาธารณะ หากเซิร์ฟเวอร์ของคุณอยู่หลังพร็อกซีแบบย้อนกลับหรือตัวจัดสรรภาระงาน ให้สร้าง URL การยืนยันใหม่โดยใช้ X-Forwarded-Host (หรือต้นทางสาธารณะ) แทนชื่อโฮสต์ภายใน และคำนวณ Content-Digest จากไบต์เนื้อหาคำขอแบบดิบก่อนการแยกวิเคราะห์ JSON

เบราว์เซอร์ปฏิเสธ issuance_token ที่แสดงผล

  • การอ้างสิทธิ์ email ที่แก้ไขหรือ Canonical: ตั้งแต่ Chrome 156 เป็นต้นไป เบราว์เซอร์ จะตรวจสอบว่าการอ้างสิทธิ์ email ของ EVT ตรงกับ email ที่ขอแบบไบต์ต่อไบต์ หากแบ็กเอนด์ทำให้ที่อยู่เป็นรูปแบบบัญชี Canonical (เช่น แสดงผล First.Last@example.com เมื่อมีการขอ first.LAST@example.com) Chrome จะทิ้งโทเค็น จับคู่คำขอกับบัญชีของผู้ใช้ แต่แสดงผลสตริง email ที่ได้รับในเนื้อหาคำขออย่างถูกต้อง
  • ไม่มีเครื่องหมายทิลดา (~) ปิดท้าย: แม้จะไม่มีการเปิดเผยข้อมูล issuance_token ก็ต้องเป็น SD-JWT ที่ถูกต้องซึ่งลงท้ายด้วยเครื่องหมายทิลดา (<Issuer-signed-JWT>~) เพื่อให้เบราว์เซอร์สามารถเพิ่ม <KB-JWT> ได้
  • `iss` iss หรือ cnf.jwk`cnf.jwk` ไม่ตรงกัน**: ตรวจสอบว่าการอ้างสิทธิ์ iss`iss` ของ EVT เป็น ต้นทาง HTTPS ที่ถูกต้อง (https://<issuer-domain>`https://<issuer-domain>` โดยไม่มีเครื่องหมายทับปิดท้าย) ซึ่งตรงกับ ข้อมูลเมตา .well-known/email-verification`.well-known/email-verification` และ cnf.jwk`cnf.jwk` ฝัง คีย์สาธารณะชั่วคราวของเบราว์เซอร์จากส่วนหัว Signature-Key`Signature-Key`