Authorize the gcloud CLI

In order to access Trusted 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 Trusted Cloud, you can use either a user account or a service account.

A user account is a Trusted 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 Trusted Cloud account associated with your Trusted Cloud project and not a specific user. You can use the built-in service account available when using Cloud Run 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 Trusted Cloud resources. Both Google Cloud CLI and Trusted Cloud use OAuth2 for authentication and authorization.

Choose one of the following authorization types:

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

Authorize with a user account

This section describes how to sign in to the gcloud CLI using Workforce Identity Federation.

gcloud config set universe_domain s3nsapis.fr

gcloud CLI browser-based sign-in

To sign in to the gcloud CLI using a browser-based sign-in flow, do the following:

1. Create a login configuration file.

   To create the login configuration file, run the following command. You can optionally activate the file as the default for the gcloud CLI by adding the --activate flag. You can then run gcloud auth login without specifying the configuration file path each time.

   gcloud iam workforce-pools create-login-config \
       locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
       --output-file=LOGIN_CONFIG_FILE_PATH

   Replace the following:

   • WORKFORCE_POOL_ID: the workforce pool ID
   • PROVIDER_ID: the provider ID
   • LOGIN_CONFIG_FILE_PATH: the path to a configuration file that you specify—for example, login.json

   The file contains contains the endpoints used by the gcloud CLI to enable the browser-based authentication flow and set the audience to the IdP that was configured in the workforce identity pool provider. The file doesn't contain confidential information.

   The output looks similar to the following:

   {
     "type": "external_account_authorized_user_login_config",
     "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
     "auth_url": "https://auth.cloud.s3nscloud.fr/authorize",
     "token_url": "https://sts.s3nsapis.fr/v1/oauthtoken",
     "token_info_url": "https://sts.s3nsapis.fr/v1/introspect",
   }

   To stop gcloud auth login from using this configuration file automatically, you can unset it by running gcloud config unset auth/login_config_file.

2. Sign in using browser-based authentication.

   To authenticate using browser-based sign-in authentication, you can use one of the following methods:

   • If you used the --activate flag when you created the configuration file, or if you activated the configuration file with gcloud config set auth/login_config_file, the gcloud CLI uses your configuration file automatically:

     gcloud auth login

   • To sign in by specifying the location of the configuration file, run the following command:

     gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH

   • To use an environment variable to specify the location of the configuration file, set CLOUDSDK_AUTH_LOGIN_CONFIG_FILE to the configuration path.

To discontinue using the login configuration file, do the following:

• If you used the --activate flag when you created the configuration file, or if you activated the configuration file with gcloud config set auth/login_config_file, you must run the following command to unset it:

  gcloud config unset auth/login_config_file

• Clear the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable, if it is set.

gcloud CLI headless sign-in

To sign in to gcloud CLI, using a headless flow, do the following:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

gcloud auth login --cred-file="config.json"

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

gcloud auth list

Authorize with a service account

The gcloud auth login command can authorize access with a service account by using a credential file stored on your local file system. This credential can be a user credential with permission to impersonate the service account, a credential configuration file for Workload Identity Federation, or a service account key.

Authorize a service account using service account impersonation

To authorize the gcloud CLI to use impersonated service account credentials, do the following:

1. In the Trusted Cloud console, go to the Service Accounts page.

   Go to Service Accounts

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

3. To get the permission that you need to impersonate a service account, ask your administrator to grant you the Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM role on the service account. For more information about granting roles, see Manage access to projects, folders, and organizations.

   This predefined role contains the iam.serviceAccounts.getAccessToken permission, which is required to impersonate a service account.

   You might also be able to get this permission with custom roles or other predefined roles.

4. Authorize the gcloud CLI with your user identity by running gcloud auth login.

5. To set up the gcloud CLI to use the identity and access provided by a service account by default, use the gcloud CLI config command:

   gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL
   

6. To stop using impersonated service account credentials with the gcloud CLI by default, unset the flag with the gcloud CLI config command:

   gcloud config unset auth/impersonate_service_account
   

Authorize a service account using Workload Identity Federation

To authorize the gcloud CLI with a service account using external credentials from Workload Identity Federation, do the following:

1. In the Trusted Cloud console, go to the Service Accounts page.

   Go to Service Accounts

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

3. Create a credential configuration file for Workload Identity Federation by following the directions for your supported identity provider.

4. To activate your service account, run gcloud auth login with the --cred-file flag:

   gcloud auth login --cred-file=CONFIGURATION_FILE
   

   Replace CONFIGURATION_FILE with the path to a credential configuration file for Workload Identity Federation.

Authorize a service account using a service account key

To authorize the gcloud CLI with a service account using a service account key, do the following:

1. In the Trusted Cloud console, go to the Service Accounts page.

   Go to Service Accounts

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

3. To create service account keys, see the IAM instructions to Create a service account key.

4. To activate your service account, run gcloud auth login with the --cred-file flag:

   gcloud auth login --cred-file=KEY_FILE
   

   Replace KEY_FILE with the path to a service account key file.

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

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 Trusted 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 ways to set up ADC, see Set up Application Default Credentials.

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

What's next

• To learn more about authentication and Trusted Cloud, see Authentication overview.
• To learn more about customizing gcloud CLI, see gcloud CLI properties.
• To learn more about managing named sets of gcloud CLI properties, see gcloud CLI configurations.