راهنمای توسعه دهنده توکن های دولتی خصوصی

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

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

توکن‌های خصوصی دولتی (که قبلاً با نام توکن‌های اعتماد شناخته می‌شدند) امکان اعتماد به اصالت کاربر را از یک زمینه به زمینه دیگر منتقل می‌کنند و در عین حال به سایت‌ها کمک می‌کنند تا با کلاهبرداری مبارزه کرده و ربات‌ها را از انسان‌های واقعی تشخیص دهند - بدون ردیابی غیرفعال.

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

توکن‌های خصوصی دولتی چگونه کار می‌کنند؟

رابطه کلیدی که باید در PST درک شود، بین صادرکنندگان و بازخریدکنندگان است. صادرکنندگان و بازخریدکنندگان می‌توانند در یک شرکت باشند.

• صادرکنندگان - این نهادها سیگنال‌هایی در مورد یک کاربر دارند (مثلاً اینکه آیا آن کاربر یک ربات است یا خیر) و آن سیگنال را در یک توکن که در دستگاه کاربر ذخیره می‌شود، جاسازی می‌کنند (جزئیات بیشتر در بخش‌های بعدی).
• بازخریدکنندگان - این نهادها ممکن است سیگنالی در مورد یک کاربر نداشته باشند، اما باید چیزی در مورد آنها بدانند (مثلاً اینکه آیا آن کاربر یک ربات است یا خیر) و درخواست بازخرید یک توکن از صادرکننده را داشته باشند تا از قابل اعتماد بودن آن کاربر مطلع شوند.

هر تعامل PST مستلزم آن است که صادرکنندگان و بازخریدکنندگان برای به اشتراک گذاشتن سیگنال‌ها در سراسر وب با یکدیگر همکاری کنند. این سیگنال‌ها مقادیر کلی هستند که به اندازه کافی دقیق نیستند تا افراد را شناسایی کنند.

آیا توکن‌های دولتی خصوصی برای من مناسب هستند؟

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

صدور و بازخرید توکن‌ها

پیاده‌سازی PST در سه مرحله انجام می‌شود:

1. صدور توکن‌ها
2. توکن‌های بازخرید
3. ارسال رکورد بازخرید

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

استراتژی توکن خود را تعریف کنید

برای تعریف استراتژی توکن خود، باید مفاهیم کلیدی PST (توکن‌ها و رکوردهای بازخرید)، متغیرها، رفتارها و محدودیت‌های آن را درک کنید تا بتوانید در مورد کاربرد بالقوه آنها برای مورد استفاده خود فکر کنید.

توکن‌ها و سوابق بازخرید: چه رابطه‌ای بین آنها وجود دارد؟

هر دستگاه می‌تواند تا ۵۰۰ توکن را در هر وب‌سایت و صادرکننده سطح بالا ذخیره کند. همچنین، هر توکن دارای فراداده‌ای است که نشان می‌دهد صادرکننده از کدام کلید برای صدور آن استفاده کرده است. از این اطلاعات می‌توان برای تصمیم‌گیری در مورد بازخرید یا عدم بازخرید یک توکن در طول فرآیند بازخرید استفاده کرد. داده‌های PST به صورت داخلی توسط مرورگر دستگاه کاربر ذخیره می‌شوند و فقط توسط API PST قابل دسترسی هستند.

وقتی یک توکن بازخرید می‌شود، رکورد بازخرید (RR) در دستگاه ذخیره می‌شود. این حافظه به عنوان حافظه پنهان برای بازخریدهای آینده عمل می‌کند. محدودیت بازخرید دو توکن در هر ۴۸ ساعت ، برای هر دستگاه، صفحه و صادرکننده وجود دارد. فراخوانی‌های بازخرید جدید در صورت امکان از RRهای ذخیره شده استفاده می‌کنند، نه اینکه باعث ایجاد درخواست به صادرکننده شوند.

1. توکن‌های جدید صادر می‌شوند (حداکثر ۵۰۰ عدد برای هر صادرکننده، سایت و دستگاه).
2. همه توکن‌ها در محل ذخیره توکن دستگاه (مشابه محل ذخیره کوکی‌ها) ذخیره می‌شوند.
3. اگر هیچ RR فعالی پیدا نشود، می‌توان RR های جدید را پس از صدور ایجاد کرد (حداکثر ۲ عدد در هر ۴۸ ساعت).
4. RRها تا زمان انقضا فعال در نظر گرفته می‌شوند و به عنوان حافظه پنهان محلی استفاده می‌شوند.
5. فراخوانی‌های جدید بازخرید در حافظه پنهان محلی ذخیره می‌شوند (هیچ RR جدیدی ایجاد نمی‌شود).

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

