Authorizing Cloud SDK tools

In order to access Google Cloud, you will usually have to authorize Cloud SDK tools. 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 Cloud SDK tools.

Types of accounts

To grant authorization to Cloud SDK tools 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 Cloud SDK tools from the command line, 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 script Cloud SDK tools for use on multiple machines.

Choosing an authorization type

You must authorize the gcloud command-line tool and other tools in Cloud SDK before you can use them to manage platform resources. Cloud SDK 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 Cloud SDK tools from the command line or you're scripting Cloud SDK tools for use on a single machine.
Service account	Recommended if you're installing and setting up Cloud SDK 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.

Authorizing with a user account

You can use the following gcloud tool commands to authorize access with a user account:

Command	Description
`gcloud init`	Authorizes access and performs other common Cloud SDK 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 Cloud SDK configuration. The gcloud tool and other Cloud SDK tools use the stored credentials to access Google Cloud. You can have any number of accounts with stored credentials for a single Cloud SDK installation, but only one account is active at any time.

Running gcloud init

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

To authorize access and perform other common Cloud SDK setup steps:

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.
Follow the browser-based authorization flow to authenticate the account and grant access permissions.

Read Initializing Cloud SDK to learn more about this command and Cloud SDK initialization.

Running gcloud auth login

gcloud auth login authorizes the user account only.

To authorize access without performing other setup steps:

Run gcloud auth login:
```
gcloud auth login
```
Or:
```
gcloud auth login --no-launch-browser
```
You can use the --no-launch-browser flag to prevent the command from automatically opening a web browser. You must then manually open the provided URL in a browser on your local system to complete the authorization process.
Follow the browser-based authorization flow to authenticate the account and grant access permissions.

Authorizing 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 Cloud SDK configuration.

To authorize using a service account:

Go to the Service Accounts page in the Google Cloud Console.

Go to the Service Accounts page
Choose an existing account or create a new account by clicking Create service account.
To create and download a JSON-formatted key file:
1. Click the action menu 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.
If required, move the key file to a location on the same system where you are authorizing Cloud SDK tools.

Alternatively, instead of Steps 1-4, you could procure a key for an an existing service account using gcloud iam service-accounts keys create.
To activate your service account, run gcloud auth activate-service-account:
```
gcloud auth activate-service-account [ACCOUNT] --key-file=[KEY_FILE]
```
Delete the key file from the system. Note that the gcloud tool stores keys and the gcloud tool copy of the key remains.

Listing accounts

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

gcloud auth list

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

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

Switching the active account

To switch the active account, run gcloud config set:

gcloud config set account [ACCOUNT]

where [ACCOUNT] is the full e-mail 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 tool on a per-invocation basis, override the active account using the --account flag.

Setting authorized session length (Google Workspace only)

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

Read the Set session length for Google Cloud services support article to learn more about enabling this feature.

Revoking credentials for an account

You can revoke credentials when you want to disallow access by the gcloud tool and other Cloud SDK tools 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 Cloud SDK for all machines, remove Cloud SDK from the list of apps that have access to your account.

Finding your credential files

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

gcloud info

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

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

What's next

Read Google Cloud Auth Guide to learn more about authorization and Google Cloud.
Read Cloud SDK Configurations to learn more about configurations.
Read Cloud SDK Properties to learn more about properties.