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

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

For information about how to provide credentials to ADC, including how togenerate a local ADC file, seeSet up Application Default Credentials.

Search order

ADC searches for credentials in the following locations:

1. GOOGLE_APPLICATION_CREDENTIALS environment variable
2. A credential file created by using thegcloud auth application-default login command
3. The attached service account, returned by the metadata server

The order of the locations ADC checks for credentials is not related tothe relative merit of each location. For help withunderstanding the best ways to provide credentials to ADC, seeSet up Application Default Credentials.

GOOGLE_APPLICATION_CREDENTIALS environment variable

You can use theGOOGLE_APPLICATION_CREDENTIALS environment variable to providethe location of a credential JSON file. This JSON file can be one of thefollowing types of files:

• A credential configuration file for Workforce Identity Federation

  Workforce Identity Federation lets you use an external identity provider(IdP) to authenticate and authorize users to access Google Cloudresources. For more information, seeWorkforce Identity Federation in theIdentity and Access Management (IAM) documentation.

• A credential configuration file for Workload Identity Federation

  Workload Identity Federation lets you use an externalIdP to authenticate and authorize workloads to accessGoogle Cloud resources. For more information, seeAuthenticating by using client libraries, the gcloud CLI, or Terraformin the Identity and Access Management (IAM) documentation.

• A service account key

  Service account keys create a security risk and are not recommended. Unlikethe other credential file types, compromised service account keys can beused by a bad actor without any additional information. For moreinformation, seeBest practices for using and managing service account keys.

A credential file created by using thegcloud auth application-default login command

You canprovide credentials to ADC by running thegcloud auth application-default login command. Thiscommand creates a JSON file containing the credentials you provide (either fromyour user account or from impersonating a service account) and places it in awell-known location on your file system. The location depends on youroperating system:

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

The credentials you provide to ADC by using the gcloud CLI aredistinct from your gcloud credentials—the credentials thegcloud CLI uses to authenticate to Google Cloud. For moreinformation about these two sets of credentials, seegcloud CLI authentication configuration and ADC configuration.

By default, the access tokens generated from a local ADC file created with user credentials includethe cloud-wide scopehttps://www.googleapis.com/auth/cloud-platform.To specify scopes explicitly, you use the--scopes flagwith thegcloud auth application-default login command.

To add scopes for services outside of Google Cloud, such as Google Drive,create an OAuth Client IDand provide it to thegcloud auth application-default login command by using the--client-id-file flag, specifyingyour scopes with the--scopes flag.

The attached service account

Many Google Cloud services let you attach a service account that can beused to provide credentials for accessing Google Cloud APIs. If ADC doesnot find credentials it can use in either theGOOGLE_APPLICATION_CREDENTIALSenvironment variable or the well-known location for local ADC credentials,it uses themetadata server to get credentials for theservice where the code is running.

Using the credentials from the attached service account is the preferred methodfor finding credentials in a production environment on Google Cloud. Touse the attached service account, follow these steps:

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

For help with creating a service account, seeCreating and managing service accounts. For help with attachinga service account, seeAttaching a service account to a resource.For help with determining the required IAM roles for your serviceaccount, seeChoose predefined roles.

What's next

• Learn the best ways toprovide credentials to ADC.
• Authenticate using the Cloud Client Libraries.
• Exploreauthentication methods.
• Learn aboutclient libraries.