برای جزئیات بیشتر، میتوانید کد نمایشی ارائهدهنده ایمیل شبیهسازیشده را مرور کنید و به مراحل صادرکننده در پیشنهادهای میانای برنامهسازی کاربردی درستیسنجی ایمیل و پروتکل درستیسنجی ایمیل مراجعه کنید.
بهعنوان صادرکننده، لازم نیست برای آزمایش مبدأ ثبتنام کنید یا کد ارائه دهید زیرا سایت طرف متکی رفتار مرورگر را راهاندازی میکند. مطمئن شوید که نقطههای پایانی شما برای پاسخ به این درخواستها پیکربندی شدهاند.
پیکربندی کاوش صادرکننده
برای اینکه مرورگرها بتوانند نقاط پایانی درستیسنجی شما را بهطور خودکار پیدا کنند، وقتی نشانی ایمیلی متعلق به دامنهتان انتخاب میشود، پیکربندیتان را بااستفاده از ساناد و نقطه پایانی .well-known پروتکل انتقال ابرمتن نمایان کنید.
پیکربندی سابقه نماینده ساناد
یک سابقه DNS TXT در دامنه ایمیل خود پیکربندی کنید که اختیار درستیسنجی را به شناسه صادرکننده شما واگذار کند. این شناسهها میتوانند از همان دامنه استفاده کنند بسته به زیرساخت شما.
قالب ضبط: _email-verification.<email-domain>
فایل منطقه نمونه:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
مقدار iss= باید نام میزبان متعارف، ساده، و با حروف کوچک (برای مثال،
iss=accounts.issuer.example) بدون طرح (https://)، درگاه، مسیر، یا
نویسههای بزرگ باشد. 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: نشانی وب اچتیتیپی که درخواستهای صدورPOSTژتون را دریافت میکند.-
jwks_uri: نشانی وب HTTPS که مجموعه کلید وب JSON عمومی شما را ارائه میدهد (JWKS). signing_alg_values_supported: آرایه الگوریتمهای امضای JWS پشتیبانیشده.
میزبانی نقطه پایانی .well-known/web-identity
ممکن است قبلاً یک منبع JSON اضافی .well-known را بهعنوان بخشی از Federated Credentials (FedCM) API پیادهسازی کرده باشید. این منبع پیوندهایی به نقطه پایان حسابها و نشانی وب ورود به سیستم شما ارائه میدهد.
نقطه پایانی: 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
یا وضعیت را بااستفاده از جاوا اسکریپت در بافت برنامه وب بهروز کنید
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"}
درخواست را تجزیه و اعتبارسنجی کنید:
- اصالتسنجی جلسه: کوکیهای جلسه شخص اول ارسالشده با درخواست را اعتبارسنجی کنید. کاربر باید اصالتسنجی شود.
Sec-Fetch-Destسرایند: رویemail-verificationتنظیم شد.- امضاهای پیام HTTP: امضای درخواست را بااستفاده از کلید عمومی
گذرا در
Signature-Keyدرستیسنجی کنید وContent-Digestرا اعتبارسنجی کنید. از Chrome 156، سرصفحهSignature-Keyشاملalg="Ed25519"در پارامترهایhwkخود است؛"Ed25519"و"EdDSA"را بپذیرید و اجازه دهیدalgتوسط نسخههای قبلی Chrome حذف شود. - پایهبار: بدنه JSON حاوی رشته
emailدرخواستی برای درستیسنجی است.
پاسخ صدور
پساز اعتبارسنجی موفقیتآمیز جلسه و توکن درخواست، بااستفاده از کتابخانههای مناسب برای پلاتفرم خود، یک «نشان وب JSON شفافسازی انتخابی» (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شما را از طرف تکیهکننده در سایت دیگری واکشی میکند. چون این درخواستها بینسایتی هستند، کوکی جلسه شما باید شاملSameSite=None; Secureباشد. کوکیSameSite=Laxهنگام آزمایش در درستیسنج همان سایت کار میکند، اما در درخواستهای بینسایتی حذف میشود. - عدم تطابق حساب یا اکتشاف: تأیید کنید که
_email-verification.<email-domain>یک رکورد TXT تکی با نام میزبان متعارف با حروف کوچک (iss=<issuer-domain>، بدونhttps://، درگاه، مسیر، یا نویسههای بزرگ) برمیگرداند، هر دو نقطه پایانی.well-knownContent-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 نسخه ۱۵۴ و بالاترSec-Fetch-Dest: email-verification(با خط تیره) ارسال میکند، درحالیکه Chrome نسخه ۱۵۳emailverification(بدون خط تیره) ارسال میکرد. هر دو مقدار را درطول عرضه بپذیرید. - عدم تطابق «امضای پیام HTTP» (
@authority) پشت پراکسی: هنگام تأیید امضای RFC 9421، مؤلفه@authorityمیزبان عمومی را منعکس میکند. اگر سرورتان پشت یک پروکسی معکوس یا ترازکننده بار قرار دارد، نشانی وب درستیسنجی را بااستفاده ازX-Forwarded-Host(یا مبدأ عمومیتان) بهجای نام میزبان داخلی بازسازی کنید وContent-Digestرا روی بایتهای بدنه درخواست خام قبلاز تجزیه JSON محاسبه کنید.
مرورگر issuance_token برگرداندهشده را رد میکند
- ادعای
emailاصلاحشده یا متعارفشده: از Chrome 156، مرورگر بررسی میکند که ادعای EVTemailباemailدرخواستی بایتبهبایت مطابقت داشته باشد. اگر پسای شما نشانی را به قالب حساب متعارف نرمالسازی کند (مثلاً وقتیfirst.LAST@example.comدرخواست شده است،First.Last@example.comرا برگرداند)، Chrome کد را رها میکند. درخواست را با حساب کاربر مطابقت دهید، اما رشته دقیقemailدریافتی در بدنه درخواست را برگردانید. - علامت مدک (
~) در انتها وجود ندارد: حتی با صفر شفافسازی،issuance_tokenباید یک SD-JWT معتبر باشد که با علامت مدک در انتها (<Issuer-signed-JWT>~) پایان یابد تا مرورگر بتواند<KB-JWT>را اضافه کند. - عدم تطابق
issیاcnf.jwk: مطمئن شوید ادعایissEVT دقیقاً منشأ HTTPS (https://<issuer-domain>، بدون اسلش انتهایی) مطابق با فراداده.well-known/email-verificationشما باشد، وcnf.jwkکلید عمومی موقت مرورگر را از سرصفحهSignature-Keyجاسازی کند.