Use the ARCore API on Google Cloud

Keyless

To authorize your app using Keyless authentication, create OAuth 2.0 client IDs.

Determine signing key fingerprints

A OAuth 2.0 client ID uses your app's signing key fingerprint to identify your app.

keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore

keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Create OAuth 2.0 client IDs

For each applicable signing key from the previous steps, create an OAuth 2.0 client ID in your Google Cloud project's credentials.

• In Google Cloud, open the Credentials page.

  Credentials

• Click Create credentials, then select OAuth client ID from the menu.

• Fill in the required fields as follows:

  • Application type: choose Android.
  • Package name: use the package name as declared in your AndroidManifest.xml.
  • SHA-1 certificate fingerprint: use a fingerprint obtained in previous steps.

• Press Create.

Include required libraries

1. Include com.google.android.gms:play-services-auth:16+ in your app's dependencies.

2. If you are using code minification, add it to your app's build.gradle file:

   buildTypes {
     release {
       ...
       proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
     }
   }
   

3. Add the following to your app's proguard-rules.pro file:

   -keep class com.google.android.gms.common.** { *; }
   -keep class com.google.android.gms.location.** { *; }
   -keep class com.google.android.gms.auth.** { *; }
   -keep class com.google.android.gms.tasks.** { *; }
   

Your app is now configured to use Keyless authentication.

Keyless

ARCore supports the authorization of API calls in iOS using a (JSON Web token). The token must be signed by a Google Service account.

In order to generate tokens for iOS, you must have an endpoint on your server that satisfies the following requirements:

• Your own authorization mechanism must protect the endpoint.

• The endpoint must generate a new token every time, such that:

  • Each user gets a unique token.
  • Tokens don't immediately expire.

Create a service account and signing key

Follow these steps to create a Google service account and signing key:

1. In Google Cloud, open the Credentials page.
   Credentials
2. Click Create Credentials > Service account.
3. Under Service account details, type a name for the new account, then click Create.
4. On the Service account permissions page, go to the Select a role drop-down. Select Service Accounts > Service Account Token Creator, then click Continue.
5. On the Grant users access to this service account page, click Done.
6. On the Credentials page, find the Service Accounts section and click the name of the account you just created.
7. On the Service account details page, scroll down to the Keys section and select Add Key > Create new key.

8. Select JSON as the key type and click Create.

   This downloads a JSON file containing the private key to your machine. Store the downloaded JSON key file in a secure location.

Create tokens on your server

To create new tokens (JWTs) on your server, use the standard JWT libraries and the JSON file that you securely downloaded from your new service account.

Create tokens on your development machine

To generate JWTs on your development machine, use the following oauth2l command:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

Specifying an empty cache location using the --cache flag is necessary to ensure that a different token is produced each time. Be sure to trim the resulting string. Extra spaces or newline characters will cause the API to reject the token.

Sign the token

You must use the RS256 algorithm and the following claims to sign the JWT:

• iss — The service account email address.
• sub — The service account email address.
• iat — The Unix epoch time when the token was generated, in seconds.
• exp — iat + 3600 (1 hour). The Unix epoch time when the token expires, in seconds.
• aud — The audience. It must be set to https://arcore.googleapis.com/.

Non-standard claims are not required in the JWT payload, though you may find the uid claim useful for identifying the corresponding user.

If you use a different approach to generate your JWTs, such as using a Google API in a Google-managed environment, make sure to sign your JWTs with the claims in this section. Above all, make sure that the audience is correct.

Pass the token in the ARCore session

1. Ensure that the iOS Authentication Strategy is set to AuthenticationToken. In Unity, go to Edit > Project Settings > XR Plug-in Management > ARCore Extensions. In the iOS Authentication Strategy drop-down menu, select the Authentication Token option.

2. When you obtain a token, pass it into your ARCore session using ARAnchorManager.SetAuthToken():

   // Designate the token to authorize ARCore API calls
   // on the iOS platform. This should be called each time the application's token is refreshed.
   ARAnchorManager.SetAuthToken(authToken);
   

Your app is now configured to use Keyless authentication.

Note the following when you pass a token into the session:

• If you have used an API key to create the session, ARCore will ignore the token and log an error.

  If you no longer need the API key, delete it in the Google Developers Console and remove it from your app.

• ARCore ignores tokens that contain spaces or special characters.

• Tokens typically expire after one hour. If there is a possibility that your token may expire while in use, obtain a new token and pass it to the API.

API Key

1. In Google Cloud, open the Credentials page.
   Credentials
2. Click Create credentials, then select API key from the menu.
   The API key created dialog displays the string for your newly created key.

3. In Unity, go to Edit > Project Settings > XR Plug-in Management > ARCore Extensions. For each target platform (Android, iOS), in its Authentication Strategy drop-down menu, select the API Key option. Then, insert your API key in the API key fields.

4. Review documentation on API key restrictions to secure your API key.

Your app is now configured to use API keys.