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
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
Troubleshoot your ADC setup
.
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.
By default, the access tokens generated from a local ADC file created with user credentials include the
cloud-wide scope
https://www.googleapis.com/auth/cloud-platform
.
To specify scopes explicitly, you use the
?scopes
flag
with the
gcloud auth application-default login
command.
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
.
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:
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.
Configure ADC:
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
.
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
:
Configure workforce identity federation.
For more information, see
Configure workforce identity federation
.
Configure the gcloud CLI to use workforce identity federation.
For more information, see
Exchange external credentials for a Google Cloud access token
.
Configure ADC:
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
.
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.
To create a service account key and make it available to ADC:
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.
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 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 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:
-
Create the service account:
gcloud iam service-accounts create
SERVICE_ACCOUNT_NAME
Replace
SERVICE_ACCOUNT_NAME
with a name for the service account.
-
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
-
To grant another role to the service account, run the command as you did in the previous step.
-
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 environment:
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
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.
To create a service account key and make it available to ADC:
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.
What's next