Руководство для разработчиков частных государственных токенов

Ранее сторонние файлы cookie использовались для хранения и передачи информации о состоянии пользователя, такой как статус входа в систему, информация об используемом устройстве, а также о том, известен ли пользователь и является ли он доверенным. Например, о том, вошел ли пользователь с помощью единого входа (SSO), есть ли у пользователя определённый тип совместимого устройства, известен ли пользователь и является ли он доверенным. В связи с прекращением поддержки сторонних файлов cookie многие из этих вариантов использования должны будут поддерживаться другими способами.

Частные государственные токены предоставляют возможность обмениваться информацией через Интернет, но с сохранением конфиденциальности за счет контроля объема данных, которыми можно фактически поделиться.

Частные государственные токены (ранее известные как токены доверия) позволяют передавать доверие к подлинности пользователя из одного контекста в другой, одновременно помогая сайтам бороться с мошенничеством и отличать ботов от реальных людей — без пассивного отслеживания.

В этом документе описываются технические детали внедрения частных государственных токенов (PST). Более подробное описание см. в обзоре PST .

Как работают частные государственные токены?

Ключевая взаимосвязь в PST — это отношения между эмитентами и погашателями. Эмитенты и погашатели могут находиться в пределах одной компании.

• Эмитенты — эти сущности имеют определенный сигнал о пользователе (например, является ли этот пользователь ботом или нет) и встраивают этот сигнал в токен, который хранится на устройстве пользователя (подробнее в следующих разделах).
• Выкупщики . Эти субъекты могут не иметь сигнала о пользователе, но им необходимо знать о нем что-то (например, является ли этот пользователь ботом или нет) и просить выкупить токен у эмитента, чтобы понять надежность этого пользователя.

Каждое взаимодействие с PST требует от эмитентов и получателей совместных действий для обмена сигналами через интернет. Эти сигналы представляют собой грубые значения, недостаточно подробные для идентификации пользователей.

Подходят ли мне частные государственные токены?

Компании, принимающие решения о доверии и желающие, чтобы эта информация была доступна в любых контекстах, могут извлечь выгоду из PST-файлов. Подробнее о потенциальных вариантах использования PST см. в нашей документации по вариантам использования PST.

Выпуск и погашение токенов

Внедрение PST происходит в три этапа:

1. Выпуск токенов
2. Погашение токенов
3. Пересылка записи о погашении

На первом этапе токены выдаются браузеру (обычно после проверки). На втором этапе другая сторона отправляет запрос на погашение выпущенного токена, чтобы прочитать его значение. На последнем этапе сторона, выдающая токены, получает запись погашения (RR) со значением, содержащимся в токене. Эта сторона, выдающая токены, может затем использовать эту запись для подтверждения личности пользователя в различных целях.

Определите свою стратегию токенов

Чтобы определить стратегию использования токенов, вам необходимо понимать ключевые концепции PST (токены и записи о погашении), переменные, поведение и ограничения, чтобы иметь возможность продумать их потенциальное применение в вашем конкретном случае.

Токены и записи о погашении: какова связь между ними?

Каждое устройство может хранить до 500 токенов для каждого сайта верхнего уровня и эмитента. Кроме того, каждый токен содержит метаданные, сообщающие, какой ключ эмитент использовал для его выпуска. Эта информация может быть использована для принятия решения об использовании токена в процессе его использования. Данные PST хранятся внутри браузера на устройстве пользователя и доступны только через API PST.

При погашении токена на устройстве сохраняется запись погашения (RR). Это хранилище служит кэшем для будущих погашений. Существует ограничение на погашение двух токенов каждые 48 часов для каждого устройства, страницы и эмитента. Новые запросы на погашение будут по возможности использовать кэшированные записи погашения, а не отправлять запрос эмитенту.

1. Выпускаются новые токены (максимум 500 на эмитента, сайт и устройство).
2. Все токены хранятся в хранилище токенов на устройстве (аналогично хранилищу cookie-файлов).
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 мы рекомендуем вам ознакомиться с демонстрационной версией .

При запуске этой демо-версии ваш браузер использует демонстрационные серверы эмитента и поглотителя для предоставления и использования токенов.

Технические соображения

Демо-версия будет работать лучше всего, если вы выполните следующие шаги:

• Перед запуском Chrome с флагами обязательно остановите все экземпляры Chrome.
• Если вы работаете на компьютере с Windows, ознакомьтесь с этим руководством о том, как передать параметры исполняемому двоичному файлу Chrome.
• Откройте Chrome DevTools в разделе Приложения > Хранилище > Токены частного состояния при использовании демонстрационного приложения, чтобы увидеть токены, выпущенные или погашенные демонстрационным эмитентом.

Подготовка к усыновлению

