Set up ADC for a 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.

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.

Tips for configuring ADC with your user credentials

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

• ADC configured with a user account might not work for some APIs without extra configuration steps. 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.

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.

Credentials from a local ADC file generated by using service account impersonation are not supported by all of the authentication libraries. For more information, see Error returned for local credentials from service account impersonation.

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.

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.

   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

• Understand best practices for using service account keys.
• Learn more about how ADC finds credentials.
• Authenticate for using Cloud Client Libraries.
• Authenticate for using REST.
• Explore authentication methods.