Support Google Play Integrity

Use the Google Play Integrity service to provide assurance that clients connecting to the Auth Server are valid instances of your app. Google Play Integrity asserts that the authenticator has attestation, the app is legitimate, and the device running the app is valid. For more information, see Overview of the Play Integrity API | Google Play | Android Developers.

When considering whether or not to use the Google Play Integrity, weigh the security requirements of your app against the processing overhead of using the Google Play Integrity service. If the Google Play Integrity service is fielding too many requests, it could throttle incoming traffic, see Overview of the Play Integrity API | Google Play | Android Developers. Older Android devices do not support Google Play Integrity, so evaluate the devices used by your customers.

Configuration of your Android app depends on where decryption and verification of the app's integrity token takes place. These operations are either done locally on the Auth Server or remotely on Google Play's server.

• If you elect to do these operations locally, you must assign values to the decryption and verification key properties.

• If you choose to do these operations remotely, you must assign a file containing your service account key to the service account key file property.

Refer to Setup | Google Play | Android Developers to get these values.

The decryption key, verification key, and service account key are sensitive credentials that either need to be encrypted or stored in an external secrets manager. If you've created a Secrets plugin, the Apps page in the Admin Console prompts you for the handles for these credentials.

Update Your Policy to Require Google Play Integrity

You can only update a draft policy. If the policy that you want to modify is active, then copy the policy and make your modifications. A policy must be active in order to be used.

1. In the Admin Console, login and, if needed, switch to the desired tenant. Navigate to Authentication > FIDO Policies.

2. On the Policies page, copy the active policy you want to modify. In the Actions column for that policy, click (copy). The Policy Details page opens, rename your new policy.

   In addition to letters and digits, only the following characters are allowed in a policy name: hyphen (-), forward slash (/), underscore (_) and space ( ).

3. Scroll down to the FIDO UAF Authenticators panel. Select both the Request Google Play Integrity Extension and Reject if missing or invalid checkboxes. The latter checkbox ensures that the Google Play Integrity token is required.

4. If your policy includes the FIDO2 protocol, scroll down to the FIDO2/WebAuthn Authenticators panel. Select both the Request Google Play Extension and Reject if missing or invalid checkboxes. The latter checkbox ensures that the Google Play Integrity token is required.

5. Save your policy.

6. To activate your policy, on the Policies page, look for the row containing your policy. Click (activate) in the Actions column.

Configure an Android App to Use Google Play Integrity

Use the Admin Console to configure your Android App.

1. Login to the Admin Console and, if needed, switch to the desired tenant. Navigate to Configuration > Apps.

2. The Apps page appears. Find your app in the list and either click its name or the (edit) icon at the end of its row.

3. The App page appears. Select the Play Integrity Configurations checkbox.

4. Enter the Google Cloud project number. You can find this in the Google Play Console dashboard after you have started the Google Play Integrity integration for your app.

5. Find and enter the SHA256 digest for your app's APK signing certificate. To retrieve the SHA256 digest, use the following command:

./keytool -exportcert -alias <alias-of-entry> \
-keystore <path-to-apk-signing-keystore> &>2 /dev/null | \
openssl sha256 -binary | openssl base64 | sed 's/=//g'

6. Choose where the integrity token is decrypted and verified, either verify the token locally or remotely.

Verify the Token Locally

If you want the Nok Nok Auth Server to decrypt and verify the integrity token locally, select Locally and find the Play Integrity Decryption Key and the Play Integrity Verification Key in the Google Play Console dashboard by following these instructions:

1. Select your app. Then choose App Integrity from the left navigation bar.

2. On the right side of the Play Integrity API pane, click Settings.

3. On the right side of the Classic requests screen, choose Download keys.

4. Follow the instructions on the Download API keys screen to generate a PEM file, upload the PEM file, download the encrypted file, and decrypt the file. This results in the decryption and verification keys.

5. Back in the Nok Nok Admin Console, enter the decryption and verification keys in one of the following 2 ways:
   
   If you are not using the Secrets plugin to store the decryption and verification keys, enter the keys directly into the Admin Console. The Server automatically encrypts them.

   If you are using the Secrets plugin to store other credentials but you choose not to store the decryption and verification keys using the Secrets plugin, make sure that Configure with key is selected before entering both the decryption and the verification key.

If you are using the Secrets plugin to store the decryption and verification keys, select Configure with handle for key in the vault and enter handles to the decryption and verification keys.

Verify the Token Remotely

If the Google Play Server will decrypt and verify the integrity token, then select Remotely.

Specify the Service Account Key in the Admin Console in one of the following 2 ways:

If you are not using the Secrets plugin to store the Service Account key, then select Upload File and click Choose File to upload the file containing the Service Account Key.

If you are using the Secrets plugin to store the Service Account Key, select Handle for service account key in the vault and enter a handle to the service account key in the external vault.