Use the ARCore API on Google Cloud

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

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.
4. Review documentation on API key restrictions to secure your API key.

Your app is now configured to use API keys.