.Gcloud

Managing Google Cloud CLI Credentials

Learn how gcloud credentials are stored, inspected, refreshed, revoked, and separated from Application Default Credentials and service account authentication.

Google Cloud CLI, commonly called gcloud, uses credentials to prove which principal is making a request. A principal is an identity recognized by Google Cloud, such as a human user or service account.

This lesson covers interactive user login, active account selection, Application Default Credentials (ADC), service account authentication, impersonation, credential storage, lifecycle management, security, and troubleshooting.

Authentication and authorization

Authentication verifies who is making a request. Authorization checks whether that authenticated identity has permission to perform a particular action on a resource.

For example, gcloud auth login can successfully authenticate developer@example.com. That does not guarantee that this account can create virtual machines, read a storage bucket, or deploy to every project. IAM roles and policies determine those permissions.

An access token is short-lived material presented to Google APIs. A refresh token is longer-lived authorization material that can be used to obtain new access tokens while the local authorization remains valid. OAuth 2.0 is the authorization framework commonly used for interactive user sign-in and delegated access.

Where gcloud stores local credential state

The Google Cloud CLI maintains configuration and authenticated-account state in a local configuration directory. Common defaults are:

  • Linux and macOS: ~/.config/gcloud
  • Windows: %APPDATA%\gcloud

The directory contains configuration data and a credentials database or related files used to remember authenticated accounts and refresh authorization. File names and internal details can vary by CLI version and platform.

If CLOUDSDK_CONFIG is set, it overrides the default directory. This is useful for isolation, but it can make accounts appear to disappear when a new terminal session points to a different location.

export CLOUDSDK_CONFIG=/path/to/isolated/gcloud-config

Treat the entire credential directory as sensitive. Do not commit it to version control, upload it in support requests, copy it casually between machines, or include it in configuration backups without protecting it. Access tokens, refresh tokens, service account key files, and generated credentials are secrets.

Interactive user login

Run the following command on a workstation when you need a human Google account for CLI commands:

gcloud auth login
  1. The CLI starts a browser-based authorization flow or provides instructions for opening one.
  2. You choose the Google account to use.
  3. You review and grant consent when required.
  4. After authorization, control returns to the terminal.

The CLI records the account locally and can normally refresh access tokens automatically while the authorization remains valid. This is convenient for development, but it is not a substitute for IAM permissions.

On a remote shell or a machine without a usable browser, use the non-browser option offered by the installed CLI, or begin the flow on another machine as instructed by gcloud auth login. Avoid sending authorization codes or tokens through chat, tickets, or scripts.

Accounts, configurations, and the active account

Several accounts can be authenticated in one local gcloud environment. The active account is the account used by default for commands that require authentication.

gcloud auth list

The output identifies locally authenticated accounts and marks the active one. To select an already authenticated account:

gcloud config set account USER_ACCOUNT_EMAIL

A configuration is a named set of gcloud properties. It can contain an account, project, region, and other settings. The active account and active project are independent settings:

gcloud config list
gcloud config set project PROJECT_ID

Changing the project does not change the account. Changing the account does not change the project. Check both before running a destructive or production command.

Credential types and intended uses

Columns: Credential type; Typical user; Used by; How obtained; Security considerations.

Interactive user credentials for gcloud: Human developer or administrator; gcloud commands; gcloud auth login; protect the local OAuth state and do not use personal credentials in shared automation.

Application Default Credentials: Developer or application runtime; Google Cloud client libraries and application code; local login, an explicitly configured credential source, or the runtime environment; keep ADC separate from assumptions about the gcloud active account.

Service account key credentials: Workload or automation that cannot use a stronger mechanism; gcloud or application code; a downloaded private key file; long-lived private keys are high-risk secrets and should be avoided when alternatives exist.

Service account impersonation credentials: Authorized human or workload acting for a service account; a single gcloud command or configured gcloud session; short-lived credentials obtained using existing credentials; the caller must have permission to impersonate the target.

