L'API Play Integrity pour PC vous aide à vérifier que les interactions et les requêtes de serveur proviennent d'un PC authentique. Le serveur backend de votre application détecte les interactions potentiellement risquées et frauduleuses. Il peut ainsi répondre en prenant les mesures appropriées pour empêcher les attaques et réduire les abus.
L'API renvoie des verdicts qui vous aident à détecter les menaces potentielles, y compris :
- Appareils et environnements à risque : le verdict
deviceIntegrityvous aide à déterminer si votre application s'exécute sur un PC authentique ou sur une instance authentique de Google Play Jeux pour PC.
Intégrer l'API
Pour intégrer l'API Play Integrity pour PC à votre application, vous devez d'abord effectuer la configuration initiale dans la console Google Cloud. Ensuite, vous devez suivre les étapes suivantes pour chaque vérification de l'intégrité :
- Préparer votre jeton d'intégrité
- Demander votre jeton d'intégrité
- Demander des données de jeton
Configuration initiale dans la console Google Cloud
Chaque application ou SDK qui appelle l'API Play Integrity doit utiliser un projet Google Cloud pour authentifier ses appels et surveiller l'utilisation de l'API. Si vous souhaitez créer un projet Cloud ou que votre application est distribuée exclusivement en dehors de Google Play, vous pouvez activer les réponses de l'API Play Integrity à partir de la console Google Cloud.
Dans la console Google Cloud, créez un projet Cloud ou sélectionnez un projet Cloud existant que vous souhaitez utiliser avec l'API Play Integrity pour PC. Accédez à API et services. Sélectionnez Activer les API et les services. Recherchez l'API Play Integrity, puis activez-la. Vous pouvez désormais intégrer l'API Play Integrity à votre application.
Étape 1 : Préparez votre jeton d'intégrité
void PrepareIntegrityToken( const PrepareIntegrityTokenParams & params, PrepareIntegrityTokenContinuation continuation )
Avant de demander un jeton d'intégrité (voir RequestIntegrityToken), vous devez préparer (ou "échauffer") l'API Play Integrity. Cela permet à Google Play de mettre en cache intelligemment les informations d'attestation partielle sur l'appareil, afin de réduire la latence sur le chemin critique lorsque vous effectuez une requête d'évaluation de l'intégrité.
En cas de réussite, la continuation est appelée avec une PrepareIntegrityTokenResultValue contenant une RequestTokenData qui doit être utilisée pour demander un jeton d'intégrité. Ces données doivent être mises en cache en mémoire et réutilisées pendant toute la durée de la session de l'application pour les appels à RequestIntegrityToken. L'appel à PrepareIntegrityToken ne doit être effectué que si votre application détermine qu'il est nécessaire de réévaluer entièrement l'évaluation de l'intégrité.
| Détails | |
|---|---|
| Paramètres | params : paramètres contenant un numéro de projet Google Cloud. continuation : rappel asynchrone auquel renvoyer le fournisseur de jetons d'intégrité. |
Étape 2 : Demandez votre jeton d'intégrité
void RequestIntegrityToken( const RequestIntegrityTokenParams & params, RequestIntegrityTokenContinuation continuation )
Les jetons d'intégrité permettent à votre application de vérifier que l'appareil n'a pas été altéré. Par exemple, votre serveur backend peut utiliser le jeton d'intégrité pour vérifier les éléments suivants :
- Appareil authentique : déterminez si votre application s'exécute sur un appareil authentique contenant une instance authentique de Google Play Jeux pour PC et qui n'a pas été falsifié.
Lorsque vous vérifiez une action de l'utilisateur dans votre application avec l'API Play Integrity pour PC, vous pouvez utiliser le champ RequestIntegrityTokenParams::request_hash pour limiter les attaques par falsification. Par exemple, un jeu peut vouloir communiquer le score du joueur à son serveur backend, et votre serveur veut s'assurer que ce score n'a pas été modifié par un serveur proxy. L'API Play Integrity renvoie la valeur que vous avez définie dans ce champ, dans la réponse d'intégrité signée. Sans le champ requestHash, le jeton d'intégrité ne sera lié qu'à l'appareil, et non à la requête spécifique, ce qui n'exclut pas le risque d'attaque.
Pour y remédier lorsque vous demandez une évaluation de l'intégrité :
- Calculez un récapitulatif de tous les paramètres de requête pertinents (par exemple, SHA256 d'une sérialisation de requête stable) à partir de l'action de l'utilisateur ou de la requête de serveur en cours.
- Définissez le champ RequestIntegrityTokenParams::request_hash sur le condensé.
| Détails | |
|---|---|
| Paramètres | params : paramètres contenant l'objet RequestTokenData préparé et le hachage de la demande de vérification de l'intégrité. continuation : rappel asynchrone pour renvoyer les données. |
Étape 3 : Demandez les données du jeton
Une fois que vous avez demandé l'évaluation de l'intégrité, l'API Play Integrity fournit un jeton de réponse chiffré. Pour obtenir les évaluations de l'intégrité de l'appareil, vous devez déchiffrer le jeton d'intégrité sur les serveurs de Google. Pour cela, procédez comme suit :
- Créez un compte de service dans le projet Google Cloud associé à votre application.
Sur le serveur de votre application, récupérez le jeton d'accès à partir des identifiants de votre compte de service à l'aide du champ d'application playintegrity, puis exécutez la requête suivante :
playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \ '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'Lisez la réponse JSON.
La charge utile résultante est un jeton en texte brut contenant des évaluations et des détails sur l'intégrité, en plus des informations fournies par le développeur. Le format du jeton est le suivant :
{
"requestDetails": { ... },
"deviceIntegrity": { ... },
}
Vous devez d'abord vous assurer que les valeurs du champ requestDetails correspondent à celles de la requête d'origine avant de vérifier chaque évaluation d'intégrité. Les sections suivantes décrivent chaque champ plus en détail.
Champ "Détails de la requête"
Le champ requestDetails contient des informations sur la requête, y compris les informations fournies par le développeur dans requestHash pour les requêtes standards et nonce pour les requêtes classiques.
"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",
}
Ces valeurs doivent correspondre à celles de la requête d'origine. Par conséquent, vérifiez la partie requestDetails de la charge utile JSON en vous assurant que requestPackageName et requestHash correspondent à ce qui a été envoyé dans la requête d'origine.
Champ "Intégrité de l'appareil"
Le champ deviceIntegrity peut contenir une seule valeur, deviceRecognitionVerdict, comportant un ou plusieurs libellés représentant la capacité d'un appareil à appliquer l'intégrité des applications. Si un appareil ne répond aux critères d'aucun libellé, le champ deviceIntegrity omet deviceRecognitionVerdict.
"deviceIntegrity": {
"deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
Par défaut, deviceRecognitionVerdict peut contenir les éléments suivants :
MEETS_PC_INTEGRITY- Renvoie une évaluation si l'application s'exécute dans un environnement PC authentique, où aucune falsification sur l'appareil n'a été détectée.
- Vide (valeur vide)
- L'application est exécutée sur un appareil présentant des signes d'attaque (hook d'API, par exemple) ou un piratage du système (mode root, par exemple), ou elle n'est pas exécutée sur un appareil physique (un émulateur n'ayant pas réussi les contrôles d'intégrité de Google Play, par exemple).
Limites d'utilisation
Limites d'utilisation de l'API Play Integrity
Votre application sera soumise à une limite de 10 000 requêtes par jour au maximum. Vous pouvez demander à augmenter cette limite quotidienne en suivant les instructions ci-dessous si votre application doit gérer un plus grand nombre d'utilisateurs.
| Action | Quota quotidien par application | Notes |
|---|---|---|
| Demandes de jetons | 10 000 | Partagé entre l'API Play Integrity pour PC et l'API Play Integrity pour les requêtes classiques et standards |
| Déchiffrement des jetons sur les serveurs Google | 10 000 | Partagé entre l'API Play Integrity pour PC et l'API Play Integrity pour les requêtes classiques et standards |
Augmenter le nombre maximal de requêtes par jour
Pour pouvoir bénéficier d'une augmentation du nombre maximal de requêtes par jour, votre application doit être disponible sur Google Play en plus de tout autre canal de distribution.
Pour demander une augmentation du nombre maximal de requêtes quotidiennes, procédez comme suit :
- Associez le projet Google Cloud que vous utilisez pour l'API Play Integrity dans la Play Console.
- Vérifiez que vous implémentez correctement la logique d'API, y compris la stratégie recommandée concernant les nouvelles tentatives.
- Demandez une augmentation de quota à l'aide de ce formulaire.
L'augmentation du quota de l'API Play Integrity peut prendre jusqu'à une semaine. Nous vous recommandons donc vivement de surveiller votre utilisation de cette API dans la Google Play Console ou dans la console Google Cloud, où vous pouvez également définir des alertes de quota pour éviter toute interruption de service.
Les augmentations de quota sont automatiquement appliquées à l'appel du client pour générer des jetons d'intégrité et à l'appel du serveur pour déchiffrer et vérifier les jetons d'intégrité.
Points à noter concernant la sécurité
L'API Play Integrity offre des avantages sans égal pour votre application lorsque vous suivez les pratiques recommandées :
Appliquer une stratégie de lutte contre les abus
L'API Play Integrity fonctionne de manière optimale lorsqu'elle est combinée avec d'autres signaux dans votre stratégie globale de lutte contre les abus plutôt que lorsqu'elle est exécutée comme seul mécanisme de protection Utilisez cette API conjointement avec d'autres bonnes pratiques de sécurité adaptées à votre application. Par défaut, votre application peut effectuer jusqu'à 10 000 requêtes classiques par jour pour toutes les installations. Vous pouvez demander à augmenter votre limite quotidienne maximale.
Collecter des données télémétriques et cerner votre audience avant d'agir
Avant de modifier le comportement de votre application en fonction des évaluations de l'API Play Integrity, vous pouvez comprendre la situation actuelle de votre audience existante en implémentant l'API sans mesure d'application forcée. Une fois que vous avez obtenu l'évaluation que votre nombre d'installations actuel renvoie, vous pouvez estimer l'impact de toute mesure d'application envisagée et adapter votre stratégie de lutte contre les utilisations abusives en conséquence.
Demander une évaluation de l'intégrité au moment opportun
Vous devez envoyer des requêtes API le plus rapidement possible après l'action ou la requête de serveur à laquelle vous souhaitez empêcher l'accès.
Rendre les requêtes API difficiles à répliquer
Les requêtes API comportent un champ appelé "requestHash" qui protège les utilisateurs contre les accès non autorisés et les attaques similaires. Dans ce champ, vous devez inclure un récapitulatif de toutes les valeurs pertinentes de la requête de votre application. Suivez les instructions sur l'utilisation de la liaison de contenu pour protéger les requêtes standards de votre application.
Éviter la mise en cache des évaluations de l'intégrité
La mise en cache des évaluations de l'intégrité augmente le risque de proxying, qui constitue une attaque par laquelle un acteur malintentionné réutilise l'évaluation d'un bon appareil à des fins abusives dans un autre environnement.
Envoyer une plage de réponses de votre serveur à votre application
Il est plus difficile de répliquer une plage de résultats que de renvoyer une réponse binaire (réussite / échec) du serveur à l'application. Par exemple, vous pouvez opter pour une série de réponses associées ("Autoriser", "Autoriser avec des limites", "Autoriser avec des limites après la confirmation du CAPTCHA" et "Refuser", par exemple).
Afficher des messages d'erreur exploitables
Si possible, fournissez des messages d'erreur utiles qui indiquent à l'utilisateur ce qu'il peut faire pour résoudre le problème.
Anticiper les problèmes ou pannes inattendus
Le tableau de bord d'état de Play affiche des informations sur l'état de fonctionnement de l'API Play Integrity, ainsi que sur les perturbations et les pannes. Vous devez planifier à l'avance la manière dont votre serveur backend devra fonctionner dans l'éventualité peu probable d'une panne à grande échelle de l'API Play Integrity.
Conditions d'utilisation et sécurité des données
En accédant à l'API Play Integrity pour PC ou en l'utilisant, vous acceptez les conditions d'utilisation de l'API Play Integrity. Lisez et acceptez l'ensemble des conditions d'utilisation et des règles applicables avant d'accéder à l'API.
Google Play dispose d'une section sur la sécurité des données, qui permet aux développeurs de divulguer les pratiques de collecte, de partage et de sécurité des données de leurs applications afin d'en tenir les utilisateurs informés. Pour découvrir comment remplir votre formulaire de données, consultez ces informations sur la manière dont l'API Play Integrity traite les données.