Évaluations de l'intégrité

Cette page explique comment interpréter et utiliser l'évaluation de l'intégrité renvoyée. Que vous effectuiez une requête API standard ou classique, l'évaluation de l'intégrité est renvoyée au même format avec un contenu similaire. L'évaluation de l'intégrité communique des informations sur la validité des appareils, des applications et des comptes. Le serveur de votre application peut utiliser la charge utile générée dans une évaluation déchiffrée et validée pour déterminer la meilleure façon de procéder pour une action ou une requête particulière dans votre application.

Format de l'évaluation de l'intégrité renvoyée

La charge utile est au format JSON en texte brut et contient des signaux d'intégrité en plus des informations fournies par le développeur.

La structure de la charge utile générale est la suivante :

{
  requestDetails: { ... }
  appIntegrity: { ... }
  deviceIntegrity: { ... }
  accountDetails: { ... }
  environmentDetails: { ... }
}

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.

Pour les requêtes API standards :

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"
  // Request hash provided by the developer.
  requestHash: "aGVsbG8gd29scmQgdGhlcmU"
  // The timestamp in milliseconds when the integrity token
  // was requested.
  timestampMillis: "1675655009345"
}

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, comme dans l'extrait de code suivant :

val requestDetails = JSONObject(payload).getJSONObject("requestDetails")
val requestPackageName = requestDetails.getString("requestPackageName")
val requestHash = requestDetails.getString("requestHash")
val timestampMillis = requestDetails.getLong("timestampMillis")
val currentTimestampMillis = ...

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request
    || !requestHash.equals(expectedRequestHash)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

RequestDetails requestDetails =
    decodeIntegrityTokenResponse
    .getTokenPayloadExternal()
    .getRequestDetails();
String requestPackageName = requestDetails.getRequestPackageName();
String requestHash = requestDetails.getRequestHash();
long timestampMillis = requestDetails.getTimestampMillis();
long currentTimestampMillis = ...;

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request.
    || !requestHash.equals(expectedRequestHash)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

Pour les requêtes API 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"
  // base64-encoded URL-safe no-wrap nonce provided by the developer.
  nonce: "aGVsbG8gd29scmQgdGhlcmU"
  // The timestamp in milliseconds when the request was made
  // (computed on the server).
  timestampMillis: "1617893780"
}

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 nonce correspondent à ce qui a été envoyé dans la requête d'origine, comme dans l'extrait de code suivant :

val requestDetails = JSONObject(payload).getJSONObject("requestDetails")
val requestPackageName = requestDetails.getString("requestPackageName")
val nonce = requestDetails.getString("nonce")
val timestampMillis = requestDetails.getLong("timestampMillis")
val currentTimestampMillis = ...

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request. See 'Generate a nonce'
        // section of the doc on how to store/compute the expected nonce.
    || !nonce.equals(expectedNonce)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

JSONObject requestDetails =
    new JSONObject(payload).getJSONObject("requestDetails");
String requestPackageName = requestDetails.getString("requestPackageName");
String nonce = requestDetails.getString("nonce");
long timestampMillis = requestDetails.getLong("timestampMillis");
long currentTimestampMillis = ...;

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request. See 'Generate a nonce'
        // section of the doc on how to store/compute the expected nonce.
    || !nonce.equals(expectedNonce)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

Champ "Intégrité de l'application"

Le champ appIntegrity contient des informations liées au package.

appIntegrity: {
  // PLAY_RECOGNIZED, UNRECOGNIZED_VERSION, or UNEVALUATED.
  appRecognitionVerdict: "PLAY_RECOGNIZED"
  // The package name of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  packageName: "com.package.name"
  // The sha256 digest of app certificates (base64-encoded URL-safe).
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  certificateSha256Digest: ["6a6a1474b5cbbb2b1aa57e0bc3"]
  // The version of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  versionCode: "42"
}

appRecognitionVerdict peut avoir les valeurs suivantes :

PLAY_RECOGNIZED

L'application et le certificat correspondent aux versions distribuées par Google Play.

UNRECOGNIZED_VERSION