Attached service account credentials: Workload running on an eligible Google Cloud resource; client libraries and applications; the platform supplies credentials for the attached identity; prefer this managed, short-lived approach over distributing key files.

Application Default Credentials are separate

Application Default Credentials (ADC) are a standard credential-discovery mechanism used by Google Cloud client libraries and application code. They are not simply another name for the gcloud CLI's active account.

Create local ADC for development with:

gcloud auth application-default login

This performs a separate authorization flow and writes local ADC state for libraries that support it. Logging in with gcloud auth login does not necessarily create ADC. Creating ADC does not necessarily select or change the gcloud active account.

At a high level, a client library commonly checks credential sources in an order like this:

  1. Credentials explicitly configured by the application or an environment variable such as GOOGLE_APPLICATION_CREDENTIALS.
  2. Local ADC created for development.
  3. Credentials supplied by the execution environment, such as an attached service account on a Google Cloud resource.

Exact behavior can vary by library and runtime. An application that cannot find credentials may need ADC even though gcloud commands work.

Service account authentication

A service account is a non-human Google Cloud identity intended for workloads and automation. It is usually more appropriate than a personal user account for scheduled jobs, deployment systems, and other non-interactive processes.

When a key file is genuinely required, activate the service account as follows:

gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL --key-file=KEY_FILE.json

The service account becomes an authenticated account in the selected gcloud configuration and can become the active account used by subsequent commands. Verify the result with gcloud auth list and gcloud config list.

A service account key is private credential material, often stored in a JSON file. Anyone who obtains an unexpired private key may be able to authenticate as that service account. Do not place keys in source control, container images, shared drives, shell history, or tickets.

Prefer attached service accounts, workload identity federation, short-lived credentials, or impersonation where supported. These approaches reduce the need to distribute and rotate long-lived private keys.

Service account impersonation

Impersonation uses an existing principal's credentials to obtain short-lived credentials for a service account. The caller does not need the service account's private key, but must have permission to impersonate the target service account.

Use impersonation for one command with:

gcloud RESOURCE_COMMAND --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

You can configure impersonation for the active gcloud configuration:

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL

Per-command impersonation is useful when only one operation should run as the deployment identity. Configuration-level impersonation is convenient for a set of related commands, but inspect it when a command unexpectedly uses a different identity.

Inspecting credentials without exposing secrets

Use account and configuration commands to inspect identity-related settings safely:

gcloud auth list
gcloud config list

These commands help identify the active account, project, and relevant properties without requiring you to print tokens. Check for command-level or configuration-level impersonation as well.

Printing an access token can be a diagnostic technique when testing an API request, but it creates a secret in terminal scrollback, logs, process captures, or copied text. If you must use a token diagnostically, do not print it in shared logs, paste it into a ticket, or commit it to source control.

gcloud auth print-access-token

Revocation and re-authentication

Revoke one locally stored user account with:

gcloud auth revoke USER_ACCOUNT_EMAIL

For local ADC, use:

gcloud auth application-default revoke

After revocation, authenticate again when needed:

gcloud auth login

Revoking local authorization removes or invalidates the local authorization for that credential source. It does not replace organization-level account disablement, IAM changes, or emergency key revocation procedures. If a service account key may have leaked, disable or delete that key through the authorized security process rather than relying only on local cleanup.

Re-authenticate when an account is disabled, consent is revoked, a password or security policy changes, an administrator invalidates sessions, or a refresh token becomes invalid. If login still fails, verify account status, organization policies, and IAM access with the appropriate administrator.

Security practices

  • Protect credential directories, OAuth tokens, ADC files, service account keys, and generated access tokens as secrets.
  • Use least-privilege IAM roles. Successful authentication only proves identity; it does not grant permissions.
  • Do not use personal user credentials in shared automation or CI/CD systems.
  • Never commit credentials, configuration backups, or key files to version control.
  • Use separate operating-system accounts, isolated CLOUDSDK_CONFIG directories, or named gcloud configurations to separate work and personal identities.
  • Prefer short-lived, attached, federated, or impersonated credentials over downloadable service account keys.
  • Before a destructive command, verify both the active account and the active project.