قبل از تعریف استراتژی خود، مطمئن شوید که رفتارها و متغیرهای حیاتی زیر را درک کرده‌اید:

سناریوهای مثال

سناریوی شماره ۱: طول عمر RR کمتر از ۲۴ ساعت است (t=t) و بازخرید چندین بار در طول بازه ۴۸ ساعته انجام می‌شود.

سناریوی شماره ۲: طول عمر RR، ۲۴ ساعت است و بازخرید چندین بار در طول بازه ۴۸ ساعته انجام می‌شود.

سناریوی شماره ۳: طول عمر RR، ۴۸ ساعت است و بازخرید در طول این ۴۸ ساعت چندین بار انجام می‌شود.

اجرای نسخه آزمایشی

قبل از پذیرش PST، توصیه می‌کنیم نسخه آزمایشی (دمو) را نصب کنید.

با اجرای این نسخه آزمایشی، مرورگر شما از سرورهای صادرکننده و بازخرید نسخه آزمایشی برای ارائه و مصرف توکن‌ها استفاده می‌کند.

ملاحظات فنی

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

• قبل از اجرای کروم با پرچم‌ها، مطمئن شوید که تمام نمونه‌های کروم را متوقف کرده‌اید.
• اگر روی دستگاه ویندوزی کار می‌کنید، به این راهنما در مورد نحوه ارسال پارامترها به فایل اجرایی کروم نگاهی بیندازید.
• هنگام استفاده از برنامه آزمایشی، Chrome DevTools را در مسیر Applications > Storage > Private State Tokens باز کنید تا توکن‌های صادر شده یا بازخرید شده توسط صادرکننده نسخه آزمایشی را مشاهده کنید.

برای فرزندخواندگی آماده شوید

این بخش الزامات لازم برای تبدیل شدن به صادرکننده یا بازخریدکننده PST را توضیح می‌دهد.

صادرکننده شوید

صادرکنندگان نقش کلیدی در PST ایفا می‌کنند. آنها به توکن‌ها مقادیری اختصاص می‌دهند تا مشخص شود که آیا کاربر ربات است یا خیر. اگر می‌خواهید به عنوان صادرکننده، PST را شروع کنید، باید با تکمیل فرآیند ثبت نام صادرکننده، ثبت نام کنید.

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

سرورهای صادرکننده

صادرکنندگان و بازخریدکنندگان، بازیگران کلیدی PST هستند؛ سرورها و توکن‌ها ابزارهای کلیدی PST هستند. اگرچه قبلاً جزئیاتی در مورد توکن‌ها و در مستندات GitHub ارائه داده‌ایم، می‌خواستیم جزئیات بیشتری در مورد سرورهای PST ارائه دهیم. برای راه‌اندازی به عنوان صادرکننده PST، ابتدا باید یک سرور صادرکننده راه‌اندازی کنید.

محیط خود را مستقر کنید: سرورهای صادرکننده

برای پیاده‌سازی سرور صادرکننده توکن، باید برنامه سمت سرور خودتان را بسازید که نقاط انتهایی HTTP را در معرض نمایش قرار دهد.

مؤلفه صادرکننده از دو ماژول اصلی تشکیل شده است: (1) سرور صادرکننده و (2) صادرکننده توکن.

همانند تمام برنامه‌های تحت وب، توصیه می‌کنیم یک لایه حفاظتی اضافی برای سرور صادرکننده خود در نظر بگیرید.

1. سرور صادرکننده: در پیاده‌سازی مثال ما، سرور صادرکننده یک سرور Node.js است که از چارچوب Express برای میزبانی نقاط پایانی HTTP صادرکننده استفاده می‌کند. می‌توانید نمونه کد را در GitHub بررسی کنید.

2. صادرکننده توکن: مؤلفه رمزنگاری صادرکننده به هیچ زبان خاصی نیاز ندارد، اما به دلیل الزامات عملکرد این مؤلفه، ما یک پیاده‌سازی C را به عنوان نمونه ارائه می‌دهیم که از کتابخانه Boring SSL برای مدیریت توکن‌ها استفاده می‌کند. می‌توانید نمونه کد صادرکننده و اطلاعات بیشتر در مورد نصب را در GitHub پیدا کنید.

3. کلیدها: مؤلفه صادرکننده توکن از کلیدهای EC سفارشی برای رمزگذاری توکن‌ها استفاده می‌کند. این کلیدها باید محافظت شده و در یک فضای امن ذخیره شوند.

