Добавить API целостности воспроизведения

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

API возвращает вердикты, которые помогают обнаружить потенциальные угрозы, в том числе:

• Рискованные устройства и среды: вердикт deviceIntegrity помогает вам определить, работает ли ваше приложение на подлинном ПК-устройстве или на подлинном экземпляре Google Play Игр для ПК.

Интеграция с API

Чтобы интегрировать Play Integrity API для ПК в ваше приложение, необходимо сначала выполнить первоначальную настройку в Google Cloud Console. После этого для каждой проверки целостности необходимо выполнить следующие шаги:

1. Подготовьте свой токен целостности
2. Запросите свой токен целостности
3. Запрос данных токена

Первоначальная настройка в Google Cloud Console

Каждое приложение или SDK, обращающееся к Play Integrity API, должно использовать проект Google Cloud для аутентификации вызовов и мониторинга использования API. Если вы хотите создать новый проект Cloud или ваше приложение распространяется исключительно за пределами Google Play, вы можете включить ответы Play Integrity API в консоли Google Cloud.

В консоли Google Cloud Console создайте новый облачный проект или выберите существующий, который вы хотите использовать с API Play Integrity для ПК. Перейдите в раздел API и службы . Выберите «Включить API и службы» . Найдите Play Integrity API и включите его. Теперь вы можете интегрировать API Play Integrity в своё приложение.

Шаг 1: Подготовьте свой токен целостности

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Перед запросом токена целостности (см. RequestIntegrityToken ) необходимо подготовить (или «разогреть») API целостности Play. Это позволит Google Play интеллектуально кэшировать информацию о частичной аттестации на устройстве, чтобы уменьшить задержку на критическом пути при запросе вердикта целостности.

В случае успешного выполнения будет вызвано продолжение с PrepareIntegrityTokenResultValue , содержащим RequestTokenData , который следует использовать для запроса токена целостности. Эти данные следует кэшировать в памяти и использовать повторно в течение сеанса приложения для вызовов RequestIntegrityToken . Вызов PrepareIntegrityToken следует выполнять только в том случае, если приложение определит необходимость полной повторной оценки целостности.

Шаг 2: Запросите токен целостности

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

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

• Подлинное устройство: Определите, работает ли ваше приложение на подлинном устройстве, содержащем подлинный экземпляр Google Play Игр для ПК и не подвергшемся подделке.

При проверке действий пользователя в вашем приложении с помощью API Play Integrity для ПК вы можете использовать поле RequestIntegrityTokenParams::request_hash для защиты от подмены данных. Например, игра может передавать счёт игрока на свой внутренний сервер, а ваш сервер должен убедиться, что этот счёт не был подменён прокси-сервером. API Play Integrity возвращает значение, заданное в этом поле, в подписанном ответе проверки целостности. Без requestHash токен целостности будет привязан только к устройству, а не к конкретному запросу, что открывает возможность атаки.

Чтобы смягчить это при запросе вердикта о целостности:

• Вычислите дайджест всех соответствующих параметров запроса (например, SHA256 стабильной сериализации запроса) из действия пользователя или запроса сервера, который происходит.
• Установите поле RequestIntegrityTokenParams::request_hash в соответствии с дайджестом.

Шаг 3: Запрос данных токена

После запроса вердикта целостности API Play Integrity предоставляет зашифрованный токен ответа. Чтобы получить вердикт целостности устройства, необходимо расшифровать токен целостности на серверах Google. Для этого выполните следующие действия:

1. Создайте учетную запись службы в проекте Google Cloud, связанную с вашим приложением.

2. На сервере вашего приложения извлеките токен доступа из учетных данных вашей службы, используя область playintegrity, и выполните следующий запрос:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. Прочитайте ответ JSON.

Полученная полезная нагрузка представляет собой простой текстовый токен, содержащий вердикты о целостности и подробную информацию, а также информацию, предоставленную разработчиком. Формат токена следующий:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

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

Поле запроса данных

Поле requestDetails содержит информацию о запросе, включая предоставленную разработчиком информацию в requestHash для стандартных запросов и nonce для классических запросов.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

Эти значения должны совпадать со значениями исходного запроса. Поэтому проверьте раздел requestDetails полезной нагрузки JSON, убедившись, что requestPackageName и requestHash соответствуют значениям, отправленным в исходном запросе.

