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

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

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

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

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

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

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

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

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

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

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

Выпуск и обмен токенов

Реализация PST происходит в три этапа:

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

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

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

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

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

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

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

1. Выпускаются новые токены (максимум 500 на каждого эмитента, сайт и устройство).
2. Все токены хранятся в хранилище токенов на устройстве (аналогично хранилищу файлов cookie).
3. Если активная запись не найдена, новые записи могут быть созданы после выдачи (максимум 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 с флагами.
• Если вы работаете на компьютере с Windows, прочтите это руководство о том, как передавать параметры в исполняемый файл Chrome.
• Откройте Chrome DevTools в разделе «Приложения» > «Хранилище» > «Токены частного состояния» при использовании демонстрационного приложения, чтобы просмотреть токены, выпущенные/погашенные эмитентом демо-версии.

Настроить на усыновление

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

Эмитенты играют ключевую роль в 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 на сервере-эмитенте:

• Обязательство ключа (например, /.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"
      }
    });

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

Серверы Искупителя

Вам нужно будет реализовать службу выкупа токенов, создав собственное серверное приложение. Это позволит вам читать токены, которые отправляет эмитент. Следующие шаги описывают, как выкупить токены, а также как прочитать записи о погашении, связанные с этими токенами.

Вы можете выбрать запуск эмитента и искупителя на одном сервере (или группе серверов).

Технические требования к серверам-редимерам

Согласно протоколу, вам необходимо реализовать как минимум две конечные точки 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>]
      }
    });

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

Разверните свою реализацию

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

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

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

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

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

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