Set up Application Default Credentials

This page describes how to set up Application Default Credentials (ADC) for use by Cloud Client Libraries, Google API Client Libraries, and the REST and RPC APIs in a variety of environments. You set up ADC by providing credentials to ADC in the environment where your code is running.

Application Default Credentials (ADC) is a strategy used by the Google authentication libraries to automatically find credentials based on the application environment. The authentication libraries make those credentials available to Cloud Client Libraries and Google API Client Libraries. When you use ADC, your code can run in either a development or production environment without changing how your application authenticates to Google Cloud services and APIs.

For 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 set up ADC. For more information, 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
• Cloud Shell or other Google Cloud cloud-based development environments
• Compute Engine or other Google Cloud services that support attaching a service account
• Google Kubernetes Engine or other Google Cloud containerized environment
• On-premises or another cloud provider

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 might not work for some methods and APIs, such as the Cloud Translation API or the Cloud Vision API, without extra parameters or configuration. 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.

ADC credentials and gcloud credentials

When you log in to the gcloud CLI, you use the gcloud auth login command to provide your user credentials, which the gcloud CLI uses for authentication and authorization to manage Google Cloud resources and services. (Alternatively, you can use the --impersonate-service-account flag or the auth/impersonate_service_account property to impersonate a service account.) These credentials are your gcloud credentials.

When you use the gcloud CLI to provide credentials to ADC, you use the gcloud auth application-default login command. This command puts your credentials into a well-known location for use by ADC in a local development environment. These are your local ADC credentials.

Your local ADC credentials are not used by the gcloud CLI, and your gcloud credentials are not used by ADC. They are two distinct sets of credentials.

The following table shows the two commands and what they do:

Command	Description
gcloud auth login	Accepts user credentials that are used to authenticate to and authorize access to Google Cloud services.
gcloud auth application-default login	Accepts user credentials that are provided to Application Default Credentials for use in a local development environment.

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.

Note: Creating a service account key is a security risk that should be avoided if possible. If you must create a service account key, make sure you keep it secure. Anyone with access to the key can gain all of the access that's granted to the associated service account. For more information, see Best practices for managing service account keys.

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 environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

Note: When you set the GOOGLE_APPLICATION_CREDENTIALS environment variable, ADC checks this location first, then checks other locations only if necessary.

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. You don't need to use the gcloud CLI to provide your user credentials.

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.

Note: Many of these Google Cloud services also provide a default service account. Using the default service account is not recommended, because by default the default service account is highly privileged, which violates the principle of least privilege.

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 provide credentials to ADC.

Google Cloud containerized environment

Authentication for containerized environments is handled differently between development and production environments.

Development for containerized environments

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 use a local container as a development environment, you must make your personal credential file available to the container. The GCP Auth minikube addon is one way to do this.

Containerized production environments

How you set up authentication for Google Cloud containerized environments depends on which environment you are using.

• For Anthos, see the authentication overview and Use fleet Workload Identity.
• For Google Kubernetes Engine, see Use Workload Identity for GKE.
• For Cloud Run for Anthos, see Using Workload Identity for Cloud Run for Anthos.

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.

Note: Creating a service account key is a security risk that should be avoided if possible. If you must create a service account key, make sure you keep it secure. Anyone with access to the key can gain all of the access that's granted to the associated service account. For more information, see Best practices for managing service account keys.

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 environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

Note: When you set the GOOGLE_APPLICATION_CREDENTIALS environment variable, ADC checks this location first, then checks other locations only if necessary.

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, do one of the following:

1. Update ADC to use a different project as the billing project:

   gcloud auth application-default set-quota-project YOUR_PROJECT
   

2. If you are calling the REST or RPC API directly, use the x-goog-user-project HTTP header to specify a billing project in each request. For details, see Set the quota project with a REST request.

Note: The API you are trying to use must be enabled in whatever project you specify.

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.

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:

• If you are using the gcloud CLI to access Google Cloud, you are not using the credentials you provided to ADC. Instead, you are using the credentials you provided to the gcloud CLI by using the gcloud auth login command. For more information about these two sets of credentials, see ADC credentials and gcloud credentials.

• 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

• Learn more about how ADC finds credentials.
• Authenticate using the Cloud Client Libraries.
• Explore authentication at Google.