Le nom du certificat ou du package ne correspond pas aux données dont Google Play dispose.

UNEVALUATED

L'intégrité de l'application n'a pas été examinée. Une condition requise n'a pas été respectée (l'appareil n'est pas suffisamment fiable, par exemple).

Pour vous assurer que le jeton a été généré par une application que vous avez créée, vérifiez que l'intégrité de l'application est conforme aux attentes, comme indiqué dans l'extrait de code suivant :

val appIntegrity = JSONObject(payload).getJSONObject("appIntegrity")
val appRecognitionVerdict = appIntegrity.getString("appRecognitionVerdict")

if (appRecognitionVerdict == "PLAY_RECOGNIZED") {
    // Looks good!
}

JSONObject appIntegrity =
    new JSONObject(payload).getJSONObject("appIntegrity");
String appRecognitionVerdict =
    appIntegrity.getString("appRecognitionVerdict");

if (appRecognitionVerdict.equals("PLAY_RECOGNIZED")) {
    // Looks good!
}

Vous pouvez également vérifier manuellement le nom du package, la version et les certificats de l'application.

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 est vide.

deviceIntegrity: {
  // "MEETS_DEVICE_INTEGRITY" is one of several possible values.
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
}

Par défaut, deviceRecognitionVerdict peut contenir les éléments suivants :

MEETS_DEVICE_INTEGRITY

L'application s'exécute sur un appareil Android doté des services Google Play. L'appareil répond aux vérifications d'intégrité du système et respecte la configuration Android requise.

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).

Pour vous assurer que le jeton provient d'un appareil fiable, vérifiez que deviceRecognitionVerdict est conforme aux attentes, comme indiqué dans l'extrait de code suivant :

val deviceIntegrity =
    JSONObject(payload).getJSONObject("deviceIntegrity")
val deviceRecognitionVerdict =
    if (deviceIntegrity.has("deviceRecognitionVerdict")) {
        deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString()
    } else {
        ""
    }

if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) {
    // Looks good!
}

JSONObject deviceIntegrity =
    new JSONObject(payload).getJSONObject("deviceIntegrity");
String deviceRecognitionVerdict =
    deviceIntegrity.has("deviceRecognitionVerdict")
    ? deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString()
    : "";

if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) {
    // Looks good!
}