الزامات فنی برای سرورهای صادرکننده

طبق پروتکل، شما باید حداقل دو نقطه پایانی HTTP را در سرور صادرکننده خود پیاده‌سازی کنید:

• Key-commitment (برای مثال، /.well-known/private-state-token/key-commitment ): این نقطه پایانی جایی است که جزئیات کلید عمومی رمزگذاری شما برای مرورگرها در دسترس خواهد بود تا تأیید شود که سرور شما قانونی است.
  • نمونه کد در گیت‌هاب
  • نسخه آزمایشی را ببینید
• صدور توکن (برای مثال، /.well-known/private-state-token/issuance ): نقطه پایانی صدور توکن که در آن تمام درخواست‌های توکن مدیریت می‌شوند. این نقطه پایانی، نقطه ادغام برای مولفه صادرکننده توکن خواهد بود.
  • نمونه کد در گیت‌هاب
  • مشاهده نسخه نمایشی

همانطور که قبلاً ذکر شد، با توجه به ترافیک بالای مورد انتظار که این سرور به طور بالقوه مدیریت خواهد کرد، توصیه می‌کنیم آن را با استفاده از یک زیرساخت مقیاس‌پذیر (مثلاً در یک محیط ابری) مستقر کنید تا بتوانید backend خود را بر اساس تقاضای متغیر تنظیم کنید.

ارسال تماس به سرور صادرکننده

برای صدور توکن‌های جدید، یک فراخوانی برای دریافت از وب‌سایت به پشته صادرکننده خود پیاده‌سازی کنید.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

یک نمونه کد را ببینید .

سرورهای بازخرید

شما باید سرویس بازخرید توکن را با ساخت برنامه سمت سرور خود پیاده‌سازی کنید. این به شما امکان می‌دهد توکن‌هایی را که صادرکننده ارسال می‌کند بخوانید. مراحل زیر نحوه بازخرید توکن‌ها و همچنین نحوه خواندن سوابق بازخرید مرتبط با آن توکن‌ها را شرح می‌دهد.

می‌توانید انتخاب کنید که صادرکننده و بازخریدکننده در یک سرور (یا گروهی از سرورها) اجرا شوند.

الزامات فنی برای سرورهای بازخرید

طبق پروتکل، شما باید حداقل دو نقطه پایانی HTTP را برای سرور بازخرید خود پیاده‌سازی کنید:

• /.well-known/private-state-token/redemption : نقطه پایانی که تمام بازخرید توکن‌ها در آن انجام خواهد شد. این نقطه پایانی جایی خواهد بود که مؤلفه بازخرید توکن در آن ادغام می‌شود.
  • کد نمونه در گیت‌هاب
  • نسخه آزمایشی

ارسال تماس به سرور بازخرید

برای بازخرید توکن‌ها، باید یک فراخوانی برای فراخوانی وب‌سایت به پشته بازخرید خود پیاده‌سازی کنید تا توکن‌های صادر شده قبلی را بازخرید کنید.

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

نمونه کد را ببینید.

پس از بازخرید یک توکن، می‌توانید رکورد بازخرید (RR) را با انجام یک فراخوانی واکشی دیگر ارسال کنید:

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

نمونه کد را ببینید.

پیاده‌سازی خود را مستقر کنید

برای آزمایش پیاده‌سازی خود، ابتدا به صفحه وبی که فراخوانی صدور توکن در آن انجام شده است بروید و تأیید کنید که توکن(ها) طبق منطق شما ایجاد شده‌اند. در backend خود تأیید کنید که فراخوانی‌ها طبق مشخصات انجام شده‌اند. سپس، به صفحه وبی که فراخوانی بازخرید در آن انجام شده است بروید و تأیید کنید که RRها طبق منطق شما ایجاد شده‌اند.

استقرار در دنیای واقعی

توصیه می‌کنیم وب‌سایت‌های هدفی را انتخاب کنید که بخشی از مورد استفاده خاص شما باشند:

• تعداد کم بازدیدهای ماهانه (~ کمتر از ۱ میلیون بازدید در ماه): شما باید ابتدا API را برای مخاطبان کمی مستقر کنید.
• شما مالک آن هستید و آن را کنترل می‌کنید: در صورت لزوم می‌توانید به سرعت و بدون نیاز به تأییدیه‌های پیچیده، پیاده‌سازی را غیرفعال کنید.
• بیش از یک صادرکننده مجاز نیست: برای محدود کردن تعداد توکن‌ها به منظور ساده‌سازی آزمایش.
• بیش از دو بازخرید مجاز نیست: در صورت بروز مشکل، باید عیب‌یابی را ساده کنید.