Common authentication commands

Columns: Command; Purpose; When to use it; Important caution.

gcloud auth login: Authenticate an interactive user for gcloud; use on a development workstation; protect the resulting local authorization.

gcloud auth list: List authenticated accounts and identify the active account; use before identity-sensitive commands; account listing does not show IAM permissions.

gcloud config set account USER_ACCOUNT_EMAIL: Set the default account for the active configuration; use to switch among stored accounts; verify that the selected account is intended.

gcloud auth application-default login: Create local ADC; use for local client-library development; this does not necessarily change the gcloud active account.

gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL --key-file=KEY_FILE.json: Activate a service account from a key file; use only when a key is required; the key file is a high-value secret.

gcloud auth revoke USER_ACCOUNT_EMAIL: Revoke local authorization for one account; use during cleanup or recovery; local revocation does not by itself revoke every server-side credential.

gcloud auth application-default revoke: Remove local ADC; use when cleaning up a workstation; applications will no longer discover that local ADC source.

Troubleshooting authentication and authorization

Columns: Symptom; Likely cause; How to verify; Resolution.

No active account: No account is active in the selected configuration; run gcloud auth list; authenticate with gcloud auth login or select an existing account with gcloud config set account.

Wrong account is used: Another account, named configuration, or impersonation setting is active; run gcloud auth list and gcloud config list; select the intended account, switch configuration, or remove unintended impersonation.

Permission denied: Authentication succeeded but the principal lacks an IAM permission, or the wrong project or resource is targeted; confirm account, project, and required permission; request an appropriate least-privilege IAM role through the authorized process.

Application code cannot find credentials: gcloud login was completed but ADC was not created, or the application uses another discovery context; inspect ADC setup and GOOGLE_APPLICATION_CREDENTIALS; run gcloud auth application-default login when appropriate and follow the library's discovery rules.

Credentials fail after a policy or account change: Local authorization was revoked or invalidated; retry login and check account status; revoke stale local authorization, run gcloud auth login, and contact an administrator if access remains blocked.

Credentials appear missing after changing CLOUDSDK_CONFIG: The CLI is reading a different directory, OS user, or environment; inspect the variable and current user; restore the intended path instead of copying credential files between machines.

Practical workflow: a personal development machine

  1. Run gcloud auth login and complete the browser flow.
  2. Run gcloud auth list and confirm the active account.
  3. Run gcloud config set project PROJECT_ID and confirm the project with gcloud config list.
  4. If local application code uses client libraries, create ADC separately with gcloud auth application-default login.
  5. Before important operations, check account, project, and impersonation settings again.

Practical workflow: automation without a key file

  1. Use an existing authorized identity, such as a workload identity or administrator-approved user identity.
  2. Grant that caller permission to impersonate the deployment service account.
  3. Run the deployment with --impersonate-service-account=SERVICE_ACCOUNT_EMAIL, or configure the property for an isolated gcloud configuration.
  4. Give the target service account only the IAM roles required for deployment.
  5. Remove local credentials and inspect the configuration after the task completes.

Summary

  • gcloud credentials authenticate a principal; IAM authorization determines what that principal may do.
  • Multiple accounts can be stored locally, but only one is normally active per configuration.
  • The active account and active project are independent settings.
  • gcloud user credentials and ADC serve different consumers and must be configured separately.
  • Service account keys are sensitive and should be replaced by short-lived, attached, federated, or impersonated credentials where possible.
  • Use account and configuration inspection to diagnose identity problems without exposing tokens.
  • Keep credential directories and all credential material out of source control and shared automation.

See the Google Cloud credentials guide for related credential-management material.