پروتکل تأیید ایمیل را با یک نسخه آزمایشی اصلی آزمایش کنید

Rowan Merewood

منتشر شده: ۸ ژوئیه ۲۰۲۶

هنگام جمع‌آوری آدرس ایمیل به عنوان بخشی از ثبت نام، ورود به سیستم، اشتراک، پرداخت، بازیابی حساب یا سایر فرآیندها، معمولاً تأیید می‌شود که آدرس ایمیل متعلق به شخصی است که آن را وارد می‌کند. روش‌های تأیید موجود، مانند رمزهای عبور یکبار مصرف (OTP) یا پیوندهای تأیید ایمیل (پیوندهای جادویی)، کاربر را ملزم به خروج از سایت شما می‌کنند. این فرآیند مخرب می‌تواند خطر ترک کامل جلسه توسط کاربر، چه انسان و چه عامل، و عدم تکمیل فرآیند تأیید هویت را افزایش دهد.

API تأیید ایمیل پیشنهادی است که به مرورگر اجازه می‌دهد مستقیماً با ارائه‌دهنده ایمیل ارتباط برقرار کند تا تأیید کند که کاربر مالک آدرس ایمیل است. کاربران یک ایمیل را از پیشنهاد تکمیل خودکار یا تکمیل خودکار مرورگر انتخاب می‌کنند، فرم را ارسال می‌کنند و سایت بدون ارسال ایمیل یا قطع جریان کاربر، آدرس ایمیل را با ارائه‌دهنده تأیید می‌کند.

جمع‌آوری ایمیل یک نقطه تبدیل حیاتی در مسیر کاربر است و کروم به بازخورد سایت‌هایی که می‌خواهند ایمیل‌ها را تأیید کنند، ارائه‌دهندگان ایمیلی که می‌توانند تأیید را انجام دهند و کاربرانی که این فرآیند را تجربه می‌کنند، در مورد این پیشنهاد علاقه‌مند است. می‌توانید همین امروز در نسخه آزمایشی origin ثبت‌نام کنید و دستورالعمل‌های پیاده‌سازی را اینجا دنبال کنید. برای پیکربندی عمومی نسخه آزمایشی origin، به شروع به کار با نسخه‌های آزمایشی origin مراجعه کنید.

می‌توانید روند کار را با یک حساب آزمایشی امتحان کنید:

• نسخه آزمایشی صادرکننده، یک حساب ایمیل و جلسه آزمایشی به شما ارائه می‌دهد
• نسخه آزمایشی تأییدکننده، هر ارائه‌دهنده شرکت‌کننده را تأیید خواهد کرد.

جریان تأیید ایمیل

بخش‌های بعدی توضیح می‌دهند که شما و کاربرانتان برای شروع جریان تأیید ایمیل به چه چیزهایی نیاز دارید و کل گردش کار هنگام استفاده از پروتکل تأیید ایمیل چگونه است.

اصطلاحات کلیدی

اصطلاحات کلیدی برای API تأیید ایمیل به شرح زیر است:

• تأییدکننده : سایتی که آدرس ایمیل را جمع‌آوری می‌کند و می‌خواهد آن را تأیید کند. تأییدکننده، طرف اتکاکننده نیز نامیده می‌شود.
• ارائه دهنده ایمیل : سرویسی که آدرس ایمیل کاربر را ارائه می‌دهد، به عنوان مثال gmail.com .
• صادرکننده : سرویسی که حساب ایمیل کاربر را مدیریت می‌کند، برای مثال accounts.google.com . صادرکننده، ارائه‌دهنده هویت نیز نامیده می‌شود.

در برخی موارد، ارائه‌دهنده ایمیل و صادرکننده ممکن است از یک دامنه مشترک فعالیت کنند. با این حال، مهم است که بین داشتن یک آدرس ایمیل و داشتن یک جلسه فعال برای حساب مرتبط، تمایز قائل شویم.

پیش‌نیازها

• کاربر باید در همان نمایه مرورگر به ارائه دهنده یا صادرکننده ایمیل خود وارد شود. به عنوان مثال، اگر از Gmail استفاده می‌کند، باید وارد حساب Google خود شود.
• به عنوان یک سایت تأییدکننده مشارکتی، باید برای نسخه آزمایشی Origin ثبت نام کنید و توکن را در همان صفحه فرم ایمیل خود ارائه دهید.