سیاست مجوزها

برای عملکرد صحیح، API مربوط به PST باید در صفحه سطح بالا و هر زیرمنبعی که از API استفاده می‌کند، در دسترس باشد.

عملیات درخواست توکن توسط دستورالعمل private-state-token-issuance کنترل می‌شود. عملیات‌های token-redemption و send-redemption-record توسط دستورالعمل private-state-token-redemption کنترل می‌شوند. در کروم ۱۳۲ و بالاتر، لیست مجاز برای این دستورالعمل‌ها به طور پیش‌فرض روی * (همه مبداها) تنظیم شده است. این بدان معناست که این ویژگی بدون تفویض صریح، در صفحه سطح بالا، iframe های same-origin و iframe های cross-origin در دسترس است.

شما می‌توانید با وارد کردن private-state-token-issuance=() و private-state-token-redemption=() در سربرگ Permissions-Policy برای هر صفحه، از صدور یا بازخرید توکن PST برای صفحات خاصی در سایت خود انصراف دهید.

همچنین می‌توانید از هدر Permissions-Policy برای کنترل دسترسی شخص ثالث به PST استفاده کنید. به عنوان پارامترهای لیست مبدا هدر، از self و هر مبدایی که می‌خواهید به API اجازه دسترسی بدهید، استفاده کنید. به عنوان مثال، برای غیرفعال کردن کامل استفاده از PST در تمام زمینه‌های مرور به جز مبدا خودتان و https://example.com ، هدرهای پاسخ HTTP زیر را تنظیم کنید:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

برای فعال کردن API برای همه منابع بین مبدایی، لیست مبدا را روی * تنظیم کنید.

بیاموزید که چگونه ویژگی‌های Privacy Sandbox را با استفاده از Permissions Policy کنترل کنید یا عمیق‌تر در مورد Permissions Policy کاوش کنید.

عیب‌یابی

شما می‌توانید فایل‌های PST را از تب‌های Chrome DevTools Network و Application بررسی کنید.

در برگه شبکه:

در برگه برنامه:

درباره این ادغام DevTools بیشتر بخوانید.

بهترین شیوه‌های مشتری

اگر عملکردهای حیاتی وب‌سایت شما به صادرکنندگان توکن خاصی بستگی دارد، آنها را اولویت‌بندی کنید. قبل از بارگذاری هر اسکریپت دیگری hasPrivateToken(issuer) برای این صادرکنندگان ترجیحی فراخوانی کنید. این امر برای جلوگیری از شکست‌های احتمالی در بازخرید بسیار مهم است.

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

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

بهترین شیوه‌های سرور و عیب‌یابی

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

• دستگاه‌های شما باید با استفاده از TLS 1.3 یا 1.2 از رمزنگاری قوی استفاده کنند.
• زیرساخت شما باید برای مدیریت حجم ترافیک متغیر (از جمله افزایش ناگهانی) آماده باشد.
• مطمئن شوید که کلیدهای شما محافظت‌شده و ایمن هستند و با سیاست کنترل دسترسی، استراتژی مدیریت کلید و برنامه‌های تداوم کسب‌وکار شما همسو می‌باشند.
• معیارهای مشاهده‌پذیری را به پشته خود اضافه کنید تا مطمئن شوید که پس از رفتن به مرحله تولید، قابلیت مشاهده برای درک میزان استفاده، گلوگاه‌ها و مشکلات عملکرد را خواهید داشت.

اطلاعات بیشتر

1. بررسی اسناد توسعه‌دهنده:
   1. برای آشنایی با PST و قابلیت‌های آن، ابتدا مرور کلی را مطالعه کنید.
   2. ویدیوی معرفی PST را تماشا کنید.
   3. نسخه آزمایشی PST را امتحان کنید.
   4. همچنین برای درک جزئیات بیشتر در مورد آن، توضیح API را مطالعه کنید.
   5. درباره مشخصات فعلی API بیشتر بخوانید.
2. با استفاده از مسائل گیت‌هاب یا فراخوان‌های W3C در گفتگو مشارکت کنید.
3. برای درک بهتر هر یک از اصطلاحات، واژه‌نامه Privacy Sandbox را مرور کنید.
4. برای کسب اطلاعات بیشتر در مورد مفاهیم کروم، مانند «نسخه آزمایشی اصلی» یا «پرچم‌های کروم»، ویدیوهای کوتاه و مقالات موجود در goo.gle/cc را مرور کنید.