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 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
• Google Cloud cloud-based development environments
• Compute Engine or other Google Cloud services that support attaching a service account

• Google Kubernetes Engine

• 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 the credentials associated with your user account.

When you configure ADC with your user account, you should be aware of the following facts:

• ADC configuration with a user account 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 User credentials not working.

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

• Your local ADC file is associated with your user account, not your gcloud CLI configuration. Changing to a different gcloud CLI configuration might change the identity used by the gcloud CLI, but it does not affect your local ADC file or the ADC configuration.

How you configure ADC with your user account depends on whether your user account is managed by Google—in other words, it is a Google Account—or by another identity provider (IdP), and federated by using Workforce Identity Federation.

Configure ADC with your Google Account

To configure ADC with a Google Account, you use the Google Cloud CLI:

1. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   Note: To add scopes for services outside of Google Cloud, such as Google Drive, create an OAuth Client ID and provide it to the gcloud auth application-default login command by using the --client-id-file flag, specifying your scopes with the --scopes flag.

   A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC.

Configure ADC with an account managed by an external IdP

To configure ADC for a user account managed by an external IdP and federated with Workforce Identity Federation:

1. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

   A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC.

Service account credentials

You can configure 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:

• C#
• 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

You can now use client libraries using the supported languages the same way you would after setting up a local ADC file with user credentials. Credentials are automatically found by the authentication libraries. For more information, see Authenticate for using client libraries.

Service account keys

If you cannot use a user account 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 operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

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 credentials. This variable applies only 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 credentials.

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

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

   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 environments

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 signed in, and manages any authorizations required. You cannot use the gcloud CLI to configure ADC in these environments. If you need to use a different user account to configure ADC, or configure ADC 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 Run 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 the required role to the principal that will 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 a Google Account

GKE

Authentication for containerized applications running on GKE or GKE Enterprise 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 addon.

Run containerized applications on Google Cloud

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

• For GKE Enterprise, see the authentication overview and Use fleet Workload Identity Federation for GKE.
• For GKE, see Access Google Cloud APIs from GKE workloads.
• For Knative serving, see Using Workload Identity Federation for GKE for Knative serving.

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 an external IdP 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 Workload Identity Federation with other clouds.

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 operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

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 credentials. This variable applies only 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 credentials.

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

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

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