Si vous rencontrez des problèmes d'intégrité de votre appareil lors des tests, assurez-vous que la configuration ROM d'usine est installée (par exemple, en réinitialisant l'appareil) et que le bootloader est verrouillé. Vous pouvez également créer des tests API Play Integrity dans la Play Console.

Libellés d'appareils conditionnels

Si votre application est publiée sur Google Play Jeux pour PC, le deviceRecognitionVerdict peut également contenir le libellé suivant :

MEETS_VIRTUAL_INTEGRITY

L'application s'exécute sur un émulateur Android doté des services Google Play. L'émulateur réussit les contrôles d'intégrité du système et respecte la configuration Android requise.

Informations facultatives provenant des appareils

Si vous acceptez de recevoir des libellés supplémentaires dans l'évaluation de l'intégrité, deviceRecognitionVerdict peut avoir les libellés supplémentaires suivants :

MEETS_BASIC_INTEGRITY

L'application est exécutée sur un appareil qui réussit les contrôles d'intégrité de base du système. Cet appareil ne respecte peut-être pas la configuration Android requise et n'est peut-être pas autorisé à exécuter les services Google Play. Par exemple, il est possible que l'appareil exécute une version non reconnue d'Android, qu'il utilise un bootloader déverrouillé ou qu'il n'ait pas été certifié par le fabricant.

MEETS_STRONG_INTEGRITY

L'application est exécutée sur un appareil Android équipé des services Google Play et offre une bonne garantie de l'intégrité du système, telle qu'une preuve matérielle de l'intégrité du démarrage. L'appareil répond aux vérifications d'intégrité du système et respecte la configuration Android requise.

Un même appareil renvoie plusieurs libellés dans l'évaluation de l'intégrité de l'appareil si chacun des critères de ces libellés est rempli.

Activité récente de l'appareil

Vous pouvez également activer l'option permettant de connaître l'activité récente de l'appareil. Celle-ci indique le nombre de fois où votre application a demandé un jeton d'intégrité sur un appareil spécifique au cours de la dernière heure. Vous pouvez utiliser l'activité récente de l'appareil pour protéger votre application contre les appareils qui enregistrent une forte activité de manière anormale, ce qui peut être le signe qu'une attaque est en cours. Vous pouvez décider du niveau de confiance attribué à chaque niveau d'activité récente de l'appareil en fonction du nombre de fois que vous estimez qu'un jeton d'intégrité devrait être demandé par votre appli installée sur un appareil type au cours de chaque heure.

Si vous acceptez de recevoir recentDeviceActivity, le champ deviceIntegrity aura deux valeurs :

deviceIntegrity: {
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
  recentDeviceActivity: {
    // "LEVEL_2" is one of several possible values.
    deviceActivityLevel: "LEVEL_2"
  }
}

Les définitions des deviceActivityLevel diffèrent selon les modes et peuvent avoir l'une des valeurs suivantes:

Champ "Détails du compte"

Le champ accountDetails contient une seule valeur, appLicensingVerdict, qui représente l'état de la licence Google Play de l'application pour le compte utilisateur connecté sur l'appareil. Si le compte utilisateur dispose de la licence Play pour l'application, cela signifie qu'il l'a téléchargée ou achetée sur Google Play.

accountDetails: {
  // This field can be LICENSED, UNLICENSED, or UNEVALUATED.
  appLicensingVerdict: "LICENSED"
}

appLicensingVerdict peut avoir une des valeurs suivantes :

LICENSED

L'utilisateur est autorisé à accéder à l'application. En d'autres termes, il a installé ou acheté votre application sur Google Play.

UNLICENSED

L'utilisateur n'est pas autorisé à accéder à l'application. C'est par exemple le cas s'il télécharge votre application indépendamment ou sans passer par Google Play. Vous pouvez montrer la boîte de dialogue GET_LICENSED à l'utilisateur en réponse à ce problème.

UNEVALUATED

Les détails concernant la licence n'ont pas été examinés, car une condition requise n'était pas respectée.

Plusieurs raisons peuvent expliquer cette situation. Par exemple :

• L'appareil n'est pas suffisamment fiable.
• La version de votre application installée sur l'appareil est inconnue de Google Play.
• L'utilisateur n'est pas connecté à Google Play.

Pour vérifier que l'utilisateur dispose des droits d'accès à votre application, vérifiez que appLicensingVerdict est conforme aux attentes, comme indiqué dans l'extrait de code suivant :

val accountDetails = JSONObject(payload).getJSONObject("accountDetails")
val appLicensingVerdict = accountDetails.getString("appLicensingVerdict")

if (appLicensingVerdict == "LICENSED") {
    // Looks good!
}

JSONObject accountDetails =
    new JSONObject(payload).getJSONObject("accountDetails");
String appLicensingVerdict = accountDetails.getString("appLicensingVerdict");

if (appLicensingVerdict.equals("LICENSED")) {
    // Looks good!
}

Champ "Détails de l'environnement"

Vous pouvez également activer d'autres signaux sur l'environnement. Accès à l'application indique à votre application si d'autres applications en cours d'exécution peuvent être utilisées pour capturer l'écran, afficher des superpositions ou contrôler l'appareil. Play Protect l'évaluation vous indique si Google Play Protect est activé sur l'appareil il a détecté un logiciel malveillant connu.

Si vous avez activé l'évaluation du risque d'accès à l'application ou Play Protect dans la Google Play Console, la réponse de l'API inclura les environmentDetails. Le champ environmentDetails peut contenir deux Valeurs appAccessRiskVerdict et playProtectVerdict.

Évaluation du risque d'accès à l'appli (bêta)

Une fois activé, le champ environmentDetails de la charge utile de l'API Play Integrity contiendra la nouvelle évaluation du risque d'accès à l'application.

{
  requestDetails: { ... }
  appIntegrity: { ... }
  deviceIntegrity: { ... }
  accountDetails: { ... }
  environmentDetails: {
      appAccessRiskVerdict: {
          // This field contains one or more responses, for example the following.
          appsDetected: ["KNOWN_INSTALLED", "UNKNOWN_INSTALLED", "UNKNOWN_CAPTURING"]
      }
 }
}

Si le risque d'accès à l'application a été évalué, appAccessRiskVerdict contient le champ appsDetected avec une ou plusieurs réponses. Ces réponses relèvent de l'une des les deux groupes suivants en fonction de la source d'installation des applications détectées:

• Applications Google Play ou système: applications installées par Google Play ou préchargées par le fabricant de l'appareil sur la partition système de l'appareil (identifiée par FLAG_SYSTEM). Les réponses de ces applications sont précédées du préfixe KNOWN_.

• Autres applications : Applications qui ne sont pas installées par Google Play. Cela exclut les applications préchargées sur la partition du système par le fabricant de l'appareil. Réponses pour ces applications sont précédés du préfixe UNKNOWN_.

Les réponses suivantes peuvent être renvoyées:

KNOWN_INSTALLED, UNKNOWN_INSTALLED

Certaines applications installées correspondent à la source d'installation correspondante.

KNOWN_CAPTURING, UNKNOWN_CAPTURING

Certaines applications en cours d'exécution dont les autorisations sont activées peuvent être utilisées pour afficher l'écran pendant l'exécution de votre application. Cela exclut les éléments validés services d'accessibilité connus de Google Play et exécutés sur l'appareil.

KNOWN_CONTROLLING, UNKNOWN_CONTROLLING

Certaines applications en cours d'exécution dont les autorisations sont activées peuvent être utilisées pour contrôler l'appareil et les entrées dans votre application, permettant de capturer les entrées et les sorties de votre application. Cela exclut les éléments validés services d'accessibilité connus de Google Play et exécutés sur l'appareil.

KNOWN_OVERLAYS, UNKNOWN_OVERLAYS

Certaines applications en cours d'exécution dont les autorisations sont activées peuvent être utilisées pour des superpositions sur votre application. Cela exclut toute accessibilité vérifiée de services connus de Google Play et exécutés sur l'appareil.

VIDE (valeur vide)

Le risque d'accès à l'application n'est pas évalué si une condition requise n'a pas été respectée. Dans dans ce cas, le champ appAccessRiskVerdict est vide. Cela peut se produire pour pour plusieurs raisons. Par exemple:

• L'appareil n'est pas suffisamment fiable.
• Le facteur de forme de l'appareil n'est pas un téléphone, une tablette ni un appareil pliable.
• L'appareil n'est pas équipé d'Android 6 (niveau d'API 23) ou version ultérieure.
• La version de votre application installée sur l'appareil est inconnue de Google Play.
• La version du Google Play Store installée sur l'appareil est obsolète.
• Jeux uniquement : Le compte utilisateur ne dispose pas d'une licence Play pour le jeu.
• Une requête standard a été utilisée avec le paramètre verdictOptOut.
• Une requête standard a été utilisée avec une version de la bibliothèque de l'API Play Integrity qui ne prend pas encore en charge le risque d'accès à l'application pour les requêtes standards.