• کاربر باید آدرس ایمیل خود را از منوی کشویی تکمیل خودکار یا تکمیل خودکار انتخاب کند.

  • اگر کاربر قبلاً آدرس ایمیلی را در این فیلد وارد کرده باشد، با استفاده از قابلیت تکمیل خودکار، آن را پیشنهاد می‌دهد.

  • اگر کاربر آدرس ایمیل خود را با استفاده از تنظیمات کروم «تکمیل خودکار و رمز عبور» ( chrome://settings/autofill ) اضافه کرده باشد، استفاده از تکمیل خودکار به او پیشنهاد می‌شود.

• اولین باری که کاربر آدرس ایمیل خود را برای تأیید ارائه می‌دهد، درخواست مجوز را مشاهده خواهد کرد. این اتفاق فقط یک بار برای هر آدرس ایمیل رخ می‌دهد.

زمانی که کاربر آن جلسه فعال را در مرورگر خود داشته باشد، می‌تواند فرآیند را شروع کند:

1. در فرمی که فیلد ایمیل دارد، کاربر آدرس ایمیل خود را از منوی کشویی تکمیل خودکار انتخاب می‌کند. سایت تأییدکننده یک فیلد پنهان در فرم با یک nonce برای هر نمونه برای تأیید این درخواست ارائه می‌دهد.

2. سپس مرورگر رکورد DNS تأیید ایمیل را برای دامنه ایمیل بازیابی می‌کند. این کار مرورگر را به صادرکننده ایمیل هدایت می‌کند. صادرکننده ایمیل تأیید می‌کند که یک جلسه فعال برای آن آدرس ایمیل دارد.

3. سپس صادرکننده، توکن تأیید ایمیل (EVT) خود را برای آدرس ارائه می‌دهد. مرورگر آن را با EVT، مبدأ سایت و nonce از فرم ورودی، در یک JWT متصل به کلید ترکیب می‌کند.

4. وقتی فرم ارسال می‌شود، بسته EVT به فیلد پنهان اضافه شده و به سایت ارسال می‌شود.

5. سپس سایت تأییدکننده، تک تک این جزئیات را تأیید می‌کند: آدرس ایمیل مورد انتظار، نانس و امضاهای مرورگر و صادرکننده.

6. کاربر یک اعلان کوچک مشاهده می‌کند که به او اطلاع می‌دهد ارائه‌دهنده ایمیل، آدرس او را تأیید کرده است.

این فرآیند به سایت تأییدکننده تأیید می‌کند که آدرس ایمیل معتبر است و متعلق به کاربر فعلی است، به این معنی که سایت می‌تواند از ارسال ایمیل تأیید صرف نظر کند.

کاربران می‌توانند ایمیل‌های تأیید شده خود را در مسیر تنظیمات > تکمیل خودکار و رمزهای عبور > اطلاعات تماس > ایمیل تأیید شده مدیریت کنند (یا chrome://settings/contactInfo را باز کنند).

ملاحظات مورد استفاده

تأیید ایمیل یک پیشرفت تدریجی در جریان فعلی شماست که نیاز کاربر را برای ترک سایت شما برای بازیابی یک رمز عبور یکبار مصرف یا کلیک روی یک لینک از بین می‌برد. سایت‌ها می‌توانند فیلدهای تأیید ایمیل را به تمام فرم‌های مربوطه، مانند ورود به سیستم، ثبت نام در خبرنامه، ایجاد حساب کاربری و بازیابی رمز عبور اضافه کنند. EVP فقط در صورتی فعال می‌شود که مرورگر از آن پشتیبانی کند. اگر هیچ کدی هنگام ارسال دریافت نشود یا هر یک از مراحل اعتبارسنجی با شکست مواجه شود، می‌توانید به جریان تأیید ایمیل پیش‌فرض خود برگردید. این همچنین به این معنی است که هیچ تشخیص ویژگی برای API وجود ندارد. سایت تأییدکننده، EVT را اختیاری در نظر می‌گیرد و در صورت وجود در درخواست، آن را پردازش می‌کند.

تأیید ایمیل تأیید می‌کند که کاربر یک جلسه فعال با ارائه‌دهنده آدرس ایمیل خود دارد. این تأیید نمی‌کند که ایمیل شما به کاربر رسیده است. ممکن است هنوز بخواهید ایمیل‌های خوشامدگویی یا معرفی موجود را ارسال کنید و ممکن است بخواهید یا نیاز داشته باشید که کاربر را به بررسی تنظیمات هرزنامه خود ترغیب کنید.

پیاده‌سازی سایت تأییدکننده

برای جزئیات بیشتر، می‌توانید کد آزمایشی سرتاسری را بررسی کنید و به مراحل اعتبارسنجی در پیشنهادهای API تأیید ایمیل و پروتکل تأیید ایمیل مراجعه کنید.

پیکربندی فیلدهای فرم

مطمئن شوید که فیلدهای فرم شما ویژگی‌های صحیحی دارند:

<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" قرار دهید. سایت باید یک nonce منحصر به فردِ وابسته به جلسه ارائه دهد تا ارسال فرم را تأیید کند.
• مقدار autocomplete="email-verification-token" را تنظیم کنید. مرورگر از این ویژگی برای شناسایی فیلدی که باید پر شود استفاده می‌کند.

با بررسی پنل Network در DevTools، عناصر فرم خود را اعتبارسنجی کنید. وقتی یک آدرس ایمیل را انتخاب می‌کنید، می‌بینید که مرورگر، DNS و درخواست‌های جستجوی حساب بعدی را برای ارائه‌دهنده و صادرکننده ایمیل فعال می‌کند. اینها درخواست‌های داخلی مرورگر هستند؛ سایت شما تا زمان ارسال فرم چیزی دریافت نمی‌کند.

اعتبارسنجی EVT

پنج مرحله برای اعتبارسنجی هر جزء از بسته EVT وجود دارد.

1. توکن را تجزیه کنید.
2. اعتبارسنجی مقادیر مورد انتظار
3. اعتبارسنجی اتصال کلید.
4. اعتبارسنجی رکورد DNS.
5. صادرکننده را کشف کنید و امضای EVT را تأیید کنید.

۱. تجزیه توکن

داده‌های خام حاصل از ارسال فرم شامل EVT و ادعاهای امضا شده در یک Selective Disclosure JSON Web Token (SD-JWT+KB) است که با یک کاراکتر ~ از هم جدا شده‌اند. شما باید این موارد را جدا کرده و هدرها و payloadهای Javascript Object Signing and Encryption (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"
  }
}

۲. اعتبارسنجی مقادیر مورد انتظار

بررسی کنید که مقادیر اولیه در payload با مقادیر ارائه شده شما مطابقت داشته باشند:

• تأیید کنید که email_verified روی true تنظیم شده باشد.
• تأیید کنید که email با آدرس ایمیل ارائه شده در فرم شما مطابقت دارد.
• تأیید کنید که nonce با nonce ارائه شده در فرم شما مطابقت دارد.
• تأیید کنید که aud با مبدا سایت شما مطابقت دارد.
• تأیید کنید که iat دارای یک مهر زمانی نسبتاً جدید است، برای مثال، پس از رندر شدن فرم.

۳. اعتبارسنجی اتصال کلید

مرورگر یک کلید موقت و زودگذر برای تراکنش ایجاد می‌کند تا تأیید کند که توکن را امضا کرده است. این کلید را از ادعای cnf (تأیید) در EVT استخراج کنید و سپس از آن برای تأیید JWT متصل به کلید استفاده کنید.

سپس، هش مورد انتظار را محاسبه کرده و آن را با ادعای sd_hash مقایسه کنید. مثال Node.js زیر نحوه انجام این محاسبه را نشان می‌دهد:

const calculatedHash = createHash("sha256")
        .update(evtJwt + "~")
        .digest("base64url");

۴. اعتبارسنجی رکورد DNS

رکورد DNS مربوط به دامنه آدرس ایمیل _email-verification را بررسی کنید. برای مثال، برای demo@gmail.com ، رکورد TXT _email-verification.gmail.com را جستجو کنید. برای این ارائه دهنده، جستجو، مکان ارائه دهنده حساب، یعنی 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"]
}

