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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سناریوی شماره 1: طول عمر RR کمتر از 24 ساعت است (t=t) و بازخرید چندین بار در طول پنجره 48 ساعته انجام می شود.

سناریوی شماره 2: طول عمر RR 24 ساعت است و بازخرید چندین بار در طول پنجره 48 ساعته انجام می شود.

سناریوی شماره 3: طول عمر RR 48 ساعت است و بازخرید چندین بار در طول پنجره 48 ساعت انجام می شود.

دمو را اجرا کنید

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

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

ملاحظات فنی

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

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

برای پذیرش تنظیم کنید

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

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

برای درخواست برای تبدیل شدن به یک صادرکننده، اپراتور وب سایت صادرکننده باید با استفاده از الگوی "New PST Issuer" یک شماره جدید در مخزن 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 ): نقطه پایانی صدور توکن که در آن تمام درخواست های توکن رسیدگی می شود. این نقطه پایانی، نقطه ادغام مؤلفه صادرکننده توکن خواهد بود.
  • کد نمونه

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

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

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

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

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

سرورهای Redeemer

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

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

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

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

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

یک تماس با سرور Redeemer ارسال کنید

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

    // 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>]
      }
    });

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

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

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

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

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

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

خط مشی مجوزها

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

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

می‌توانید با قرار دادن 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 برای همه منابع متقاطع، فهرست مبدا را روی * تنظیم کنید.

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

عیب یابی

می‌توانید PST‌ها را از برگه‌های «شبکه ابزارهای توسعه‌دهنده Chrome» و «برنامه» بررسی کنید.

در تب Network:

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

درباره این ادغام 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. از طریق مشکلات GitHub یا تماس های W3C در گفتگو مشارکت کنید.
3. برای درک بهتر هر یک از اصطلاحات، واژه نامه Privacy Sandbox را مرور کنید.
4. برای کسب اطلاعات بیشتر درباره مفاهیم Chrome، مانند «نسخه آزمایشی اصلی» یا «پرچم‌های Chrome»، ویدیوها و مقالات کوتاه موجود در goo.gle/cc را مرور کنید.