منتشرشده: ۸ ژوئیه ۲۰۲۶، آخرین بهروزرسانی: ۵ اکتبر ۲۰۲۶
هنگام جمعآوری نشانی ایمیل بهعنوان بخشی از ثبتنام، ورود به سیستم، مشترک شدن، تسویهحساب، بازیابی حساب، یا فرایندی دیگر، تأیید اینکه نشانی ایمیل متعلق به شخص واردکننده آن است یک رویه معمول است. روشهای درستیسنجی موجود، مثل گذرواژههای یکبارمصرف (OTP) یا پیوندهای درستیسنجی ایمیل (پیوندهای جادویی)، کاربر را ملزم میکند از سایت شما خارج شود. این فرایند مختلکننده میتواند خطر رها کردن جلسه بهطور کامل و هرگز تکمیل نکردن فرایند اصالتسنجی را برای کاربر، چه انسان و چه عامل، افزایش دهد.
Email Verification API پیشنهادی است که به مرورگر اجازه میدهد مستقیماً با ارائهدهنده ایمیل ارتباط برقرار کند تا درستیسنجی کند که کاربر مالک نشانی ایمیل است. کاربر ایمیلی را از پیشنهاد تکمیل خودکار یا تکمیل خودکار مرورگر انتخاب میکند، فرم را ارسال میکند، و سایت نشانی ایمیل را بدون ارسال ایمیل یا مختل کردن جریان کاربر با ارائهدهنده درستیسنجی میکند.
جمعآوری ایمیل نقطه تبدیل مهمی در سفر کاربر است و Chrome میخواهد از سایتهایی که میخواهند ایمیلها را درستیسنجی کنند، ارائهدهندگان ایمیلی که میتوانند درستیسنجی را انجام دهند، و کاربرانی که این فرایند را تجربه میکنند بازخورد دریافت کند. امروز میتوانید برای آزمایش مبدأ ثبتنام کنید و دستورالعملهای پیادهسازی را در اینجا دنبال کنید. برای پیکربندی کلی آزمایش مبدأ، به شروع به کار با آزمایشهای مبدأ مراجعه کنید.
میتوانید این جریان را با حساب نمایشی امتحان کنید:
- نمونه صادرکننده حساب و جلسه ایمیل ساختگی به شما میدهد
- نمونه نمایشی درستیسنج هر ارائهدهنده شرکتکننده را درستیسنجی میکند
گردش درستیسنجی ایمیل
بخشهای زیر توضیح میدهد که شما و کاربرانتان برای شروع جریان درستیسنجی ایمیل و کل گردش کار هنگام استفاده از «پروتکل درستیسنجی ایمیل» چه کارهایی باید انجام دهید.
واژههای کلیدی
اصطلاحات کلیدی Email Verification API بهشرح زیر است:
- درستیسنج: سایتی که نشانی ایمیل را جمعآوری میکند و میخواهد آن را درستیسنجی کند. درستیسنج را طرف متکی نیز مینامند.
- ارائهدهنده ایمیل: سرویسی که نشانی ایمیل کاربر را ارائه میدهد، برای مثال
gmail.com. - صادرکننده: سرویسی که حساب ایمیل کاربر را مدیریت میکند، برای مثال
accounts.google.com. صادرکننده را ارائهدهنده هویت نیز مینامند.
در برخی موارد، ارائهدهنده ایمیل و صادرکننده ممکن است از یک دامنه عمل کنند. بااینحال، مهم است که بین داشتن نشانی ایمیل و داشتن جلسه فعال برای حساب مرتبط تمایز قائل شوید.
پیشنیازها
- کاربر باید در همان نمایه مرورگر به سیستم ارائهدهنده ایمیل یا صادرکننده خود وارد شده باشد. برای مثال، اگر از Gmail استفاده میکنند، باید به سیستم «حساب Google» خود وارد شوند.
- بهعنوان سایت درستیسنجی شرکتکننده، باید برای آزمایش اصلی ثبتنام کنید و کد را در همان صفحهای که فرم ایمیلتان قرار دارد ارائه دهید.
کاربر باید نشانی ایمیل خود را از منوِ کرکرهای تکمیل خودکار یا تکمیل خودکار انتخاب کند.
- اگر کاربر قبلاً نشانی ایمیلی را در این فیلد وارد کرده باشد، این نشانی بااستفاده از تکمیل خودکار پیشنهاد خواهد شد.
اگر کاربر نشانی ایمیل خود را بااستفاده از تنظیمات Chrome «تکمیل خودکار و گذرواژه» (
chrome://settings/autofill) اضافه کرده باشد، این نشانی بااستفاده از تکمیل خودکار پیشنهاد خواهد شد.
اولینبار که کاربر نشانی ایمیلی را برای درستیسنجی ارائه میدهد، پیامواره اجازهای را خواهد دید. این کار فقط یکبار برای هر نشانی ایمیل انجام میشود.
وقتی کاربر آن جلسه فعال را در مرورگرش داشته باشد، میتواند فرایند را شروع کند:
- در فرمی که فیلد ایمیل دارد، کاربر نشانی ایمیل خود را از منو کرکرهای تکمیل خودکار انتخاب میکند. سایت درستیسنج یک فیلد پنهان در فرم با یک مقدار یکبارمصرف برای هر نمونه ارائه میکند تا این درخواست را اعتبارسنجی کند.
سپس مرورگر سابقه ساناد درستیسنجی ایمیل را برای دامنه ایمیل بازیابی میکند. این کار مرورگر را به صادرکننده هدایت میکند. سپس صادرکننده تأیید میکند که برای آن نشانی ایمیل جلسه فعالی دارد.
سپس صادرکننده نشان درستیسنجی ایمیل (EVT) را برای نشانی ارائه میدهد. مرورگر آن را با EVT، مبدأ سایت، و تکمنظوره از فرم ورودی در یک JWT کلیدبند ترکیب میکند.
وقتی فرم ارسال میشود، بسته EVT به فیلد پنهان اضافه میشود و به سایت ارسال میشود.
سایت درستیسنج سپس هریک از این جزئیات را درستیسنجی میکند: نشانی ایمیل موردانتظار، عدد یکبارمصرف، و امضاهای مرورگر و صادرکننده.
کاربر اعلان کوچکی میبیند که به او اطلاع میدهد ارائهدهنده ایمیلش نشانی او را تأیید کرده است.
این فرایند به سایت درستیسنج تأییدیه میدهد که نشانی ایمیل معتبر است و متعلق به کاربر فعلی است، که یعنی سایت میتواند از ارسال ایمیل درستیسنجی صرفنظر کند.
کاربران میتوانند ایمیلهای درستیسنجیشده خود را در تنظیمات > تکمیل خودکار و گذرواژهها > اطلاعات تماس > ایمیل درستیسنجیشده مدیریت کنند (یا chrome://settings/contactInfo را باز کنند).
ملاحظات مورد استفاده
درستیسنجی ایمیل یک بهبود تدریجی در جریان موجود شما است که نیاز کاربر به ترک سایت برای دریافت رمز یکبارمصرف یا کلیک کردن روی پیوند را برطرف میکند. سایتها میتوانند فیلدهای درستیسنجی ایمیل را به همه فرمهای مربوطه، مانند ورود به سیستم، ثبتنام خبرنامه، ایجاد حساب، و بازیابی گذرواژه اضافه کنند. «ایویپی» فقط درصورتی راهاندازی میشود که مرورگر از آن پشتیبانی کند. اگر هنگام ارسال کد دریافت نشد یا هریک از مراحل اعتبارسنجی ناموفق بود، میتوانید به جریان تأیید ایمیل پیشفرض خود برگردید. این همچنین به این معنی است که هیچ ویژگی تشخیص برای API وجود ندارد؛ سایت درستیسنج EVT را اختیاری درنظر میگیرد و درصورت وجود در درخواست، آن را پردازش میکند.
درستیسنجی ایمیل تأیید میکند که کاربر جلسه فعالی با ارائهدهنده نشانی ایمیل خود دارد. این ویژگی تأیید نمیکند که ایمیل شما به کاربر رسیده است. همچنان ممکن است بخواهید ایمیلهای خوشامدگویی یا آمادهسازی موجود را ارسال کنید و ممکن است بخواهید یا نیاز داشته باشید از کاربر بخواهید تنظیمات هرزنامه خود را بررسی کند.
پیادهسازی سایت درستیسنج
برای جزئیات بیشتر، میتوانید کد نمایش گامبهگام را بررسی کنید و به مراحل اعتبارسنجی در ایپیآی درستیسنجی ایمیل و پیشنهادهای پروتکل درستیسنجی ایمیل مراجعه کنید.
پیکربندی فیلدهای فرم
مطمئن شوید فیلدهای فرم شما مشخصههای صحیح را داشته باشند:
<input
name="email-address"
type="email"
autocomplete="email">
<input
type="hidden"
name="token"
nonce="rAnD0m-VaLuE"
autocomplete="email-verification-token">
مشخصههای type و autocomplete ورودی email را روی email تنظیم کنید تا
مرورگر بتواند تکمیل خودکار نشانی ایمیل را ارائه دهد.
فیلد جدید hidden با کد درستیسنجی ایمیل در
ارسال فرم تکمیل خواهد شد. مشخصههای ضروری عبارتاند از:
-
type="hidden"تنظیم شد زیرا این فیلد به ورودی کاربر نیاز ندارد. -
nonce="rAnD0m-VaLuE"تنظیم شود. سایت باید یک نانس منحصربهفرد محدود به جلسه ارائه دهد تا ارسال فرم را درستیسنجی کند. -
autocomplete="email-verification-token"تنظیم شود. مرورگر از این مشخصه برای شناسایی فیلد درج استفاده میکند.
عناصر فرمتان را با بررسی پانل «شبکه» در DevTools اعتبارسنجی کنید. وقتی نشانی ایمیلی را انتخاب میکنید، میبینید که مرورگر ساناد و پُرسمانهای جستجوی حساب بعدی را برای ارائهدهنده ایمیل و صادرکننده راهاندازی میکند. اینها درخواستهای داخلی مرورگر هستند؛ سایت شما تا زمان ارسال فرم چیزی دریافت نمیکند.
اعتبارسنجی EVT
برای اعتبارسنجی هریک از عناصر بسته EVT، پنج مرحله وجود دارد.
- کد را تجزیه کنید.
- مقادیر موردانتظار را اعتبارسنجی کنید.
- کلید اختصاصدادهشده را تأیید کنید.
- ساختار ساناد را اعتبارسنجی کنید.
- صادرکننده را شناسایی و امضای EVT را درستیسنجی کند.
۱. تجزیه کردن کد
دادههای خام ارسال فرم حاوی EVT و ادعاهای امضاشده در
«نشان وب JSON افشای انتخابی»
(SD-JWT+KB) است که با مدک
(~ نویسه) از هم جدا شدهاند. باید این موارد را جدا کنید و سرصفحهها و محمولههای «امضای شیء و رمزگذاری Javascript» (JOSE) را رمزگشایی کنید (برای مثال بااستفاده از jose برای Node.js).
اگر example.com demo@gmail.com را درستیسنجی کند، بار مفید رمزگشاییشده شبیه به
مثال زیر است:
{
"evtJwtDecodedPayload": {
"cnf": {
"jwk": {
"crv": "Ed25519",
"kty": "OKP",
"x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
}
},
"email": "demo@gmail.com",
"email_verified": true,
"iat": 1782911685,
"iss": "https://accounts.google.com"
},
"kbJwtDecodedPayload": {
"aud": "https://example.com",
"iat": 1782911685,
"nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
"sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
}
}
۲. مقادیر موردانتظار را اعتبارسنجی کنید
بررسی کنید که مقادیر پایه در محتوای پیام با مقادیر ارائهشده شما مطابقت داشته باشد:
- تأیید کنید که
email_verifiedرویtrueتنظیم شده است. - تأیید کنید که
emailبا نشانی ایمیل ارائهشده در فرمتان مطابقت دارد. - تأیید کنید که
nonceبا مقدار یکبارمصرف ارائهشده در فرم شما مطابقت دارد. - مطمئن شوید که
audبا مبدأ سایت شما مطابقت داشته باشد. - تأیید کنید که
iatمُهر زمان نسبتاً جدیدی داشته باشد، برای مثال، بعداز پرداز کردن فرم.
۳. تأیید کردن تخصیص کلید
مرورگر کلید موقت و زودگذری برای تراکنش ایجاد میکند تا تأیید کند
که کد را امضا کرده است. این کلید را از ادعای cnf (تأیید) در EVT استخراج کنید
و سپس از آن برای تأیید JWT کلیدبسته استفاده کنید.
سپس، درهمسازی موردانتظار را محاسبه کنید و آن را با ادعای sd_hash مقایسه کنید. مثال Node.js زیر نحوه انجام این محاسبه را نشان میدهد:
const calculatedHash = createHash("sha256")
.update(evtJwt + "~")
.digest("base64url");
۴. راستیآزمایی کردن سابقه ساناد
سابقه ساناد _email-verification را برای دامنه نشانی ایمیل درستیسنجی کنید. برای مثال، برای demo@gmail.com، _email-verification.gmail.com TXT
گزارش را پُرسمان کنید. برای این ارائهدهنده، پُرسمان مکان ارائهدهنده حساب را برمیگرداند، یعنی accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
۵. صادرکننده را شناسایی و امضای EVT را درستیسنجی کنید
مطمئن شوید صادرکننده منبع /.well-known/email-verification را ارائه میکند که
نقاط پایانی را برای صدور رمز، کلید وب JSON (JWK) برای
سایت، و الگوریتمهای امضای پشتیبانیشده ارائه میدهد.
$ curl https://accounts.google.com/.well-known/email-verification
{
"issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
"jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["EdDSA"]
}
از JWKs برای درستیسنجی EVT JWT که از رمز استخراج کردهاید استفاده کنید. اکثر کتابخانههای JOSE توابعی برای مدیریت این درستیسنجی ارائه میدهند.
اگر هر پنج مرحله موفقیتآمیز باشد، نشانی ایمیل را درمقابل ارائهدهنده درستیسنجی کردهاید. درغیراینصورت، طبق جریان عادیتان، به ارسال ایمیل تأیید برای کاربر برگردید.
پیادهسازی خدمات صادرکننده و ارائهدهنده ایمیل
برای جزئیات بیشتر، میتوانید نسخه نمایشی ارائهدهنده ایمیل ساختگی کد را گامبهگام دنبال کنید و به مراحل صادرکننده در API درستیسنجی ایمیل و پیشنهادهای پروتکل درستیسنجی ایمیل مراجعه کنید.
بهعنوان صادرکننده، نیازی به ثبتنام برای آزمایش مبدأ یا ارائه رمز ندارید، زیرا رفتار مرورگر توسط سایت طرف اعتماد فعال میشود. فقط باید مطمئن شوید که نقاط پایانی موردانتظار برای پاسخ دادن به این درخواستها در جای خود قرار دارند.
پیکربندی کاوش صادرکننده
برای اینکه مرورگرها بتوانند بهطور خودکار نقاط پایانی درستیسنجی شما را هنگام انتخاب نشانی ایمیل متعلق به دامنهتان پیدا کنند، پیکربندیتان را بااستفاده از «ساناد» و نقطه پایانی .well-known پروتکل انتقال ابرمتن نمایان کنید.
پیکربندی گزارش نماینده ساناد
سابقه ساناد TXT را در دامنه ایمیلتان پیکربندی کنید که اختیار درستیسنجی را به
شناسه صادرکننده شما واگذار میکند. این شناسهها میتوانند از همان دامنه استفاده کنند
بسته به زیرساخت شما.
قالب ضبط: _email-verification.<email-domain>
فایل منطقه نمونه:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
میزبانی نقطه پایانی .well-known/email-verification
فایل فراداده JSON را در دامنه صادرکننده خود تحت مسیر /.well-known/ میزبانی کنید.
این فایل قابلیتهای صدور شما و الگوریتمهای امضای رمزنگاریشدهای را که زیرساختتان پشتیبانی میکند مشخص میکند.
نقطه پایانی: https://<issuer-domain>/.well-known/email-verification
پاسخ نمونه:
{
"issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
"jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["EdDSA", "ES256"]
}
میزبانی نقطه پایانی .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/x-www-form-urlencoded POST
حاوی request_token را دریافت میکند.
بخشهای زیر فرایند کامل رسیدگی به درخواستهای صدور را نشان میدهد.
۱. درخواست صدور را اعتبارسنجی کنید
را بخوانیدتجزیه و اعتبارسنجی کردن محمولههای مرورگر ورودی:
- روش:
POST - درستیسنجی جلسه: کوکیهای طرف اول کاربر را که همراه با درخواست ارسال شدهاند
session/authenticationدرستیسنجی کنید تا مطمئن شوید زمینه هویت فعال و مجاز وجود دارد. - درستیسنجی پارامتر: پارامتر
request_tokenرا استخراج کنید (یک JWT امضاشده که توسط مرورگر تولید شده است). تأیید کنید که حاوی کلید عمومی موقت موردانتظار، ایمیل هدف، مخاطب صحیح، و مُهر زمان معتبر باشد.
رمزینه رمزگشاییشده باید چیزی شبیه به این باشد:
{
"decodedHeader": {
"alg": "ES256",
"typ": "JWT",
"jwk": {
"kty": "EC",
"crv": "P-256",
"x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
"y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
}
},
"decodedPayload": {
"iss": "https://accounts.issuer.example",
"sub": "demo@example.com",
"email": "demo@example.com",
"iat": 1780272000,
"exp": 1780272300
},
"signature": "SIGnatURE-123_SIGnatURE-123_SIGnatURE-123"
}
۲. پاسخ با کد
پساز درستیسنجی موفق جلسه و کد درخواست، بااستفاده از بار داده، یک JWT امضاشده «افشای انتخابی» (SD-JWT) تولید کنید:
{
"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
}
بار را بااستفاده از کلید خصوصی و الگوریتم پشتیبانیشده امضا کنید. برای مثال، استفاده از jose در Node.js:
const evtJwt = await new SignJWT(evtPayload)
.setProtectedHeader({
alg: "EdDSA",
kid: PRIVATE_KEY_JWK.kid, // Key ID corresponding to our JWKS keys
typ: "evt+jwt", // Standard Token Type for EVTs
})
.sign(privateKey);
// Standard SD-JWT compatibility requires appending a trailing tilde "~"
// to separate the signed token from the key binding section.
const issuanceToken = `${evtJwt}~`;
نمونه پاسخ موفق (HTTP 200):
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
ملاحظات آزمایش معرفی ویژگی جدید
آزمایشهای معرفی ویژگی جدید برای جمعآوری بازخورد انجام میشوند، بنابراین اگر بهعنوان طرف اتکا یا ارائهدهنده هویت شرکت میکنید، ورودی شما بسیار مهم است. برای گزارش کردن مشکلات، از مخزنهای GitHub زیر استفاده کنید:
- Browser Email Verification API: WICG/email-verification
- پروتکل درستیسنجی ایمیل: dickhardt/email-verification
اگر در پیادهسازی Chrome با اشکالاتی مواجه شدید، اشکال را دربرابر این عنصر گزارش کنید:
فعال کردن عملکرد آزمایش مبدأ براساس هر پاسخ و با افزودن نشان OT کنترل میشود. این یعنی اگر ترجیح میدهید عملکرد را به بخشی از کاربران خود محدود کنید، کنترل دقیقی دارید. برای مثال، اگر ازقبل چارچوب آزمایش A/B دارید، میتوانید آزمایش اصلی را در آنجا برای جمعیت آزمایش کنترلشده ادغام کنید. یا اگر گروهی از کاربران دارید که آزمایش بتا یا پیشنمایش زودرس انجام میدهند، ممکن است بخواهید یا نیاز داشته باشید این ویژگی را برای آنها فعال کنید. در این مورد، قبلاز صدور یا تأیید اعتبار رمز، نشانی ایمیل ارائهشده را بررسی کنید.
آزمایشهای معرفی ویژگی جدید همچنین محدودیتهای ترافیکی دارند تا سایتهایی که قبلاز راهاندازی به این ویژگی تکیه میکنند به حداقل برسند. میانای برنامهسازی کاربردی صادرکننده درحال توسعه است و باید انتظار تغییرات ناسازگار با نسخههای قبلی را همراه با بهروزرسانیهای «تجربه کاربری Chrome» داشته باشید.
با پیشرفت توسعه، بهروزرسانیهای بیشتری در وبلاگ اینجا و در فهرست پستی evp-announce@chromium.org منتشر خواهیم کرد.