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

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

How you provide your user credentials to ADC 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.

Provide user credentials for your Google Account

To provide your user credentials to ADC for a Google Account, you use the Google Cloud CLI:

  1. Install and initialize the gcloud CLI.

    When you initialize the gcloud CLI, be sure to specify a Google Cloud project in which you have permission to access the resources your application needs.

  2. Create your credential file:

    gcloud auth application-default login

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

Provide user credentials for an account managed by an external IdP

To provide your user credentials for a user account managed by an external IdP and federated with workforce identity federation, you need your workforce pool provider name. Your administrator should be able to provide you with this information. The workforce pool provider name has the following format:

locations/global/workforcePools/POOL_ID/provider/PROVIDER_ID

Provide your user credentials to ADC for a federated user account:

  1. Create your login configuration file and set the gcloud CLI auth/login_config_file property to point to its location, using the iam workforce-pools create-login-config command:

    gcloud iam workforce-pools create-login-config PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE --activate
    

    Replace the following:

    • PROVIDER_ID: the provider ID
    • LOGIN_CONFIG_FILE: a path to the configuration file that you specify—for example, login.json

    The file that is created looks similar to the following example:

    {
    "type": "external_account_authorized_user_login_config",
    "audience": "//iam.googleapis.com/PROVIDER_ID",
    "auth_url": "https://auth.cloud.google/authorize",
    "token_url": "https://sts.googleapis.com/v1/oauthtoken",
    "token_info_url": "https://sts.googleapis.com/v1/introspect",
    }
    

  2. Sign in to the gcloud CLI using the login file:

    gcloud auth login
    
  3. Initialize the gcloud CLI:

    gcloud init
    
  4. Create your local ADC file:

    gcloud auth application-default login
    

For more information, see Workforce identity federation.

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:

  • 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

Service account keys

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

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 credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

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

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
  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 GKE Enterprise

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 context:

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

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.

What's next