Few steps to new level security — Play Integrity API for Android apps.

Fullset setup and testing of Google Integrity API

Hi there! Today I am going to tell you about my experience with Play Integrity API and about the reasons to use this API. If you read this article, I suppose you were disappointed in ProGuard or R8, and now you are searching for new solutions to protect your app from reverse engineering, unauthorized access, cheating or different attacks. It was a good idea for Google to create this API because somebody can change your DEX file, relatively easy steal your content and share these hacked apps. In my case, there were several thousand unauthorized users, who used the content worth several hundred dollars every day for free. And it was a sad story😔

Sections:

0- Overview Play Integrity API

1- Setup Play Integrity API and Service Account

2- Setup Play Integrity API on the Android app

3- Test your setup by Postman

4- Setup Google play integrity on the server side (PHP example)

5- Create an App integrity test response

6- Do you need more than 10k requests per day?

7- Conclusion

Overview Play Integrity API

https://developer.android.com/google/play/integrity/overview

The Play Integrity API helps to protect your apps and games from different attacks such as cheating and unauthorized access.

There is min API level 19 (Android 4.4) to use this Integrity API.

The main advantage is that all verification methods processing outside the Android app.

Figure 1. Sequence diagram that shows the high-level design of the Play Integrity API.

When the user performs a high-value action in your app that you want to protect with an integrity check, complete the following steps:

1. App gets unique value from server and generates the nonce value.
2. In requestIntegrityToken(nonce) to Play Integrity API, the App passes nonce value.
3. App receives signed and encrypted verdict from the Play Integrity API — integrity token.
4. The app passes the integrity token to your app’s backend.
5. Your app’s backend sends an integrity token to a Google Play server. The Google Play server decrypts and verifies the verdict, returning the results to your app’s backend.
6. Based on the signals contained in the token payload, your app’s backend decides how to proceed.
7. Your app’s backend sends the decision outcomes to your app.

Setup Play Integrity API and Service Account

https://developer.android.com/google/play/integrity/setup

First of all, you need to turn on the Play Integrity API in Play Console:

Select your app ->Setup->App integrity

If you haven't added the Google Cloud project, you must link it.

Select existed item or create a new one.

After that, in the Google Cloud console enabling of Google Play Integrity API is needed. The easiest way is to search it.👍

In the Google Cloud console find Google Play Integrity API and enable it.

Great, now you have enabled Google Play Integrity API, but, as you know, for Google API requests Google Service Account authorization is required. At this step new service account must be created.

In the Google Cloud console search for the Service Accounts section and create Service Account.

A very important step is to select 2 roles: Service Account User and Service Usage Consumer.

Add 2 roles: Service Account User and Service Usage Consumer.

Okay, Service Account has existed, but for authorization, you need to get the JSON key — save it in order to use it later.

Setup Play Integrity API on the Android app

https://developer.android.com/google/play/integrity/setup

https://developer.android.com/google/play/integrity/verdict#request

This step described integration in Android App.

Add this implementation to your app project.

Send request for the integrity token by providing a nonce

A nonce value is a base64 string with a minimal size. It is recommended to be generated based on a unique value from the app’s server, but if the server side is not ready, you can use the method, as following:

Attention! It is for testing only, okay?

Let’s get an integrity token.

integrityTokenResponse will return token() — integrity token that you could send for verification to your apps server.

Great, your app can get an integrity token right now. You can’t make this request very frequently because there are some limits: the default is 10k requests for each project a day. The best solution is to make this request not more than 1–2 times a day.

Your day quote may be increased after a special request to Google Support.

Test your setup by Postman and gcloud

You have finished the integration, but the app’s server isn’t ready to work with your integrity request. No problem! You can test your integration yourself.

For making a REST request you need to get an Authorization token for Service Account, you can use gcloud. Just download gcloud for your OS.

Please install gcloud using this link https://cloud.google.com/sdk/docs/install#linux

If your gcloud is installed, you should get an authorization token for your Service Account. It takes several commands. There are som examples for Windows.

Run command gcloud auth activate-service-account, put your data: service account email, JSON key path and project id.

Run command set GOOGLE_APPLICATION_CREDENTIALS= JSON key path

Run command gcloud auth application-default print-access-token. It is necessary to put scopes=https://www.googleapis.com/auth/playintegrity

This method will return an authorization token that you can use to authorize the request to Google API.

Let’s continue testing in the Postman app.

Create POST request

Header Authorization is required = Bearer {access token}

Raw body with JSON that contains integrity_token. Get it in the Android app.

Congratulations! You have received Google API response.

This JSON response contains all information that your app’s server should process.

Application integrity field

https://developer.android.com/google/play/integrity/verdict#application-integrity-field

appRecognitionVerdict can have the following values: PLAY_RECOGNIZED, UNRECOGNIZED_VERSION , UNEVALUATED ;

Device integrity field

https://developer.android.com/google/play/integrity/verdict#device-integrity-field

device_recognition_verdict can have one of the following labels: Default: MEETS_DEVICE_INTEGRITY , or blank(empty). Optional: MEETS_BASIC_INTEGRITY ,MEETS_STRONG_INTEGRITY , MEETS_VIRTUAL_INTEGRITY

Account details field

https://developer.android.com/google/play/integrity/verdict#account-details-field

appLicensingVerdict can have the following values:LICENSED , UNLICENSED , UNEVALUATED

Setup Google play integrity on the server side (PHP example)

You need to install the Google Client Library. The following guide can help you: https://developers.google.com/analytics/devguides/config/mgmt/v3/quickstart/service-php#install

Put your data into tokenRequest :

$client->setAuthConfig(path/to/your/credentials/json/file.json); — path to your Service Account JSON key.

$tokenRequest->setIntegrityToken(“TOKEN_HERE”); — integrity token from mobile app.

$result = $service->v1->decodeIntegrityToken(‘PACKGE_NAME_HERE’, $tokenRequest); — package name (application id)

The following work with the response from Google API should be customized to your needs. A common use case is to block such users.

Create App integrity test response

Go to Play Console, in the App integrity section you can find “Create new test”, where you can customize Google API response.

You can create tests to evaluate how the Play Integrity API interacts with your app. For email addresses you specify, you can decide what integrity response they should get in your app from Google Play’s servers. This allows you to test how your app reacts to all possible responses.

Do you need more than 10k requests per day?

There is one feature that allows you to get a higher daily quota only after filling in a special form. But you have to wait for an answer for a long time😔

Conclusion

The Integrity API is a very powerful instrument to save your app content from different attacks. The only disadvantage is that the number of requests per day is limited. But it can be agreed with Google support. Up to the time of publication, my app is secure and there are no problems with cheaters. You can easily use Integrity API and save money for your project.

Share your thoughts in the comments. Let’s have a discussion here.

Take care.