از JWKها برای تأیید EVT JWT که از توکن استخراج کرده‌اید استفاده کنید. اکثر کتابخانه‌های JOSE توابعی را برای مدیریت این تأیید ارائه می‌دهند.

اگر هر پنج مرحله با موفقیت انجام شد، آدرس ایمیل را در مقابل ارائه دهنده تأیید کرده‌اید. در غیر این صورت، طبق روال عادی خود، یک ایمیل تأیید برای کاربر ارسال کنید.

پیاده‌سازی سرویس ارائه‌دهنده و صادرکننده ایمیل

برای جزئیات بیشتر، می‌توانید کد آزمایشی ارائه‌دهنده ایمیل را بررسی کنید و به مراحل صادرکننده در پیشنهادهای API تأیید ایمیل و پروتکل تأیید ایمیل مراجعه کنید.

به عنوان صادرکننده، نیازی به ثبت نام در نسخه آزمایشی اصلی یا ارائه توکن ندارید زیرا رفتار مرورگر توسط سایت طرف اعتمادکننده ایجاد می‌شود. شما فقط باید مطمئن شوید که نقاط پایانی مورد انتظار برای پاسخ به آن درخواست‌ها در محل خود قرار دارند.

پیکربندی کشف صادرکننده

برای اینکه مرورگرها بتوانند هنگام انتخاب آدرس ایمیل متعلق به دامنه شما، به طور خودکار نقاط پایانی تأیید شما را کشف کنند، پیکربندی خود را با استفاده از DNS و یک نقطه پایانی HTTP .well-known نمایش دهید.

