Authorize Access to an Android App through Attestation Server

• Sign in to Mekarge A3 Console

1Create API Resource

1. Navigate to Authorization → Resources → Create
2. Click Create under the API tile
3. Name the new Resource (i.e. My API) and its Resource URI (i.e. api:myapi)
4. Select a lifetime for Access Tokens issued for this Resource (i.e. 3600)
5. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if Resource URI is taken before

2Add Scopes

1. Navigate to Authorization → Resources
2. Click ⋮ at the end of the newly created row and select View Details
3. Navigate to Scopes tab
4. Name a Scope (i.e. action:call) for Scope Name and click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if same Scope Name is used before

3Create Role

1. Navigate to Authorization → Roles → Create
2. Name the new Role (i.e. basic)
3. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if Role Name is taken before

4Create Appraisal

1. Navigate to Device Attestation → Appraisals → Create
2. Set play-integrity⚠ for Appraisal Name
💡 Hints
Fixed values are coming from the constants defined in Attestation Server
3. Select Affirming⚠ as Appraisal Status Level
💡 Hints
Fixed values are coming from the constants defined in Attestation Server
4. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
5. Navigate to Device Attestation → Appraisals
6. Click ⋮ at the end of the newly created row and select View Details
7. Navigate to Trustworthiness Vector tab
8. Set request-package-name⚠ for Trustworthiness Claim Name
💡 Hints
Fixed values are coming from the constants defined in Attestation Server
9. Select Affirming⚠ as Trustworthiness Acceptance Level and click Put Claim
💡 Hints
Fixed values are coming from the constants defined in Attestation Server
10. Set timestamp-millis⚠ for Trustworthiness Claim Name
💡 Hints
Fixed values are coming from the constants defined in Attestation Server
11. Select Affirming⚠ as Trustworthiness Acceptance Level and click Put Claim
💡 Hints
Fixed values are coming from the constants defined in Attestation Server
12. Click Commit at the end of the page

5Create Attestation Profile

1. Navigate to Device Attestation → Attestation Profiles → Create
2. Name the new Attestation Profile (i.e. android) and click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if Attestation Profile Name is taken before
3. Navigate to Device Attestation → Attestation Profiles
4. Click ⋮ at the end of the newly created row and select View Details
5. Navigate to Appraisals tab
6. Select the Appraisal play-integrity created in the previous steps and click Add

6Create Data Source

1. Navigate to Authentication → Data Sources → Create
2. Click Create under the Hosted Database Data Source
3. Name the new Data Source (i.e. My DB) and its alias (i.e. db)
4. Select a lifetime for ID Tokens for the Users defined in this Data Source (i.e. 86400)
5. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if Data Source Alias is taken before

7Create User Group

1. Navigate to Authentication → User Groups → Create
2. Name the new User Group (i.e. users)
3. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if User Group Name is taken before
4. Navigate to Authentication → User Groups
5. Click ⋮ at the end of the newly created row and select View Details
6. Navigate to Roles tab
7. Select the Role basic created in the previous steps and click Add

8Create User

1. Navigate to Authentication → Users → Create
2. Select the User Group (i.e. users) created in the previous steps
3. Select E-Mail as User Login Type
4. Set an E-Mail address (i.e. johndoe@test.com) as User Login Identifier
5. Set a Password (i.e. secret) as User Password
6. Set Default Locale to en
7. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if a User with the same User Login Identifier is defined before

9Add User Information

1. Navigate to Authentication → Users
2. Click Scan
3. Click the icon at the end of the newly created row
4. Navigate to Claim Set tab
5. Set en for Claim Set Locale and click Create
ⓘ Possible Issues
• Creation will be rejected if Locale is used before
6. Click the edit icon at the end of the newly created row that will appear at the Defined Claim Sets section
7. Navigate to Custom Claims tab on the second section
8. Set name⚠ for Claim Name
9. Set Claim Value (i.e. John Doe) and click Put Claim
10. Click Commit at the end of the page

10Create UI Collection

1. Navigate to User Interface → UI Collections → Create
2. Name the new Collection (i.e. default)
3. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if Collection Name is taken before

11Create Login Page

1. Navigate to User Interface → Web Components → Create
2. Click Create under the Login Page Component
3. Select the UI Collection (i.e. default) created in the previous steps
4. Set en for Locale and click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
• Creation will be rejected if there is already a Login Page defined with en Locale defined before
5. Navigate to User Interface → Web Components
6. Click ⋮ at the end of the newly created row and select View Details
7. Click Heading Variables tab on the second section
8. Change Heading (i.e. My Native App) and click Publish at the end of the page

12Create Client

1. Navigate to Authorization → Clients → Create
2. Click Create under the Native Application Application Type
3. Name the new Client (i.e. My Native App)
4. Select Post (Http Body) as Client Authentication Type
5. Click Create
ⓘ Possible Issues
• Creation will be rejected if you exceed your quota
6. Navigate to Authorization → Clients
7. Click ⋮ at the end of the newly created row and select View Details
8. Navigate to Features tab
9. Activate Enable Device Attestation and click Update
💡 Hints
Activate Enable Device Attestation to increase security for native applications.
10. Activate Enable PKCE and click Update
💡 Hints
Activate Enable PKCE to improve the security of Authorization Code flows involving User Agents. Read more about PKCE in RFC 7636
11. Activate Enable OpenID and click Update
💡 Hints
Activate Enable OpenID to allow ID Token issuance.
12. Navigate to Redirections tab
13. Set https://10.0.2.2:8000/callback ⚠ for Redirection URL and click Add
💡 Hints
10.0.2.2 is a special Android emulator hostname that maps to the host machine's localhost.
14. Navigate to Permissions tab
15. Select the Resource (i.e. My API) → Select the Scope (i.e. action:call) → Click Grant
16. Click the edit icon at the end of the newly created row that will appear at the Permission List section
17. Navigate to Add Roles tab on the second section
18. Select the Role (i.e. basic) created in the previous steps and click Add
19. Navigate to Add Attestation Profiles tab on the second section
20. Select the Attestation Profile (i.e. android) created in the previous steps and click Add
21. Click Back To Client
22. Navigate to Data Sources tab
23. Select the Data Source (i.e. My DB) created in the previous steps and click Select
24. Navigate to UI Collections tab
25. Select the UI Collection (i.e. default) created in the previous steps and click Select

