How Application Default Credentials works

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

This page describes the locations where Application Default Credentials (ADC) looks for credentials. Understanding how ADC works can help you understand which credentials ADC is using, and how it's finding them.

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 information about the best ways to provide credentials to ADC, see Provide credentials for Application Default Credentials.

Search order

ADC searches for credentials in the following locations:

  1. GOOGLE_APPLICATION_CREDENTIALS environment variable
  2. User credentials set up with the Google Cloud CLI
  3. The attached service account, as provided by the metadata server

GOOGLE_APPLICATION_CREDENTIALS environment variable

You can use the GOOGLE_APPLICATION_CREDENTIALS environment variable to provide the location of a credential JSON file. This JSON file can be one of the following types of files:

  • A credential configuration file for workload identity federation

    Workload identity federation enables you to use an external identity provider to access Google Cloud resources. For more information, see Authenticating by using client libraries, the gcloud CLI, or Terraform in the Identity and Access Management (IAM) documentation.

  • A service account key

    Service account keys create a security risk and are not recommended. Unlike the other credential file types, compromised service account keys can be used by a bad actor without any additional information. For more information, see Best practices for using and managing service account keys.

User credentials set up with the gcloud CLI

You can set up ADC to use your Google Account credentials by running the gcloud auth application-default login command. This command places a JSON file containing your credentials in a well-known location on your file system. The location depends on your operating system:

  • Linux, macOS: $HOME/.config/gcloud/application_default_credentials.json
  • Windows: %APPDATA%\gcloud\application_default_credentials.json

For more information about using the gcloud CLI and ADC, see Types of gcloud credentials.

The attached service account

Many Google Cloud services let you attach a service account that can be used to provide credentials for accessing Google Cloud APIs. If ADC does not find credentials it can use in either the GOOGLE_APPLICATION_CREDENTIALS environment variable or the well-known location for Google Account credentials, it uses the metadata server to get credentials for the service where the code is running.

If your application is running on a Google Cloud resource that supports attaching a service account, you should use the attached service account to provide credentials. To use the attached service account, follow these steps:

  1. Create a user-managed service account.
  2. Grant that service account the least privileged IAM roles possible.
  3. Attach the service account to the resource where your code is running.

This configuration is recommended for applications running in production.

For help with attaching a service account, see Attaching a service account to a resource. For help with determining the required IAM roles for your service account, see Choose predefined roles.

What's next