הטמעה של ספק אימייל (מנפיק)

לפרטים נוספים, אתם יכולים לעיין בקוד ההדגמה המדומה של ספק האימייל ובשלבים למנפיקים בהצעות ל-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-Dest header: מגדירים את הערך 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: מוודאים שהטענה של EVT‏ iss היא המקור המדויק של HTTPS (https://<issuer-domain>, ללא לוכסן בסוף) שתואם למטא-נתונים של .well-known/email-verification, ושה-EVT‏ cnf.jwk מטמיע את המפתח הציבורי הזמני של הדפדפן מהכותרת Signature-Key.