Le risque d'accès à l'application exclut automatiquement les services d'accessibilité vérifiés qui ont fait l'objet d'un examen amélioré de l'accessibilité de Google Play (installé par n'importe quelle plate-forme de téléchargement d'applications de l'appareil). "Exclu" signifie que l'accessibilité vérifiée services exécutés sur l'appareil ne renvoient pas de résultat superposition dans l'évaluation du risque d'accès à l'appli. Pour demander un accès amélioré à Lire l'examen de l'accessibilité de votre application d'accessibilité, la publier sur Google Assurez-vous que l'indicateur isAccessibilityTool de votre application est défini sur "true" dans le fichier manifeste de votre application ou demander un examen.

Le tableau suivant donne quelques exemples de verdicts et leur signification (ce ne répertorie pas tous les résultats possibles):

En fonction du niveau de risque, vous pouvez décider des combinaisons d'évaluations acceptables et des évaluations pour lesquelles vous souhaitez prendre des mesures. La L'extrait de code suivant montre comment vérifier qu'il n'y a pas Applications en cours d'exécution susceptibles de capturer l'écran ou de contrôler votre application:

val environmentDetails =
    JSONObject(payload).getJSONObject("environmentDetails")
val appAccessRiskVerdict =
    environmentDetails.getJSONObject("appAccessRiskVerdict")

if (appAccessRiskVerdict.has("appsDetected")) {
    val appsDetected = appAccessRiskVerdict.getJSONArray("appsDetected").toString()
    if (!appsDetected.contains("CAPTURING") && !appsDetected.contains("CONTROLLING")) {
        // Looks good!
    }
}

JSONObject environmentDetails =
    new JSONObject(payload).getJSONObject("environmentDetails");
JSONObject appAccessRiskVerdict =
    environmentDetails.getJSONObject("appAccessRiskVerdict");

if (appAccessRiskVerdict.has("appsDetected")) {
    String appsDetected = appAccessRiskVerdict.getJSONArray("appsDetected").toString()
    if (!appsDetected.contains("CAPTURING") && !appsDetected.contains("CONTROLLING")) {
        // Looks good!
    }
}

Corriger les évaluations du risque d'accès à l'appli

Selon votre niveau de risque, vous pouvez décider de l'évaluation du risque d'accès à l'appli qui vous avant de laisser l'utilisateur effectuer une demande ou une action. Des invites Google Play facultatives peuvent être présentées à l'utilisateur après en vérifiant le verdict du risque d'accès à l'application. Vous pouvez montrer CLOSE_UNKNOWN_ACCESS_RISK pour demander à l'utilisateur de fermer les applications inconnues à l'origine du problème verdict du risque d'accès à l'application ou afficher CLOSE_ALL_ACCESS_RISK pour demander à de fermer toutes les applications (connues et inconnues) à l'origine de l'évaluation du risque d'accès à l'application.

Évaluation Play Protect

Une fois activé, le champ environmentDetails de l'API Play Integrity "charge utile" contiendra l'évaluation Play Protect:

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

playProtectVerdict peut avoir une des valeurs suivantes :

NO_ISSUES

Play Protect est activé et n'a détecté aucun problème d'application sur l'appareil.

NO_DATA

Play Protect est activé, mais aucune analyse n'a encore été effectuée. L'appareil ou l'application Play Store ont peut-être été réinitialisés récemment.

POSSIBLE_RISK

Play Protect est désactivé.

MEDIUM_RISK

Play Protect est activé et a détecté des applications potentiellement dangereuses installées sur l'appareil.

HIGH_RISK

Play Protect est activé et a détecté des applications dangereuses installées sur l'appareil.

UNEVALUATED

L'évaluation Play Protect n'a pas été menée.

Plusieurs raisons peuvent expliquer cette situation. Par exemple :

• L'appareil n'est pas suffisamment fiable.
• Jeux uniquement : Le compte utilisateur ne dispose pas d'une licence Play pour le jeu.

Conseils sur l'utilisation de l'évaluation Play Protect

Le serveur backend de votre application peut décider de la marche à suivre en fonction de l'évaluation basée sur votre tolérance au risque. Voici quelques suggestions et actions utilisateur possibles :

NO_ISSUES

Play Protect est activé et n'a détecté aucun problème. Aucune action n'est donc requise de la part de l'utilisateur.

POSSIBLE_RISK et NO_DATA

Lorsque vous recevez ces évaluations, demandez à l'utilisateur de vérifier que Play Protect est activé et qu'une analyse a été effectuée. NO_DATA ne doit apparaître que dans de rares cas.

MEDIUM_RISK et HIGH_RISK

En fonction de votre tolérance au risque, vous pouvez demander à l'utilisateur de lancer Play Protect et de prendre des mesures concernant les avertissements Play Protect. Si l'utilisateur ne parvient pas à remplir ces exigences, vous pourriez les empêcher de l'action du serveur.