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

Choose the environment 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 Anthos
• On-premises or another cloud provider

Local development environment

You can provide either your user credentials or service account credentials to ADC in a 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.

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.

When you provide user credentials to create a local ADC file, you should be aware of the following facts:

• 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.

• The local ADC contains your access and refresh tokens. Any user with access to your file system can use those credentials. If you no longer need these local credentials, you can revoke them by using the gcloud auth application-default revoke command.

• 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, someone must grant you the required roles.

• Your local ADC file is associated with your user account, not your gcloud CLI configuration. Changing to a different gcloud CLI configuration does not affect your local ADC file or the credentials provided to ADC.

Service account credentials

You can set up ADC with credentials from a service account by using service account impersonation or by using a service account key.

Service account impersonation

You can use service account impersonation to set up a local Application Default Credentials (ADC) file. Client libraries that support impersonation can use those credentials automatically. Local ADC files created by using impersonation are supported in the following languages:

• Go
• Java
• Node.js
• Python

You must have the Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM role on the service account you are impersonating. For more information, see Required roles.

Use service account impersonation to create a local ADC file:

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Service account keys

If you cannot use user credentials or service account impersonation for local development, you can use a service account key.

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other management operations such as key rotation. 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 cannot use the gcloud CLI to provide credentials to ADC in these environments. If you need to provide a different user account to ADC, or provide credentials by using a service account, use a local development environment or a Google Cloud compute resource as your development environment.

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 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.

Set up authentication:

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. To provide access to your project and your resources, grant a role to the service account:

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • ROLE: the role to grant
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
3. To grant another role to the service account, run the command as you did in the previous step.

4. Grant your Google Account a role that lets you use the service account's roles and attach the service account to other resources:

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • USER_EMAIL: the email address for your Google Account

GKE or Anthos

Authentication for containerized applications running on GKE or Anthos is handled differently between local testing environments and Google Cloud environments.

Test containerized applications locally

To test your containerized application on your local workstation, you can configure containers to authenticate with your local credential file. To test the containers, use a local Kubernetes implementation such as minikube and the GCP Auth minikube addon.

Run containerized applications on Google Cloud

You set up authentication for Google Cloud containerized environments differently depending on the context:

• For Anthos, see the authentication overview and Use fleet Workload Identity.
• For GKE, 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.

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other management operations such as key rotation. 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.

   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.

What's next

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