server-side-app-integrity-check

Server-side app integrity check

This is a Node.js module that is to be used in your app server to validate Android's app integrity tokens (or, attestation objects) sent by your clients. It can validate tokens of Android's Play Integrity API (either classic or standard requests). It does NOT support Android's SafetyNet API, as it is deprecated.

The decryptPlayIntegrity function returns the attestation token. The verifyPlayIntegrity function returns 'success' only if high security standards are met in the device environment.

It is your responsibility to handle Google/Apple server outages (as those must inevitably always be used in the attestations), to design your platform logic to conform to the API request rate limits, and to have a plan on how to handle clients that do not meet the maximum standards (for example, rooted devices or Play Protect disabled), among other considerations.

See also: https://github.com/srinivas1729/appattest-checker-node

This work (code and documentation) is based on https://github.com/herzhenr/spic-server. See the attached license.

Setup

Set up a Google Cloud Project

• Create a new Google Cloud Project
• Navigate to APIs & Services -> Enabled APIs & Services -> Enable APIs & Services and enable the Play Integrity API there
• Within the Play Integrity API page navigate to Credentials -> Create Credentials -> Service Account. Set a name there and leave the rest on default values.
• Navigate to Keys -> Add Key -> Create New Key Go to Keys -> Add Key -> Create new key. The JSON file that downloads automatically has the contents verbatim you will later need for the environment variable.

Set up a Google Play Console Project

• Create a new Google Play Console Project.
• Within Google Play Console, link the new Google Cloud Project to it.
• To obtain the decryption and verification keys, navigate within th Google Play Console to Release -> Setup -> AppIntegrity -> Response encryption
• Click on Change and choose Manage and download my response encryption keys if you plan to verify attestations on your server instead of offloading work to Google servers.
• Follow the on-screen instructions to create a private-public key pair in order to download the encrypted keys.

Environment variables

Define the necessary environment variables in a .env file at the root of your project. Use example.env as a sample. Don't forget to rename it to .env

Using the module

Run npm install server-side-app-integrity-check from your project root.

If, for example, you have a CommonJS project, you can use the library in this way:

/* 'token' is the token the client received from the PlayIntegrity Server in the previous step
*  'mode': Set to 'server' to check integrity locally. Set to 'google' to offload the check to Google servers
*  'none_truth' is the ground truth of the nonce as stored by your app server
*/
let attestcheckerlibrary = await import('server-side-app-integrity-check');
decryptedToken = await attestcheckerlibrary.decryptPlayIntegrity(token, mode);
attestationresult = attestcheckerlibrary.verifyPlayIntegrity(decryptedToken, nonce_truth);

Possible return values for attestationresult:

{status: "fail", message: "Some explanatory message here", decryptedToken: "Here you will have the decrypted token"} := Attestation was not successful. The app integrity is compromised or some other condition has occurred. Bear in mind that attestations will likely not succeed if an Android device has been rooted or if the device does not meet maximum standards.

{status: "error", message: "Some explanatory message here", decryptedToken: "Here you will have the decrypted token"} := An unexpected error has occurred. Do not forget to also embrace the sample code above within a try-catch clause to capture any errors throwed by the module.

{status: "success", message: "Some explanatory message here", decryptedToken: "Here you will have the decrypted token"} := Nice! The client passed the attestation.