Authenticate for using the gcloud CLI

This page describes various ways to sign in to the gcloud CLI. The Google Cloud CLI is a command-line tool you can use for Google Cloud administration. Most services support the gcloud CLI.

If you plan to use client libraries or third-party development tools that support Application Default Credentials (ADC) in a local development environment, you need to set up ADC in your local environment. For more information, see Set up Application Default Credentials for a local development environment.

How you authenticate to and use the gcloud CLI depends on where you are running the tool:

Local environment

For most use cases, you can use your user credentials to sign in to the gcloud CLI, but you can also use a service account.

When you sign in to the gcloud CLI in a local environment, the tool places your access and refresh tokens in your home directory. Any user with access to your file system can use those credentials. For more information, see Mitigating compromised OAuth tokens for Google Cloud CLI.

The following table describes your options for signing in to the gcloud CLI and how that affects the credentials used by the tool to authenticate and authorize to Google APIs.

Credential type Authentication command Notes More information
User credentials

The gcloud CLI uses your user credentials for authentication and authorization for all Google APIs.

To use a service account for authorization to Google APIs, use service account impersonation.

Service account gcloud auth login --cred-file=SERVICE_ACCT_KEY

This method is not recommended, because using service account keys increases risk.

To use a service account for authorization to Google APIs, sign in to the gcloud CLI with your user credentials, and then use service account impersonation.

Cloud Shell

When you use Cloud Shell, you don't need to sign in to the gcloud CLI, but you do need to authorize the use of your account before using any Google tools from Cloud Shell. After you do that, the gcloud CLI uses your user credentials to access Google APIs.

For more information, see Authorize with Cloud Shell.

Google Cloud compute resources

When you use the gcloud CLI on Google Cloud compute resources such as Compute Engine virtual machines, you don't need to initialize or sign in to the gcloud CLI, because it gets its credentials and configuration information from the hosting compute resource by using the metadata server.

Credential type Authentication command Notes More information
Service account Not applicable The gcloud CLI uses the service account attached to the compute resource for authentication and authorization for all Google APIs. Google Cloud services that support attaching a service account

Workload identity federation

When you use the gcloud CLI with workload identity federation, you use the workload identity federation configuration file to sign in to the gcloud CLI. For more information, see Workload identity federation.

gcloud CLI credentials and ADC credentials

When you sign in to the gcloud CLI, you use the gcloud auth login command to provide your user credentials, which the gcloud CLI uses for authentication and authorization to manage Google Cloud resources and services. These credentials are your gcloud CLI credentials.

When you use the gcloud CLI to provide credentials to ADC, you use the gcloud auth application-default login command. This command puts your credentials into a well-known location for use by ADC in your local environment. These are your local ADC credentials.

Your local ADC credentials and your gcloud CLI credentials are two distinct sets of credentials. The gcloud CLI does not use ADC to obtain credentials.

The following table shows the two commands and what they do:

Command Description
gcloud auth login

Generates user credentials that are used to authenticate to and authorize access to Google Cloud services.

gcloud auth application-default login

Generates user credentials that are provided to Application Default Credentials for use in a local development environment.

Usually, you use the same account to sign in to the gcloud CLI and to provide user credentials to ADC, but you can use different accounts if needed.

What's next