ดูรายละเอียดเพิ่มเติมได้จากโค้ดเดโมของผู้ให้บริการอีเมลจำลองและดูขั้นตอนของผู้ให้บริการในข้อเสนอ 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-inHTTP หรือเรียก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`