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.
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 how to provide credentials to ADC, see Set up Application Default Credentials.
ADC searches for credentials in the following locations:
- User credentials set up by using the Google Cloud CLI
- The attached service account, returned by the metadata server
The order of the locations ADC checks for credentials is not related to the relative merit of each location. For help with understanding the best ways to provide credentials to ADC, see Set up Application Default Credentials.
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 provided by using the gcloud CLI
You can provide user credentials to ADC by running the
gcloud auth application-default login command. This
command places a JSON file containing the credentials you provide (usually from
your own Google Account) in a well-known location on your file system. The
location depends on your operating system:
- Linux, macOS:
The credentials you provide to ADC by using the gcloud CLI are distinct from your gcloud credentials—the credentials the gcloud CLI uses to authenticate to Google Cloud. For more information about these two sets of credentials, see ADC credentials and 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
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.
Using the credentials from the attached service account is the preferred method for finding credentials in a production environment on Google Cloud. To use the attached service account, follow these steps:
- Create a user-managed service account.
- Grant that service account the least privileged IAM roles possible.
- Attach the service account to the resource where your code is running.
For help with creating a service account, see Creating and managing service accounts. 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.
- Learn the best ways to provide credentials to ADC.
- Authenticate using the Cloud Client Libraries.
- Explore authentication at Google.
- Learn about client libraries at Google.
- Review the Application Default Credentials AIP.