13Create a New Project

1. Open https://console.cloud.google.com/
2. Sign in with your Google account
3. Click New Project
4. Name the new Project (i.e. My Native App) and click Create
5. Open API Library
6. Search for Play Integrity API and click Enable

14Create Service Account

1. Open Service Accounts
2. Click Create Service Account
3. Give an ID to Service Account (i.e. my-native-app) and click Create and Continue
4. Add the role Play Integrity API User and click Continue
5. Click Done
6. Click on your newly created service account's E-Mail
7. Navigate to Keys tab
8. Click Add Key → Create new key
9. Choose JSON and click Create
10. The service account key will be downloaded automatically
💡 Hints
This file contains sensitive credentials. Store accordingly.

15Get Project Number

1. Navigate to Dashboard
2. Copy down the Project Number from Project info section

16Clone Repository

1. Run the following command to checkout the Reference Implementation for the Attestation Server

git clone https://github.com/mekargeoss/a3-ri-attestation-python.git

17Install Dependencies for Attestation Server

1. Run the following commands to install dependencies

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

18Populate the .env File

1. Navigate to Environments
2. Click ⋮ at the end of the current Environment and select View Details
3. Copy the Issuer Path from Environment Info section to set ISSUER_PATH
4. Navigate to Authorization → Clients
5. Click ⋮ at the end of the previously created row and select View Details
6. Copy the Client Id from Client Credentials section to set CLIENT_ID
7. Copy the Client Secret from Client Credentials section to set CLIENT_SECRET
8. Copy the HMAC Key from Verifier HMAC Key section to set VERIFIER_SECRET
9. Navigate to Redirections tab
10. Copy the redirection entry from Redirection URLs section to set REDIRECT_URI
Checks
Redirection URL was set as https://10.0.2.2:8000/callback in previous steps
11. Navigate to Authorization → Resources
12. Click ⋮ at the end of the previously created row and select View Details
13. Copy the Resource Uri from Resource Information section to set RESOURCE_URI
14. Navigate to Device Attestation → Attestation Profiles
15. Click ⋮ at the end of the previously created row and select View Details
16. Copy the Attestation Profile Name from Attestation Profile Information section to set ATTESTATION_PROFILE_ANDROID
17. Use the absoulte path of Service Account File to set GOOGLE_SERVICE_ACCOUNT_FILE
18. Use https://10.0.2.2:8000 to set BASE_URL
19. Use app://finish to set DEEPLINK_URL
20. Use oss.mekarge.a3.nat.android to set ANDROID_PACKAGE_NAME
21. Fill in the .env file with the information collected above

ISSUER_PATH=
CLIENT_ID=
CLIENT_SECRET=
VERIFIER_SECRET=
REDIRECT_URI=
RESOURCE_URI=
ATTESTATION_PROFILE_ANDROID=

BASE_URL=https://10.0.2.2:8000
DEEPLINK_URL=app://finish

ANDROID_PACKAGE_NAME=oss.mekarge.a3.nat.android
GOOGLE_SERVICE_ACCOUNT_FILE=

19Create a Self Signed Certificate

1. Create a private key and certificate for the Attestation Server (You can skip this step if you already have key and certificate).

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 \
  -nodes -keyout server.key -out server.crt \
  -subj "/C=TR/ST=Example/L=ExampleCity/O=Example/OU=Dev/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1,IP:10.0.2.2"

20Clone Repository

1. Run the following command to checkout the Reference Implementation for the Android App

git clone https://github.com/mekargeoss/a3-ri-native-android.git

21Open Project

1. Start Android Studio and open the project
2. Start Gradle sync

22Edit Config File

1. Open the Config.kt file under the oss.mekarge.a3.nat.android package
2. Update the CLOUD_PROJECT_NUMBER constant with the number obtained in step 15

const val CLOUD_PROJECT_NUMBER: Long =

23Add Custom Certificate

1. Create raw directory under res directory.
2. Save the generated certificate at step 19 (was server.crt) as ./res/raw/trusted_ca.crt.
💡 Hints
If you are using an existing certificate:
• If it is a custom self signed certificate save as ./res/raw/trusted_ca.crt likewise
• If the certificate has a trust anchor installed on the system, you can skip this step and remove the trust-anchors node from ./res/xml/network_security_config.xml file

24Start Server

1. Run the following command to start the server

uvicorn app.main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --ssl-keyfile server.key \
  --ssl-certfile server.crt

25 Start App

1. Click Run 'app'
2. On the emulator screen click Login to start Authorization Flow
💡 Hints
You might see certificate warning if you use the generated the certificate at step 19. You can skip warning and continue to the site.
3. Use the E-Mail address and Password used while creating the User to log in