Поле целостности устройства

Поле deviceIntegrity может содержать одно значение deviceRecognitionVerdict , которое имеет одну или несколько меток, отражающих эффективность обеспечения целостности приложения устройством. Если устройство не соответствует критериям ни одной из меток, поле deviceIntegrity не содержит deviceRecognitionVerdict .

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

По умолчанию deviceRecognitionVerdict может содержать следующее:

MEETS_PC_INTEGRITY

Возвращает вердикт, работает ли приложение в реальной среде ПК, где не было обнаружено никаких вмешательств на устройстве.

Пусто (пустое значение)

Приложение запущено на устройстве, имеющем признаки атаки (например, перехват API) или взлома системы (например, наличие прав root), либо приложение не запущено на физическом устройстве (например, эмулятор, не прошедший проверку целостности Google Play).

Ограничения по использованию

Ограничения на использование API Play Integrity

Максимальное количество запросов для вашего приложения — 10 000 в день. Вы можете запросить увеличение этого дневного лимита, следуя инструкциям ниже, если вашему приложению необходимо обрабатывать большее количество пользователей.

Увеличьте максимальное количество ежедневных запросов

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

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

1. Подключите проект Google Cloud, который вы используете для API Play Integrity в Play Console.
2. Убедитесь, что вы правильно реализуете логику API, включая рекомендуемую стратегию повторных попыток.
3. Подайте запрос на увеличение квоты, используя эту форму .

Увеличение квоты Play Integrity API может занять до недели, поэтому мы настоятельно рекомендуем отслеживать использование Play Integrity API в Google Play Console или в Google Cloud Console, где вы также можете настроить оповещения о квоте, чтобы избежать перебоев в предоставлении услуг.

Увеличение квоты автоматически применяется как к клиентскому вызову для генерации токенов целостности, так и к серверному вызову для расшифровки и проверки токенов целостности.

Соображения безопасности

API Play Integrity обеспечит максимальную отдачу для вашего приложения, если вы будете следовать следующим рекомендациям:

Иметь стратегию борьбы со злоупотреблениями

API Play Integrity наиболее эффективен при использовании вместе с другими сигналами в рамках вашей общей стратегии борьбы со злоупотреблениями, а не в качестве единственного механизма. Используйте этот API в сочетании с другими подходящими передовыми практиками обеспечения безопасности для вашего приложения. По умолчанию ваше приложение может выполнять до 10 000 запросов в день для всех установок. Вы можете запросить увеличение суточного лимита .

Собирайте телеметрию и изучайте свою аудиторию, прежде чем предпринимать какие-либо действия.

Прежде чем менять поведение приложения на основе вердиктов API Play Integrity, вы можете оценить текущую ситуацию с вашей текущей аудиторией, внедрив API без применения мер принудительного характера. Определив, какие вердикты выдаёт ваша текущая база установок, вы сможете оценить влияние любых планируемых мер принудительного характера и соответствующим образом скорректировать стратегию борьбы со злоупотреблениями.

Запросите вердикт о добросовестности в подходящий момент

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

Сделайте так, чтобы ваши запросы API было сложно воспроизводить

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

Избегайте кэширования вердиктов о целостности

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

Отправьте ряд ответов с вашего сервера в ваше приложение

Воспроизвести диапазон результатов принятия решений сложнее, чем отправлять двоичный ответ «Разрешить/Запретить» с сервера обратно в приложение для каждого ответа. Например, можно использовать серию связанных ответов, таких как «Разрешить», «Разрешить с ограничениями», «Разрешить с ограничениями после прохождения CAPTCHA» и «Запретить».

Показывать сообщения об ошибках, требующие действий

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

Имейте план на случай непредвиденных проблем или сбоев

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

Условия обслуживания и безопасность данных

Получая доступ к Play Integrity API для ПК или используя его, вы соглашаетесь с Условиями использования Play Integrity API. Перед использованием API ознакомьтесь со всеми применимыми условиями и политиками.

В Google Play есть раздел безопасности данных, где разработчики могут раскрывать информацию о методах сбора, передачи и обеспечения безопасности данных в своих приложениях, чтобы информировать пользователей. Чтобы помочь вам заполнить форму данных, ознакомьтесь с этой информацией о том, как API Play Integrity обрабатывает данные.