לפרטים נוספים, אתם יכולים לעיין בקוד ההדגמה המדומה של ספק האימייל ובשלבים למנפיקים בהצעות ל-Email Verification API ול-Email Verification Protocol.
כמנפיקים, אתם לא צריכים להירשם לגרסת המקור לניסיון או לספק אסימון, כי האתר של הצד המסתמך מפעיל את התנהגות הדפדפן. חשוב לוודא שנקודות הקצה מוגדרות להגיב לבקשות האלה.
הגדרת גילוי מנפיקים
כדי לאפשר לדפדפנים לגלות באופן אוטומטי את נקודות הקצה של האימות כשבוחרים כתובת אימייל ששייכת לדומיין שלכם, צריך לחשוף את ההגדרה באמצעות DNS ונקודת קצה של .well-known HTTP.
הגדרת רשומת DNS של נציג
מגדירים רשומת DNS TXT בדומיין של האימייל, שמאצילה את סמכות האימות למזהה המנפיק. המזהים האלה יכולים להשתמש באותו דומיין, בהתאם לתשתית שלכם.
פורמט ההקלטה: _email-verification.<email-domain>
קובץ אזור לדוגמה:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
הערך של iss= חייב להיות שם מארח קנוני פשוט באותיות קטנות (לדוגמה, iss=accounts.issuer.example) בלי סכימה (https://), יציאה, נתיב או אותיות רישיות. Chrome דוחה רשומות שכוללות רכיבים שאינם שמות מארחים.
אירוח נקודת קצה (endpoint) של .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: כתובת ה-URL מסוג HTTPS שמקבלת בקשות להנפקת אסימוניםPOST.jwks_uri: כתובת ה-URL מסוג HTTPS שמציגה את קבוצת מפתחות ה-JWK הציבוריים (JWKS).-
signing_alg_values_supported: מערך של אלגוריתמים נתמכים לחתימת JWS.
אירוח נקודת קצה (endpoint) של .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"
}
שימוש בנקודת קצה (endpoint) של חשבונות
נקודת הקצה accounts מ-FedCM API מספקת רשימה של חשבונות מחוברים כרגע. בדוגמה הבאה מוצגת תגובה מינימלית. פרטים נוספים זמינים במדריך להטמעה של ספק הזהויות.
נקודת קצה (endpoint): כמו שמצוין ב-.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 מקבל בקשת application/json POST שמכילה את מפתח 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"}
מנתחים ומאמתים את הבקשה:
- אימות סשן: אימות קובצי ה-Cookie הזמניים מהדומיין הנוכחי שנשלחים עם הבקשה. המשתמש צריך להיות מאומת.
-
Sec-Fetch-Destheader: מגדירים את הערךemail-verification. - חתימות של הודעות HTTP: מאמתים את החתימה של הבקשה באמצעות המפתח הציבורי הזמני ב-
Signature-Keyומאמתים אתContent-Digest. החל מגרסה 156 של Chrome, הכותרתSignature-Keyכוללת אתalg="Ed25519"בפרמטריםhwkשלה. צריך לאשר את"Ed25519"ואת"EdDSA", ולאפשר השמטה שלalgבגרסאות קודמות של Chrome. - המטען הייעודי (payload): גוף ה-JSON מכיל את המחרוזת
emailשנדרשת לאימות.
תשובה להנפקה
אחרי אימות מוצלח של הסשן ושל אסימון הבקשה, צריך ליצור SD-JWT חתום (טוקן JWT עם חשיפה סלקטיבית) שמוחזר כ-JSON באמצעות ספריות מתאימות לפלטפורמה שלכם. לדוגמה, ב-Node אפשר להשתמש ב-@sd-jwt/core וב-jose.
הפורמט של המטען הייעודי (payload) הגולמי אמור להיראות כך:
{
"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 שולח שאילתות לנקודות הקצה רק אם הוא יודע שהמשתמש מחובר. מוודאים שתהליך הכניסה מגדיר את כותרת ה-HTTP
Set-Login: logged-inאו קורא ל-navigator.login.setStatus("logged-in"). - קובצי Cookie זמניים חסומים (
SameSite=None): הדפדפן מאחזר אתaccounts_endpointו-issuance_endpointמהצד המסתמך באתר אחר. מכיוון שמדובר בבקשות בין אתרים, קובץ Cookie זמני חייב לכלול אתSameSite=None; Secure. קובץ Cookie עם מאפייןSameSite=Laxפועל כשבודקים אותו באמצעות כלי אימות של אותו אתר, אבל הוא מושמט בבקשות בין אתרים. - בעיה בזיהוי או אי התאמה בחשבון: מוודאים שהפקודה
_email-verification.<email-domain>מחזירה רשומת TXT אחת עם שם מארח קנוני באותיות קטנות (iss=<issuer-domain>, ללאhttps://, יציאה, נתיב או אותיות רישיות), ששתי נקודות הקצה.well-knownמחזירותContent-Type: application/json, של-.well-known/email-verificationישissuerשתואם ל-https://<issuer-domain>בבייט אחר בייט, ושבתגובהaccounts_endpointנכלל חשבון שערךemailשלו תואם לכתובת שהוזנה. - אלגוריתם חתימה לא נתמך ב-
.well-known/email-verification: בגרסאות 154 ו-155 של Chrome נדרש"EdDSA"ב-signing_alg_values_supported, אבל בגרסה 156 ואילך של Chrome ובמפרט של IETF יש תמיכה ב-"Ed25519". מפרסמים את שתי["Ed25519", "EdDSA"]במהלך המעבר כדי שהגרסה היציבה של Chrome לא תדחה את המטא-נתונים של הגילוי.
אימות בקשת ההנפקה נכשל
- איות הכותרת
Sec-Fetch-Dest: גרסה 154 של Chrome והלאה שולחת את הכותרתSec-Fetch-Dest: email-verification(עם מקף), וגרסה 153 של Chrome שלחה את הכותרתemailverification(בלי מקף). במהלך ההשקה, צריך לקבל את שני הערכים. - אי התאמה של חתימת HTTP על הודעה (
@authority) מאחורי שרת Proxy: כשמאמתים את החתימה של RFC 9421, הרכיב@authorityמשקף את המארח שפונה לציבור. אם השרת שלכם נמצא מאחורי שרת proxy הפוך או מאזן עומסים, צריך לשחזר את כתובת ה-URL לאימות באמצעותX-Forwarded-Host(או המקור הציבורי שלכם) ולא באמצעות שם המארח הפנימי, ולחשב אתContent-Digestעל בסיס הבייטים של גוף הבקשה הגולמי לפני ניתוח ה-JSON.
הדפדפן דוחה את הערך issuance_token שמוחזר
- טענת
emailששונתה או עברה קנוניזציה: החל מגרסה 156 של Chrome, הדפדפן בודק שטענת ה-EVT שלemailתואמת ל-emailהמבוקש, בייט אחר בייט. אם ה-backend שלכם מנרמל את הכתובת לפורמט חשבון קנוני (למשל, מחזיר אתFirst.Last@example.comכשנשלחה בקשה ל-first.LAST@example.com), Chrome משמיט את האסימון. להתאים את הבקשה לחשבון של המשתמש, אבל להחזיר את המחרוזתemailהמדויקת שהתקבלה בגוף הבקשה. - חסרה טילדה (
~) בסוף: גם אם אין גילויים נאותים, ה-issuance_tokenחייב להיות SD-JWT תקין שמסתיים בטילדה (<Issuer-signed-JWT>~) כדי שהדפדפן יוכל להוסיף את ה-<KB-JWT>. - יש אי התאמה בין
issלביןcnf.jwk: מוודאים שהטענה של EVTissהיא המקור המדויק של HTTPS (https://<issuer-domain>, ללא לוכסן בסוף) שתואם למטא-נתונים של.well-known/email-verification, ושה-EVTcnf.jwkמטמיע את המפתח הציבורי הזמני של הדפדפן מהכותרתSignature-Key.