Authorize the gcloud CLI

Stay organized with collections Save and categorize content based on your preferences.

In order to access Google Cloud, you will usually have to authorize the Google Cloud CLI. This page demonstrates available authorization options and shows you how to manage the accounts you use for authorization. If you're using a Compute Engine instance or Cloud Shell, you're not required to authorize the gcloud CLI.

Types of accounts

To grant authorization to the gcloud CLI to access Google Cloud, you can use either a user account or a service account.

A user account is a Google Cloud account that allows end users to authenticate to your application. For most common use cases, especially interactively using the gcloud CLI, using a user account is best practice.

A service account is a Google Cloud account associated with your Google Cloud project and not a specific user. To have your application use a service account, you provide a service account key to your application. Alternatively, you can use the built-in service account available when using Cloud Functions, App Engine, Compute Engine, or Google Kubernetes Engine. A service account is recommended to run gcloud CLI scripts on multiple machines.

Choose an authorization type

You must authorize the Google Cloud CLI to manage Google Cloud resources. Both Google Cloud CLI and Google Cloud use OAuth2 for authentication and authorization.

Choose one of the following authorization types:

Type Description
User account Recommended if you're using the gcloud CLI from the command line or you're writing scripts with the gcloud CLI for use on a single machine.
Service account Recommended if you're installing and setting up the gcloud CLI as part of a machine deployment process in production, or for use on Compute Engine virtual machine instances where all users have access to root.

For more information about authentication and Google Cloud, see Authentication overview.

Authorize with a user account

Use the following gcloud CLI commands to authorize access with a user account:

Command Description
gcloud init Authorizes access and performs other common setup steps.
gcloud auth login Authorizes access only.

During authorization, these commands obtain account credentials from Google Cloud and store them on the local system. The specified account becomes the active account in your configuration. The gcloud CLI uses the stored credentials to access Google Cloud. You can have any number of accounts with stored credentials for a single gcloud CLI installation, but only one account is active at a time.

Run gcloud init

gcloud init authorizes access and performs other common setup steps. gcloud init uses a web-based authorization flow to authenticate the user account and grant access permissions.

To authorize access and perform other common setup steps:

  1. Run gcloud init:

    gcloud init
    

    Or, to prevent the command from automatically opening a web browser:

    gcloud init --console-only
    

    Using the --console-only flag is useful if you're running the command on a remote system using ssh and do not have access to a browser on that system. You must then manually open the provided URL in a browser on your local system to complete the authorization process.

  2. Follow the browser-based authorization flow to authenticate the account and grant access permissions.

For more information about gcloud init, see Initializing the gcloud CLI.

Run gcloud auth login

Running gcloud auth login authorizes the user account only. To authorize access without performing other setup steps, use one of the following options.

  • If you want to authorize the gcloud CLI on a machine with a browser, follow these steps.

    1. Authorize the gcloud CLI:

      gcloud auth login
      
    2. Follow the browser-based authorization flow to authenticate the account and grant access permissions.

  • If you want to authorize the gcloud CLI on a machine that doesn't have a browser and you can install the gcloud CLI on another machine with a browser, use the --no-browser flag.

    1. Authorize the gcloud CLI:

      gcloud auth login --no-browser
      
    2. Copy the long command that begins with gcloud auth login --remote-bootstrap=".

    3. Paste and run this command on the command line of a different, trusted machine that has local installations of both a web browser and the gcloud CLI tool version 372.0 or later.

    4. Copy the long URL output from the machine with the web browser.

    5. Paste the long URL back to the first machine under the prompt, "Enter the output of the above command", and press Enter to complete the authorization.

  • If you want to authorize the gcloud CLI on a machine that doesn't have a browser and you cannot install the gcloud CLI on another machine with a browser, use the --no-launch-browser flag. The --no-launch-browser flag prevents the command from automatically opening a web browser.

    1. Authorize the gcloud CLI:

      gcloud auth login --no-launch-browser
      
    2. Copy the long URL that begins with https://accounts.google.com/o/oauth2/auth...

    3. Paste this URL into the browser of a different, trusted machine that has a web browser.

    4. Copy the authorization code from the machine with the web browser.

    5. Paste the authorization code back to the first machine at the prompt, "Enter verification code", and press Enter to complete the authorization.

  • If you already have an access token, use one of the following methods to pass the access token to the gcloud CLI:

    • Store the access token in a file and set its path through the --access-token-file flag.
    • Store the access token in a file and set its path in the auth/access_token_file property.
    • Set the CLOUDSDK_AUTH_ACCESS_TOKEN environment variable to the access token value.

Authorize with a service account

gcloud auth activate-service-account authorizes access using a service account. As with gcloud init and gcloud auth login, this command saves the service account credentials to the local system on successful completion and sets the specified account as the active account in your gcloud CLI configuration.

To authorize using a service account:

  1. Go to the Service Accounts page in the Google Cloud console.

    Go to Service Accounts

  2. Choose an existing account or create a new account by clicking Create service account.

  3. To create and download a JSON-formatted key file:

    1. Click in the Actions column for the service account and then select Manage keys.
    2. Click the Add key drop-down menu.
    3. Click Create new key.
    4. Select a key format and then click Create.
  4. If required, move the key file to a location on the same system where you are authorizing the gcloud CLI.

    Alternatively, instead of Steps 1-4, you could procure a key for an an existing service account using gcloud iam service-accounts keys create.

  5. To activate your service account, run gcloud auth activate-service-account:

    gcloud auth activate-service-account ACCOUNT --key-file=KEY_FILE
    
  6. Delete the key file from the system. Note that the gcloud CLI stores keys and the gcloud CLI copy of the key remains.

List accounts

To list the accounts whose credentials are stored on the local system, run gcloud auth list:

gcloud auth list

The gcloud CLI lists the accounts and shows which account is active:

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

Switch the active account

To switch the active account, run gcloud config set:

gcloud config set account ACCOUNT

where [ACCOUNT] is the full email address of the account.

You can also switch accounts by creating a separate configuration that specifies the different account and switching between configurations:

gcloud config configurations activate CONFIGURATION

If you want to switch the account used by the gcloud CLI on a per-invocation basis, override the active account using the --account flag.

Set authorized session length (Google Workspace only)

As an administrator, you can control how long different users can access the gcloud CLI without having to re-authenticate. For example, you can force users with elevated privileges to re-authenticate more frequently than regular users.

For more information, see Set session length for Google Cloud services.

Revoke credentials for an account

You can revoke credentials when you want to disallow access by the gcloud CLI by a particular account. You don't need to revoke credentials to switch between accounts.

To revoke credentials, run gcloud auth revoke:

gcloud auth revoke ACCOUNT

To revoke all access for the gcloud CLI for all machines, remove the gcloud CLI from the list of apps that have access to your account.

Work with credential files

Find your credential files

To find the location of your credential files, run gcloud info:

gcloud info

The gcloud CLI prints information about your installation. Credential files are stored in the user configuration directory:

User Config Directory: [/home/USERNAME/.config/gcloud]

Set up Application Default Credentials

The gcloud CLI provides support for managing Application Default Credentials (ADC) with the gcloud auth application-default command group. To make user credentials available to ADC, run gcloud auth application-default login:

gcloud auth application-default login

These credentials are not used by the gcloud CLI. For more information, see How to provide credentials for ADC and How Application Default Credentials works.

What's next