La API de Play Integrity para PC te ayuda a verificar que las interacciones y las solicitudes del servidor provengan de un dispositivo para PC original. Cuando se detectan interacciones potencialmente riesgosas y fraudulentas, el servidor de backend de tu app puede responder con las medidas adecuadas para evitar los ataques y reducir los abusos.
La API devuelve veredictos que te ayudan a detectar posibles amenazas, incluidos los siguientes:
- Dispositivos y entornos riesgosos: El veredicto
deviceIntegrityte ayuda a determinar si tu app se ejecuta en un dispositivo para PC original o en una instancia original de Google Play Juegos para PC.
Realiza la integración con la API
Para integrar la API de Play Integrity para PC en tu app, primero debes realizar la configuración inicial en Google Cloud Console. Después de eso, debes seguir los siguientes pasos para cada verificación de integridad:
- Prepara tu token de integridad
- Solicita tu token de integridad
- Solicita datos de tokens
Configuración inicial en Google Cloud Console
Cada app o SDK que llame a la API de Play Integrity debe usar un proyecto de Google Cloud para autenticar sus llamadas y supervisar el uso de la API. Si quieres crear un proyecto nuevo de Cloud o tu app se distribuye de forma exclusiva fuera de Google Play, puedes habilitar las respuestas de la API de Play Integrity desde la consola de Google Cloud.
En la consola de Google Cloud, crea un proyecto de Cloud nuevo o elige uno existente que desees usar con la API de Play Integrity para PC. Navega a APIs y servicios. Selecciona Habilitar APIs y servicios. Busca la API de Play Integrity y, luego, habilítala. Ahora puedes integrar la API de Play Integrity en tu app.
Paso 1: Prepara tu token de integridad
void PrepareIntegrityToken( const PrepareIntegrityTokenParams & params, PrepareIntegrityTokenContinuation continuation )
Antes de solicitar un token de integridad (consulta RequestIntegrityToken), debes preparar (o "precalentar") la API de Play Integrity. Esto permite que Google Play almacene en la caché del dispositivo la información de certificación parcial de forma inteligente para disminuir la latencia en la ruta de acceso crítica cuando solicitas un veredicto de integridad.
Si la operación se realiza correctamente, se llamará a la continuación con un PrepareIntegrityTokenResultValue que contiene un RequestTokenData que se debe usar para solicitar un token de integridad. Estos datos deben almacenarse en caché en la memoria y reutilizarse durante la sesión de la aplicación para las llamadas a RequestIntegrityToken. Solo si tu aplicación determina que es necesario volver a evaluar por completo el veredicto de integridad, se debe realizar una llamada a PrepareIntegrityToken.
| Detalles | |
|---|---|
| Parámetros | params: Son parámetros que contienen un número de proyecto de Google Cloud. continuation: Es la devolución de llamada asíncrona a la que se debe devolver el proveedor de tokens de integridad. |
Paso 2: Solicita tu token de integridad
void RequestIntegrityToken( const RequestIntegrityTokenParams & params, RequestIntegrityTokenContinuation continuation )
Los tokens de integridad son un mecanismo para que tu aplicación verifique que el dispositivo no se haya alterado. Por ejemplo, tu servidor de backend puede usar el token de integridad para verificar lo siguiente:
- Dispositivo original: Determina si tu aplicación se ejecuta en un dispositivo original que contiene una instancia original de Google Play Juegos para PC y no se manipuló.
Cuando verifiques una acción del usuario en tu app con la API de Play Integrity para PC, puedes usar el campo RequestIntegrityTokenParams::request_hash para mitigar los ataques de manipulación. Por ejemplo, es posible que un juego quiera informar la puntuación del jugador al servidor de backend del juego, y que tu servidor quiera verificar que esta puntuación no haya sido manipulada por un servidor proxy. La API de Play Integrity muestra el valor que estableces en este campo, dentro de la respuesta de integridad firmada. Sin el requestHash, el token de integridad se vinculará solo al dispositivo, pero no a la solicitud específica, lo que abre la posibilidad de un ataque.
Para mitigar este problema cuando solicitas un veredicto de integridad, haz lo siguiente:
- Calcula un resumen de todos los parámetros de solicitud relevantes (p. ej., SHA256 de una serialización de solicitud estable) de la acción del usuario o la solicitud del servidor que está sucediendo.
- Establece el campo RequestIntegrityTokenParams::request_hash en el resumen.
| Detalles | |
|---|---|
| Parámetros | params: Parámetros que contienen el RequestTokenData preparado y el hash de la solicitud de verificación de integridad. continuation: Es la devolución de llamada asíncrona para devolver los datos. |
Paso 3: Solicita datos del token
Después de solicitar un veredicto de integridad, la API de Play Integrity proporciona un token de respuesta encriptado. Para obtener los veredictos de integridad del dispositivo, debes desencriptar el token de integridad en los servidores de Google. Para hacerlo, completa estos pasos:
- Crea una cuenta de servicio dentro del proyecto de Google Cloud que esté vinculado a tu app.
En el servidor de la app, recupera el token de acceso de las credenciales de la cuenta de servicio con el permiso playintegrity y realiza la siguiente solicitud:
playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \ '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'Lee la respuesta JSON.
La carga útil resultante es un token de texto sin formato que contiene veredictos y detalles de integridad junto con la información que proporciona el desarrollador. El formato del token es el siguiente:
{
"requestDetails": { ... },
"deviceIntegrity": { ... },
}
Antes de verificar cada veredicto de integridad, debes comprobar que los valores del campo requestDetails coincidan con los de la solicitud original. En las siguientes secciones, se describe cada campo con mayor detalle.
Campo de detalles de la solicitud
El campo requestDetails contiene información sobre la solicitud, incluida la información proporcionada por el desarrollador en el requestHash de las solicitudes estándar y en el nonce de las solicitudes clásicas.
"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",
}
Estos valores deben coincidir con los de la solicitud original. Por lo tanto, verifica la parte requestDetails de la carga útil de JSON asegurándote de que requestPackageName y requestHash coincidan con lo que se envió en la solicitud original.
Campo de integridad del dispositivo
El campo deviceIntegrity puede contener un solo valor, deviceRecognitionVerdict, que tenga una o más etiquetas que representen la capacidad de un dispositivo para aplicar de manera forzosa la integridad de la app. Si un dispositivo no cumple con los criterios de ninguna etiqueta, el campo deviceIntegrity omite deviceRecognitionVerdict.
"deviceIntegrity": {
"deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
De forma predeterminada, deviceRecognitionVerdict puede contener lo siguiente:
MEETS_PC_INTEGRITY- Devuelve un veredicto si la app se ejecuta en un entorno de PC original, en el que no se detectó ninguna manipulación en el dispositivo.
- Vacío (un valor en blanco)
- La app se está ejecutando en un dispositivo que muestra indicios de ataque (como trampas de API) o de vulneración del sistema (como un dispositivo con permisos de administrador), o bien no se está ejecutando en un dispositivo físico (como un emulador que no pasa las verificaciones de integridad de Google Play).
Límites de uso
Límites de uso de la API de Play Integrity
Tu app estará sujeta a un máximo de 10,000 solicitudes totales por día. Si tu app necesita controlar una mayor cantidad de usuarios, puedes solicitar que se aumente este máximo diario siguiendo las instrucciones que se indican a continuación.
| Acción | Cuota diaria por app | Notes |
|---|---|---|
| Solicitudes de tokens | 10,000 | Se comparte entre la API de Play Integrity para PC y la API de Play Integrity para solicitudes clásicas y estándar. |
| Desencriptaciones de tokens en los servidores de Google | 10,000 | Se comparte entre la API de Play Integrity para PC y la API de Play Integrity para solicitudes clásicas y estándar. |
Cómo aumentar la cantidad máxima diaria de solicitudes
Para poder recibir un aumento en la cantidad máxima diaria de solicitudes, la app debe estar disponible en Google Play, además de cualquier otro canal de distribución.
Para solicitar un aumento en la cantidad máxima diaria de solicitudes, haz lo siguiente:
- Vincula el proyecto de Google Cloud que usas para la API de Play Integrity en Play Console.
- Verifica que estés implementando correctamente la lógica de API, incluida la estrategia de reintento recomendada.
- Solicita un aumento de la cuota con este formulario.
El aumento de la cuota de la API de Play Integrity puede tardar hasta una semana, por lo que te recomendamos que supervises el uso de la API de Play Integrity en Google Play Console o en la consola de Google Cloud, donde también puedes establecer alertas de cuota para evitar interrupciones del servicio.
Los aumentos de cuota se aplican automáticamente a la llamada del cliente para generar tokens de integridad y a la llamada del servidor para desencriptar y verificar los tokens de integridad.
Consideraciones de seguridad
La API de Play Integrity brinda el máximo valor a tu app cuando sigues estas prácticas recomendadas:
Asegúrate de contar con una estrategia contra el abuso
La API de Play Integrity funciona mejor cuando se usa junto con otros indicadores como parte de tu estrategia general contra el abuso y no como tu único mecanismo antiabuso. Usa esta API junto con otras prácticas recomendadas de seguridad para tu app. De forma predeterminada, tu app puede realizar hasta 10,000 solicitudes totales por día en todas las instalaciones. Puedes solicitar que se aumente tu máximo diario.
Recopila información sobre la telemetría y comprende a tu público antes de realizar acciones
Antes de cambiar el comportamiento de tu app según los veredictos de la API de Play Integrity, puedes comprender la situación actual con tu público existente implementando la API sin aplicación forzosa. Una vez que sepas qué veredictos muestra tu base de instalaciones actual, puedes estimar el impacto de cualquier aplicación forzosa que estés planeando y ajustar tu estrategia contra el abuso según corresponda.
Cómo solicitar un veredicto de integridad en el momento oportuno
Debes realizar solicitudes a la API lo más cerca posible del momento de la acción o la solicitud del servidor que quieres proteger.
Haz que tus solicitudes a la API sean difíciles de replicar
Las solicitudes a la API tienen un campo llamado requestHash que se usa para proteger contra la manipulación y ataques similares. En este campo, debes incluir un resumen de todos los valores relevantes de la solicitud de tu app. Sigue las instrucciones para usar la vinculación de contenido y proteger las solicitudes estándar de tu app.
Evita que los veredictos de integridad se almacenen en caché
El almacenamiento en caché de los veredictos de integridad aumenta el riesgo de generar proxies, que es un ataque en el que una entidad que actúa de mala fe reutiliza un veredicto de un dispositivo confiable con fines abusivos en otro entorno.
Envía un rango de respuestas del servidor a la app
Tener un rango de resultados de decisión es más difícil de replicar que enviar una respuesta binaria de permiso / denegación del servidor a la app para cada respuesta. Por ejemplo, puedes usar una serie de respuestas relacionadas, como Permitir, Permitir con límites, Permitir con límites después de que se complete el captcha y Rechazar.
Muestra mensajes de error prácticos
Cuando sea posible, proporciona mensajes de error útiles al usuario y dile qué hacer para solucionarlo.
Ten un plan para problemas inesperados o interrupciones
En el panel de estado de Play, se muestra información sobre el estado del servicio de la API de Play Integrity, así como información sobre cualquier interrupción. Debes planificar con anticipación cómo quieres que funcione el servidor de backend en el caso improbable de una interrupción a gran escala de la API de Play Integrity.
Condiciones del Servicio y seguridad de los datos
Cuando accedes a la API de Play Integrity para PC o la usas, aceptas sus Condiciones del Servicio. Asegúrate de leer y entender todas las condiciones y políticas aplicables antes de acceder a la API.
Google Play tiene una sección de Seguridad de los datos para que los desarrolladores divulguen las prácticas de seguridad, uso compartido y recopilación de datos de sus apps y mantener informados a sus usuarios. Para ayudarte a completar el formulario de datos, consulta la siguiente información sobre cómo la API de Play Integrity controla los datos.