Authenticating to a Cloud API Service

To allow your application code to use a Cloud API, you will need to set up the proper credentials for your application to identify itself to the service, authenticate its identity, and obtain authorization to perform tasks. (These credential-related mechanisms are known as auth schemes.)

Types of authentication schemes

Auth schemes provide several checks to determine identity, authentication, and authorization:

  • An Identity check only attempts to determine who is making the request, and does not check whether the entity making the request is actually who they say they are.

  • An Authentication check attempts to determine if the caller using the auth scheme is actually who they say they are. Generally, this check is done through a shared secret. However, API keys provide some form of implicit authentication by restricting their usage to certain scenarios. (See API Key Restrictions below.)

  • An Authorization check attempts to determine what the caller can do once authenticated. Such schemes usually require the passing around of credentials.

Cloud APIs offer several different auth schemes, with identity, authentication, and authorization as summarized below:

Auth Scheme Identity Authentication Authorization
API Keys key string key restrictions x
Service Accounts service account email private key OAuth token
User Accounts user email password OAuth token
  • API Keys provide the simplest authentication scheme; however, an API key only provides identity; secure authentication is not validated through a shared secret; instead, key restrictions provide a form of implicit authentication.

  • Service Accounts provide both identity and authentication via a public/private key exchange. This exchange produces an auth token for use in accessing resources, including the API itself. Using a service account is the preferred way for backends to securely authenticate to Cloud APIs.

  • User Accounts provide identity and authentication via a challenge-response (password) mechanism to a third party (user) account. As with service accounts, this authentication produces an auth token for use in accessing resources. Typically, user account auth schemes are only used when the API needs to a access private information.

Recommendations

When accessing a Google Cloud Platform API, we recommend that you set up a service account for production usage. A service account provides identity, authentication, and authorization, allowing you to use other Cloud services with the same auth scheme, and is more secure, using short-lived OAuth tokens.

If at all possible, configure your application to use a service account. However, in some cases you may not be able to use a service account key. For example, an application may not be able to use a Google Cloud authentication library in your platform, or you need to make API requests from a client application and cannot proxy those requests through a server. In those cases, use an API key, though you should add a restriction on the key to guard against its unauthorized usage.

Setting up a Service Account

Google Cloud Platform API authentication and authorization is typically done using a service account. A service account, like a user account, is represented by an email address. Unlike a user account, however, a service account is a role account restricted to the Google Cloud Platform, and may be configured to access APIs or services for which it has access.

Service accounts obtain temporary authentication tokens using two-legged OAuth. As well, you can place authorization restrictions (for example, on Google Cloud files) using service accounts just as you would for user accounts. For more information on how service account authentication and authorization work, see the service account section of the Using OAuth 2.0 to Access Google APIs guide.

Creating a Service Account

Within the Cloud Platform Console, navigate to the API Manager→Credentials panel. (If you have recently created a new project and enabled a Cloud API, you will have arrived at this panel automatically by clicking Go to Credentials.)

Select Create credentials and select Service account key from the dropdown menu:

A Create service account key panel will appear. Within the panel, from the Service account dropdown menu, select New service account. The service account configuration panel appears:

Type a Name for this service account. This name will be used as the default name for your Service account ID (to the left of the "@" in the generated service account ID address), but you can change this service account ID name if you wish. These names can be arbitrary; it is only important that you remember them. Set the Role dropdown option to be "Project > Owner". Under Key type, we recommend that you leave this value as JSON. Click Create and the Cloud Platform Console will generate a JSON key (as a .json text file), prompt you to download the file to your computer, and display a New private key dialog box.

The generated JSON key will will be similar to the following sample JSON key:

{
  "type": "service_account",
  "project_id": "project-id",
  "private_key_id": "some_number",
  "private_key": "-----BEGIN PRIVATE KEY-----\n....
  =\n-----END PRIVATE KEY-----\n",
  "client_email": "<api-name>api@project-id.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/...<api-name>api%40project-id.iam.gserviceaccount.com"
}

Store this JSON file securely, as it contains your private key (and this file is the only copy of that key). You will need to refer to this service account key file within your code when you wish to send credentials to the Google Cloud Platform API.

Authenticating with Application Default Credentials

The simplest way for applications to authenticate to a Google Cloud Platform API service is by using Application Default Credentials (ADC). Services using ADC first search for credentials within a GOOGLE_APPLICATION_CREDENTIALS environment variable; Google Cloud recommends you set this environment variable to point to your service account key file (the .json file downloaded when you created a service account key, as explained in Set Up a Service Account.

$ export GOOGLE_APPLICATION_CREDENTIALS=<path_to_service_account_file>

Setting up an API Key

The simplest authentication mechanism involves passing an API key directly to the service. Because this scheme is limited in both scope and security, we advise using unrestricted API keys only for testing purposes. However, for certain applications (e.g. embedded devices, Android, or iOS apps), API keys may be necessary, in which case, you should add appropriate restrictions to limit their usage.

Creating an API Key

Within the Cloud Platform Console, navigate to the API Manager→Credentials panel. (If you have recently created a new project and enabled a Cloud API, you will have arrived at this panel automatically by clicking Go to Credentials.)

Select Create credentials and select API key from the dropdown menu.

The Create a new key dialog appears.

Enter a name for this key ("Curl Test Key" is shown above, but you can choose any name you wish). You can leave the Restriction fields blank since this key will only used for testing purposes, but if you plan to deploy a key in production, you should set a restriction field.

Click Create. The API key created dialog box lists your newly created key.

You may wish to copy your key and keep it secure. (If you need to retrieve it at a later time, you can do so from the API Manager→Credentials page). Unless you are using a testing key that you intend to delete at a later time, we recommend you add an API Key Restriction as shown in the next section.

API key restrictions

Your API key is unrestricted by default, which is insecure if anyone can either read this key (if placed within a browser, for example) or access the device on which the key is placed. We recommend you place a restriction on this API key to inhibit unauthorized usage.

To add a restriction, click on Restrict key within the API key created dialog box. The API key configuration panel will appear:

The type of restriction you select will depend on your application needs:

  • Web applications interacting directly with the API (that is, not through any backend or middleware) should add an HTTP referrers restriction. Note, however, that such applications will expose their API key publicly; prefer using a service account auth scheme instead.
  • Backend applications that cannot otherwise support service accounts (for example, embedded devices that do not have a supported language in the client library) should add an IP addresses restriction to guard against usage from clients at different IP addresses.
  • Android applications should add an Android apps restriction and add your package name and SHA-1 signing-certificate fingerprint.
  • iOS applications should add an iOS apps restriction and add any iOS bundle identifiers to restrict API calls to these iOS bundles.

For testing, you might not want to place any restriction at all. However, it is recommended that you either add a restriction to this key or delete it once you deploy your application to production.

Send feedback about...

Google Cloud Natural Language API Documentation