پیکربندی رکورد نماینده DNS

یک رکورد DNS 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 دیگر که ممکن است قبلاً به عنوان بخشی از API مربوط به Federated Credentials (FedCM) پیاده‌سازی کرده باشید. این منبع، لینک‌هایی به نقطه پایانی حساب‌های شما و URL ورود به سیستم ارائه می‌دهد.

نقطه پایانی: https://<domain>/.well-known/web-identity

پاسخ نمونه:

{
  "accounts_endpoint": "https://accounts.issuer.example/accounts",
  "login_url": "https://accounts.issuer.example/login"
}

از یک نقطه پایانی حساب‌ها استفاده کنید

نقطه پایانی حساب‌ها از API FedCM فهرستی از حساب‌های وارد شده در حال حاضر را ارائه می‌دهد. مثال زیر یک پاسخ حداقلی را نشان می‌دهد. برای جزئیات بیشتر، به راهنمای پیاده‌سازی ارائه‌دهنده هویت مراجعه کنید.

نقطه پایانی: همانطور که در .well-known/web-identity مشخص شده است

نمونه پاسخ زیر است:

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

ادغام با API وضعیت ورود

کاربر باید یک جلسه فعال با ارائه دهنده داشته باشد و شما باید این را با استفاده از API وضعیت ورود به سیستم به مرورگر اطلاع دهید.

وقتی کاربری با موفقیت وارد سیستم شد یا از سیستم خارج شد، هدر پاسخ HTTP منطبق را ارائه بده:

Set-Login: logged-in
Set-Login: logged-out

روش دیگر، به‌روزرسانی وضعیت با استفاده از جاوا اسکریپت در متن برنامه وب شماست:

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

رسیدگی به درخواست‌های صدور

issuance_endpoint شما یک درخواست POST application/x-www-form-urlencoded دریافت می‌کند که حاوی 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) با استفاده از 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
}

فایل اجرایی را با استفاده از کلید خصوصی و الگوریتم پشتیبانی‌شده خود امضا کنید. برای مثال، با استفاده از 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...~"
}

ملاحظات مربوط به آزمایش مبدا

آزمایش‌های Origin آزمایش‌هایی برای جمع‌آوری بازخورد هستند، بنابراین اگر به عنوان یک طرف وابسته یا ارائه‌دهنده هویت در آنها شرکت می‌کنید، نظرات شما بسیار مهم است. برای گزارش مشکلات، از مخازن GitHub زیر استفاده کنید:

• API تأیید ایمیل مرورگر: WICG/email-verification
• پروتکل تأیید ایمیل: dickhardt/email-verification

اگر در پیاده‌سازی کروم با اشکالی مواجه شدید، اشکال را به کامپوننت مربوطه گزارش دهید:

• شماره جدید: کرومیوم > بلینک > هویت > EVP

فعال کردن قابلیت آزمایش اولیه (Origin trial) بر اساس هر پاسخ و با وارد کردن توکن OT توسط شما کنترل می‌شود. این بدان معناست که اگر ترجیح می‌دهید این قابلیت را به بخشی از کاربران خود محدود کنید، کنترل دقیقی بر آن دارید. به عنوان مثال، اگر از قبل یک چارچوب آزمایش A/B دارید، می‌توانید آزمایش اولیه را برای یک جمعیت آزمایشی کنترل‌شده در آنجا ادغام کنید. از طرف دیگر، اگر یک گروه آزمایشی بتا یا پیش‌نمایش اولیه از کاربران دارید، ممکن است بخواهید یا نیاز داشته باشید که این ویژگی را برای آنها فعال کنید. در این صورت، قبل از صدور یا اعتبارسنجی توکن، آدرس ایمیل ارائه شده را بررسی کنید.

نسخه‌های آزمایشی Origin همچنین محدودیت‌های ترافیکی دارند تا سایت‌هایی که قبل از راه‌اندازی به این ویژگی متکی هستند را به حداقل برسانند. API صادرکننده در حال توسعه است و باید انتظار تغییرات ناسازگار با نسخه‌های قبلی و به‌روزرسانی‌های Chrome UX را داشته باشید.

با پیشرفت توسعه، به‌روزرسانی‌های بیشتر را در وبلاگ اینجا و در فهرست پستی evp-announce@chromium.org منتشر خواهیم کرد.