Provide credentials for Application Default Credentials

Stay organized with collections Save and categorize content based on your preferences.

This page describes how to provide credentials to Application Default Credentials (ADC) for use by Cloud Client Libraries and Google API Client Libraries in a variety of environments.

ADC is a strategy used by Cloud Client Libraries and Google API Client Libraries to automatically find credentials based on the application environment, and use those credentials to authenticate to Google Cloud APIs. When you set up ADC and use a client library, your code can run in either a development or production environment without changing how your application authenticates to Google Cloud services and APIs.

For more information about where ADC looks for credentials and in what order, see How Application Default Credentials works.

If you are using API keys, then you don't need to provide credentials by using ADC. For help with finding out whether an API accepts API keys, see Using API keys.

How to provide credentials to ADC

How you provide credentials to ADC depends on where your code is running:

Local development environment

User credentials

When your code is running in a local development environment, such as a development workstation, the best option is to use credentials associated with your Google Account, also called user credentials.

To provide your user credentials to ADC, you use the Google Cloud CLI:

  1. Install and initialize the gcloud CLI, if you haven't already.

  2. Create your credential file:

    gcloud auth application-default login

    A login screen is displayed. After you log in, your credentials are stored in the local credential file used by ADC.

Using the gcloud CLI to provide credentials to ADC has the following limitations:

  • User credentials do not work for some methods and APIs, such as the Cloud Translation API or the Cloud Vision API. If you see an error message about the API not being enabled in the project, or that there is no quota project available, see Troubleshooting your ADC setup.

  • This method stores your credentials in a file on your file system. Any user with access to your file system can use those credentials. When you no longer need these credentials, you should revoke them:

    gcloud auth application-default revoke
  • If your Google Account does not have the required Identity and Access Management (IAM) roles in your project, your code might not be able to access some resources. If this happens, ask your security administrator to grant you the required roles.

Types of gcloud credentials

The gcloud auth application-default login command provides a way to store credentials for your Google Account in the well-known location for use by ADC, but those credentials are used only by the client libraries and ADC. When you run commands in the gcloud CLI, you are using the credentials you provided when you logged into the gcloud CLI using the gcloud auth login command.

Usually, you will use the same account to log in to the gcloud CLI and to provide user credentials to ADC, but you can use different accounts if needed.

For information about logging in to the gcloud CLI, see Initializing the gcloud CLI.

Service account keys

If you cannot use user credentials for local development, you can use a service account key. Service account keys create unnecessary risk and should be avoided whenever possible.

If your organization policy has a constraint that prevents creating a service account key, then this method is unavailable to you.

To create a service account key and make it available to ADC:

  1. Create a service account with the roles your application needs, and a key for that service account, by following the instructions in Creating a service account key.

  2. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the location of the key.

Google Cloud cloud-based development environment

When you use a Google Cloud cloud-based development environment such as Cloud Shell or Cloud Code, the tool uses the credentials you provided when you logged in, and manages any authorizations required.

Containerized development environment

If you are doing local development in a containerized environment, you must make your personal credential file available to the container. The GCP Auth minikube addon is one way to do this.

Google Cloud services that support attaching a service account

Some Google Cloud services, such as Compute Engine, App Engine, and Cloud Functions, support attaching a user-managed service account to some types of resources. Generally, attaching a service account is supported when that service's resources can run or include application code. When you attach a service account to a resource, the code running on the resource can use that service account as its identity.

Attaching a user-managed service account is the preferred way to provide credentials to ADC for production code running on Google Cloud.

For help with creating a service account, see Creating and managing service accounts. For help determining the roles that you need to provide to your service account, see Choose predefined roles.

For information about which resources you can attach a service account to, and help with attaching the service account to the resource, see the IAM documentation on attaching a service account.

If your organization policy has a constraint that restricts the creation of service accounts, then you cannot use this method to set up credentials for ADC.

Google Cloud containerized environment

If you plan to containerize your application using Google Kubernetes Engine or Anthos, you can use ADC for local development with the gcloud CLI, or use a local container.

When you are ready to move to your Google Cloud containerized environment, you need to understand how your environment supports authentication and service accounts.

On-premises or another cloud provider

If you are running your application outside of Google Cloud, you need to provide credentials that are recognized by Google Cloud to use Google Cloud services.

Workload identity federation

The preferred way to authenticate with Google Cloud using credentials from a different identity provider is to use workload identity federation; you create a credential configuration file and set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to it. This approach is more secure than creating a service account key.

For help with setting up workload identity federation for ADC, see Configuring workload identity federation and Obtaining short-lived credentials with identity federation.

Service account key

If you are not able to configure workload identity federation, then you must create a service account, grant it the IAM roles that your application requires, and create a key for the service account.

If your organization policy has a constraint that prevents creating a service account key, then this method is unavailable to you.

To create a service account key and make it available to ADC:

  1. Create a service account with the roles your application needs, and a key for that service account, by following the instructions in Creating a service account key.

  2. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the location of the key.

Troubleshooting your ADC setup

Some common problems you might encounter when using ADC include the following situations:

User credentials not working

If your API request returns an error message about end user credentials not being supported by this API, the API not being enabled in the project, or no quota project being set, review the following information.

There are two kinds of Google Cloud APIs:

  • Resource-based APIs, which use the project associated with the resources being accessed for billing and quota,

  • Client-based APIs, which use the project associated with the account accessing the resources for billing and quota.

When you use Google Account credentials with a client-based API, the default project associated with the account can't be used for billing purposes.

To resolve this issue, you must update ADC to use a different project as the billing project:

gcloud auth application-default set-quota-project YOUR_PROJECT

You must have the serviceusage.services.use IAM permission for a project to be able to designate it as your billing project. The serviceusage.services.use permission is included in the Service Usage Consumer IAM role. If you don't have the serviceusage.services.use permission for any project, contact your security administrator or a project owner who can give you the Service Usage Consumer role in the project.

The billing project is not included in the token returned from ADC for REST requests. If you are using ADC with a REST request, see Setting the quota project with a REST request.

Incorrect credentials

If your credentials don't seem to be providing the access you expect, or aren't found, inspect the credentials available to ADC, in the order that ADC looks for credentials, to see what might be going wrong. Here are a few things to check:

  • Make sure that the GOOGLE_APPLICATION_CREDENTIALS environment variable is set only if you are using a service account key or other JSON file for ADC. The credentials pointed to by the environment variable take precedence over other credentials, including for Workload Identity.

  • Confirm that the principal making the request has the required IAM roles. If you are using user credentials, then the roles must be granted to the email address associated with the Google Account. If you are using a service account, then that service account must have the required roles.

  • If you provide an API key with the API request, the API key takes precedence over ADC in any location. If you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable and you are using an API key, the API might return a warning telling you that the credentials you provided to ADC are being ignored. To stop the warning, unset the GOOGLE_APPLICATION_CREDENTIALS environment variable.

Unrecognized credential type

If your API request returns an error that includes "Error creating credential from JSON. Unrecognized credential type", make sure you are using a valid credential. Client ID files are not supported to provide credentials for ADC.

What's next