В этом разделе объясняются требования для того, чтобы стать эмитентом или погашателем PST.

Стать эмитентом

Эмитенты играют ключевую роль в PST. Они присваивают токенам значения, чтобы определить, является ли пользователь ботом. Чтобы начать работу с PST в качестве эмитента, вам необходимо зарегистрироваться, пройдя процедуру регистрации эмитента.

Чтобы подать заявку на статус эмитента, оператор сайта эмитента должен создать новую задачу в репозитории GitHub , используя шаблон «Новый эмитент PST». Следуйте инструкциям в репозитории, чтобы заполнить задачу. После проверки конечной точки она будет добавлена ​​в этот репозиторий, и инфраструктура сервера 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 ): эта конечная точка — место, где данные вашего открытого ключа шифрования будут доступны браузерам для подтверждения легитимности вашего сервера.
  • Пример кода на GitHub
  • Посмотреть демо
• Выпуск токенов (например, /.well-known/private-state-token/issuance ): конечная точка выпуска токенов, где будут обрабатываться все запросы на токены. Эта конечная точка будет точкой интеграции для компонента выпуска токенов.
  • Пример кода на GitHub
  • Посмотреть демо

Как упоминалось ранее, из-за ожидаемого высокого трафика, который потенциально будет обрабатывать этот сервер, мы рекомендуем вам развернуть его с использованием масштабируемой инфраструктуры (например, в облачной среде), чтобы иметь возможность настраивать ваш бэкэнд в зависимости от изменяющегося спроса.

Отправить вызов на сервер эмитента

Реализуйте вызов выборки веб-сайта в стеке вашего эмитента для выпуска новых токенов.

 // 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 : конечная точка, где будут обрабатываться все выкупы токенов. В эту конечную точку будет интегрирован компонент выкупа токенов.
  • Пример кода на GitHub
  • Демо

Отправить вызов на сервер выкупа

Чтобы выкупить токены, вам необходимо реализовать вызов веб-сайта для извлечения данных из стека выкупа, чтобы выкупить ранее выпущенные токены.

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

См. пример кода .

Разверните вашу реализацию

Чтобы протестировать реализацию, сначала перейдите на веб-страницу, где выполняется вызов эмиссии, и убедитесь, что токены создаются в соответствии с вашей логикой. Убедитесь в бэкенде, что вызовы были выполнены в соответствии со спецификацией. Затем перейдите на веб-страницу, где выполняется вызов погашения, и убедитесь, что записи ресурсов создаются в соответствии с вашей логикой.

Реальное развертывание

Мы рекомендуем вам выбирать целевые веб-сайты, которые являются частью вашего конкретного варианта использования:

• Небольшое количество посещений в месяц (~ <1 миллиона посещений в месяц): сначала следует развернуть API для небольшой аудитории.
• Вы им владеете и управляете: при необходимости вы можете быстро отключить реализацию без сложных согласований.
• Не более одного эмитента: чтобы ограничить количество токенов с целью упрощения тестирования.
• Не более двух выкупщиков: необходимо упростить устранение неполадок в случае их возникновения.

Политика разрешений

Для правильной работы API PST должен быть доступен странице верхнего уровня и любым подресурсам, использующим этот API.

Операция запроса токена контролируется директивой private-state-token-issuance . Операции token-redemption и send-redemption-record контролируются директивой private-state-token-redemption . В Chrome версии 132 и более поздних версиях разрешённый список для этих директив по умолчанию установлен на * (все источники). Это означает, что функция доступна для страниц верхнего уровня, фреймов iframe с тем же источником и фреймов iframe с кросс-источником без явного делегирования.

Вы можете отказаться от выпуска или погашения токенов PST для определенных страниц вашего сайта, включив private-state-token-issuance=() и private-state-token-redemption=() в заголовок Permissions-Policy для каждой страницы.

Вы также можете использовать заголовок 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 с помощью политики разрешений или изучите ее подробнее.

Поиск неисправностей

Вы можете проверить PST-файлы на вкладках «Сеть» и «Приложение» в Chrome DevTools.

На вкладке Сеть:

На вкладке «Приложение»:

Узнайте больше об интеграции 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. Посмотрите ознакомительное видео о тихоокеанском времени .
   3. Попробуйте демо-версию PST.
   4. Также прочтите объяснение API, чтобы узнать о нем больше подробностей.
   5. Узнайте больше о текущей спецификации API.
2. Примите участие в обсуждении, используя вопросы GitHub или звонки W3C .
3. Чтобы лучше понять терминологию, ознакомьтесь с глоссарием Privacy Sandbox .
4. Чтобы узнать больше о таких концепциях Chrome, как «пробная версия Origin» или «флаги Chrome», просмотрите короткие видеоролики и статьи, доступные на goo.gle/cc .