Authenticate your requests

Cloud Client Libraries for Java uses the Google Auth Library for Java to authenticate requests. This library supports multiple authentication types. For more details, see the project's README.md and javadoc.

Authentication in a Google Cloud environment

When using Google Cloud libraries from a Google Cloud environment (such as Compute Engine, Google Kubernetes Engine, or App Engine) you don't need to perform additional authentication steps.

An example call without additional authentication:

Storage storage = StorageOptions.getDefaultInstance().getService();

Authentication in non-Google Cloud environments

To authenticate in a non-Google Cloud environment, there are three common options:

1. (Recommended) Use a service account.
2. Use the Google Cloud SDK with a local test environment.
3. Use an existing OAuth2 access token.

Use a service account

1. Generate a JSON service account key.

2. After downloading the key, you must do one of the following:

   • Define the environment variable GOOGLE_APPLICATION_CREDENTIALS to be the location of the key. For example:

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json
   

   • Supply the JSON credentials file when building the service options. For example, this Storage object has the necessary permissions to interact with your Cloud Storage data:

   Storage storage = StorageOptions.newBuilder()
       .setCredentials(ServiceAccountCredentials.fromStream(new FileInputStream("/path/to/my/key.json")))
       .build()
       .getService();
   

Use the Google Cloud SDK with a local test environment

If you are using a local environment for development or testing, you can use the Google Cloud SDK.

Create Application Default Credentials with gcloud auth application-default login. Cloud Client Libraries for Java will automatically detect these credentials.

Use an existing OAuth2 access token

If you have an OAuth2 access token, you can use it to authenticate. If you do, the access token isn't automatically refreshed:

Credentials credentials = GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
Storage storage = StorageOptions.newBuilder()
    .setCredentials(credentials)
    .build()
    .getService();

Another example:

Credentials credentials = GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
CloudTasksSettings cloudTasksSettings = CloudTasksSettings.newBuilder()
    .setCredentialProvider(FixedCredentialsProvider.create(credentials))
    .build();
CloudTasksClient cloudTasksClient = CloudTasksClient.create(cloudTasksSettings);

Application Default Credentials

If you don't provide credentials, Cloud Client Libraries for Java will attempt to detect them from the environment using GoogleCredentials.getApplicationDefault(). This method searches for Application Default Credentials in the following locations, in order:

1. The credentials file pointed to by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
2. Credentials provided by the Google Cloud SDK gcloud auth application-default login command.
3. Google App Engine's built-in credentials.
4. Google Cloud Shell's built-in credentials.
5. Google Compute Engine's built-in service account credentials.

Authentication with an API key

Some Google Cloud APIs support authenticating with API keys.

To use an API key with Cloud Client Libraries for Java, you must manually set the x-goog-api-key header for the relevant service client.

For example, to set the API key with the Language service:

public LanguageServiceClient createGrpcClientWithApiKey(String apiKey) throws Exception {
    // Manually set the API key using the header
    Map<String, String> header = new HashMap<String, String>() { {put("x-goog-api-key", apiKey);}};
    FixedHeaderProvider headerProvider = FixedHeaderProvider.create(header);

    // Create the client
    TransportChannelProvider transportChannelProvider = InstantiatingGrpcChannelProvider.newBuilder().setHeaderProvider(headerProvider).build();
    LanguageServiceSettings settings = LanguageServiceSettings.newBuilder().setTransportChannelProvider(transportChannelProvider).build();
    LanguageServiceClient client = LanguageServiceClient.create(settings);
    return client;
  }

An example instantiation with the Language Client using REST:

 public LanguageServiceClient createRestClientWithApiKey(String apiKey) throws Exception {
    // Manually set the API key header
    Map<String, String> header = new HashMap<String, String>() { {put("x-goog-api-key", apiKey);}};
    FixedHeaderProvider headerProvider = FixedHeaderProvider.create(header);

    // Create the client
    TransportChannelProvider transportChannelProvider = InstantiatingHttpJsonChannelProvider.newBuilder().setHeaderProvider(headerProvider).build();
    LanguageServiceSettings settings = LanguageServiceSettings.newBuilder().setTransportChannelProvider(transportChannelProvider).build();
    LanguageServiceClient client = LanguageServiceClient.create(settings);
    return client;
  }