Authenticate for the gcloud CLI

This document is only about authentication for the Google Cloud CLI to access Cloud de Confiance by S3NS resources. If you need to authenticate workloads using Cloud Client Libraries or Google API Client Libraries, see How Application Default Credentials works.

Before you begin

If you're new to Cloud de Confiance by S3NS, see Set up the Google Cloud CLI for Cloud de Confiance for instructions on setting up your environment and signing in to authorize the gcloud CLI to act on your behalf.

The rest of this document covers more complex scenarios such as using the gcloud CLI with different principal types, appropriate authentication methods for different environments, switching principals, and managing stored credentials.

Authentication methods

All gcloud CLI commands need to authenticate to Cloud de Confiance APIs. You can authenticate in the following ways:

• Authorize and store credentials: Suitable for humans to use in a local development environment. You can authorize the gcloud CLI to act on behalf of a principal using the gcloud auth login command. After initial authentication, this command stores credentials in the gcloud CLI configuration directory. The gcloud CLI uses these stored credentials to authenticate automatically for subsequent commands until your session expires, or you revoke the authorization.

• Authenticate with a credential file: Suitable for workloads running outside of Cloud de Confiance by S3NS. You can use environment variables or gcloud CLI configuration properties to specify a credential file for automatic authentication. This file can be one of the following:

  • A Workload Identity Federation credential configuration file.

  • A service account key.

• Provide an access token: Suitable for highly isolated automated workflows or stateless sessions on shared machines. You can bypass credential storage by providing an access token directly to the gcloud CLI. You can do this by setting a specific environment variable to the raw access token string, or by pointing the gcloud CLI to a file containing the access token.

After authenticating, you can optionally let the gcloud CLI impersonate a service account by providing the service account's email address.

You can use multiple authentication methods in a single environment. However, only one principal is used for any given gcloud command. To determine which principal to use, the gcloud CLI follows a priority order.

When you don't need to authenticate

You don't need to authenticate for the gcloud CLI in the following situations:

• When using the gcloud CLI from a resource that exposes a Compute Engine metadata server. This includes resources such as Compute Engine VM instances, Cloud Run services, and Cloud Build builds. The gcloud CLI authenticates using the service account attached to the VM, and is authorized to access the same resources as that service account within the limits of any access scopes that have been applied.

Choose the right principal for the task

There are different types of principals for human use and automated workloads. The principal type you need to use affects how you authenticate.

• Service accounts: These are accounts specific to Cloud de Confiance by S3NS that workloads can use to access services or resources. You typically don't authenticate as a service account directly. Instead, you attach a service account to a resource such as a Compute Engine VM, or use service account impersonation.

• Federated principals: These are identities that reference user or service accounts in an external identity provider. There are two types of federated principals supported by Cloud de Confiance by S3NS, which have similar names:

  • Workforce Identity Federation: Lets human users sign in to Cloud de Confiance by S3NS with identities managed by an external identity provider. If your organization already has single sign-on (SSO) set up, you might use this type of identity to authenticate to Cloud de Confiance by S3NS.

    Your identity provider must support OpenID Connect (OIDC) or SAML 2.0 to use Workforce Identity Federation.

  • Workload Identity Federation: Lets workloads running outside of Cloud de Confiance by S3NS operate on Cloud de Confiance by S3NS resources.

    You can use Workload Identity Federation with workloads that authenticate using X.509 client certificates; that run on Amazon Web Services (AWS) or Azure; on-premises Active Directory; deployment services, such as GitHub and GitLab; and with any identity provider that supports OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) V2.0.

Use the gcloud CLI as a human

You can use the gcloud CLI with a federated user identity that's managed in an external identity provider (IdP). You do this with Workforce Identity Federation.

The following instructions assume you already have a Workforce Identity Federation pool and provider set up to work with your IdP.

To use the gcloud CLI with a federated user identity, you create a login configuration file, and then sign in using a browser-based flow:

1. Run the following command to create a login configuration file:

   Linux and macOS

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

   Windows (PowerShell)

   gcloud iam workforce-pools create-login-config `
       locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
       --output-file=LOGIN_CONFIG_PATH

   Replace the following:

   • WORKFORCE_POOL_ID: The Workforce Identity Federation pool ID.
   • WORKFORCE_PROVIDER_ID: The Workforce Identity Federation provider ID.
   • LOGIN_CONFIG_PATH: The path to write the login configuration file to. For example, login-config.json.

   The login configuration file 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 login configuration file content looks similar to the following:

   {
     "universe_domain": "s3nsapis.fr",
     "universe_cloud_web_domain": "cloud.s3nscloud.fr",
     "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"
   }

2. Point to the login configuration file with an environment variable, a property in the active gcloud CLI configuration, or use it directly with the gcloud auth login command:

   Environment variable

   To use the login configuration file with an environment variable, complete the following instructions:

   1. Set the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable to the path of the login configuration file.

   2. Run the following command:

      gcloud auth login

   3. The gcloud CLI references the environment variable to find the login configuration file, and then starts the authentication process. Follow the browser-based flow to authenticate and authorize the gcloud CLI to access resources on your behalf for future commands.

   To stop using the login configuration file for gcloud auth login commands, clear the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable.

   gcloud CLI configuration

   To use the login configuration file with a gcloud CLI configuration property, complete the following instructions:

   1. Set the active gcloud CLI configuration's auth/login_config_file property to the login configuration file's path with the following command:

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

   2. Run the following command:

      gcloud auth login

   3. The gcloud CLI references the configuration property to find the login configuration file, and then starts the authentication process. Follow the browser-based flow to authenticate and authorize the gcloud CLI to access resources on your behalf for future commands.

   To stop using the login configuration file for gcloud auth login commands, unset the property with the following command:

   gcloud config unset auth/login_config_file

   gcloud auth login

   To use the login configuration file directly with the gcloud auth login command, complete the following instructions:

   • If you used the --activate flag when you created the login configuration file, run the following command:

     gcloud auth login

   • If you didn't use the --activate flag when you created the login configuration file, run the following command:

     Linux and macOS

     gcloud auth login \
         --login-config=LOGIN_CONFIG_PATH

     Windows (PowerShell)

     gcloud auth login `
         --login-config=LOGIN_CONFIG_PATH

     Replace LOGIN_CONFIG_PATH with the path of your login configuration file.

   The gcloud auth login command stores access credentials in your home directory. The authenticated principal becomes the active principal in your active gcloud CLI configuration. Unless overridden, the gcloud CLI uses these stored credentials to access Cloud de Confiance by S3NS.

Use the gcloud CLI with workloads

For automated workloads, you typically authenticate with one of the following:

• A federated workload identity, using Workload Identity Federation

• A service account, using impersonation

Federated workload identities

You can use the gcloud CLI with a federated workload identity. You do this with Workload Identity Federation.

A workload can either access Cloud de Confiance by S3NS resources directly by acting as a principal defined by a workload identity pool, or impersonate a service account attached to a workload identity pool.

We recommend using the direct access method to avoid over-permissioned service accounts, and to log resource access using the federated principal's identifier. Only use service account impersonation when Cloud de Confiance by S3NS APIs don't support Workload Identity Federation.

The following instructions assume you already have a Workload Identity Federation pool and provider set up to work with your IdP.

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

2. Define the path to the credential configuration file in an environment variable, as a property in the active gcloud CLI configuration, or with the gcloud auth login command:

   Environment variable

   Set the CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE environment variable to the path of the credential configuration file. The gcloud CLI references the file each time it runs a command, and obtains a credential from your IdP. This credential is exchanged for an access token to Cloud de Confiance by S3NS.

   To stop using the credential configuration file, clear the CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE environment variable.

   gcloud CLI configuration

   Set the active gcloud CLI configuration's auth/credential_file_override property to the credential configuration file's path with the following command:

   gcloud config set auth/credential_file_override CONFIGURATION_PATH
   

   Replace CONFIGURATION_PATH with the path to the credential configuration file.

   To stop using the credential configuration file by default for gcloud commands, unset the property with the following command:

   gcloud config unset auth/credential_file_override
   

   gcloud auth login

   Run the following command using the --cred-file flag:

   Linux and macOS

   gcloud auth login \
       --cred-file=CONFIGURATION_PATH
   

   Windows (PowerShell)

   gcloud auth login `
       --cred-file=CONFIGURATION_PATH
   

   Replace CONFIGURATION_PATH with the path to a credential configuration file.

   The gcloud auth login command stores access credentials in your home directory. The authenticated principal becomes the active principal in your active gcloud CLI configuration. Unless overridden, the gcloud CLI uses these stored credentials to access Cloud de Confiance by S3NS.

Service accounts

You can use the gcloud CLI with a service account in the following ways:

• On a resource that exposes a Compute Engine metadata server, such as a Compute Engine VM instance or Cloud Run service. The gcloud CLI uses whatever service account is attached to the resource to authenticate by default.

• By using another principal to impersonate a service account.

• By using a service account key.

Use the gcloud CLI with an access token

If you've already authenticated for the gcloud CLI on another device, you can obtain an access token for that device's active principal with the following command:

gcloud auth print-access-token

You can then use this access token on another device to access Cloud de Confiance by S3NS resources. Using an access token bypasses the need to set an active principal, and overrides any active principal set in the active gcloud CLI configuration.

Access tokens for user accounts have a default lifespan of one hour.

You can use an access token with the gcloud CLI for future commands, or only a single command.

Credentials priority

Because multiple authentication methods might be used in one environment, the gcloud CLI evaluates the methods in a specific order to determine which principal to use. The gcloud CLI starts with provided credentials, and then assesses if service account impersonation has been requested.

The order of evaluation for provided credentials is as follows:

1. The CLOUDSDK_AUTH_ACCESS_TOKEN environment variable, set to the access token string.

2. Access token files. The methods used to define the access token file paths are evaluated in the following order:

   1. The --access-token-file command-line flag, used with any gcloud CLI command.

   2. The CLOUDSDK_AUTH_ACCESS_TOKEN_FILE environment variable.

   3. The auth/access_token_file property in the active gcloud CLI configuration.

3. Credential files. The methods used to define the credential file paths are evaluated in the following order:

   1. The CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE environment variable.

   2. The auth/credential_file_override property in the active gcloud CLI configuration.

4. The active principal set by the gcloud auth login command, or by setting the core/account property.

Service account impersonation priority

If service account impersonation has been requested, the gcloud CLI checks which service account to impersonate after credentials have been provided for the principal that is doing the impersonation. The methods used to define service accounts for impersonation are evaluated in the following order:

1. The --impersonate-service-account command-line flag.

2. The CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT environment variable.

3. The service account defined by the auth/impersonate_service_account property in the active configuration.

Add the gcloud CLI as a credential helper to Docker

To pull from Artifact Registry container registries, you can add the gcloud CLI as a credential helper to your Docker configuration.

To do so, run the gcloud auth configure-docker command:

gcloud auth configure-docker REGION-docker.pkg.dev

Manage principals and credentials

You can use the gcloud auth login command to authenticate multiple principals in the same environment, and authorize the gcloud CLI to access resources on their behalf. However, only one principal can be active at any time. The following sections cover managing the principals in your gcloud CLI configuration, including listing them, switching between them, and revoking their credentials.

List principals

To list the principals whose access credentials are stored on the local system (that is, who have been authenticated using gcloud auth login), run the gcloud auth list command:

gcloud auth list

The gcloud CLI lists the principals and shows which principal is active:

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

Overrides for the active principal aren't included in this list. These include the following environment variables:

• CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
• CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

To check if these environment variables are set, run the following command for your operating system:

echo "$ENVIRONMENT_VARIABLE"

echo $env:ENVIRONMENT_VARIABLE

Replace ENVIRONMENT_VARIABLE with the environment variable you want to check.

Overrides for the active principal also include the following configuration properties:

• auth/credential_file_override
• auth/impersonate_service_account

To check if these configuration properties are set, run the following command:

gcloud config list

Switch active principals

To switch to an active principal that has stored credentials (that is, they previously completed the gcloud auth login flow), run gcloud config set:

gcloud config set account PRINCIPAL_IDENTIFIER

Replace PRINCIPAL_IDENTIFIER with the full identifier of the principal.

You can also switch principals in the following ways:

• Create a separate configuration that specifies a different active principal, and then activate that configuration.

• Use the --account command-line flag to specify a principal for a single command.

• Use an override like a command-line flag, an environment variable, or configuration property.

Set session lengths

Administrators 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 Cloud de Confiance services.

Revoke credentials for a principal

You can revoke credentials for principals who have authenticated with gcloud auth login so that the gcloud CLI can't act on their behalf. Revoking invalidates the credentials on Google's authorization servers, and removes the principal from the active gcloud CLI configuration.

To revoke credentials, run gcloud auth revoke:

gcloud auth revoke PRINCIPAL_IDENTIFIER

Replace PRINCIPAL_IDENTIFIER with the full identifier of the principal.

To revoke access for the gcloud CLI on all devices associated with your Google Account, go to Third-party apps & services in your Google Account settings, and delete all connections with the Google Cloud SDK.

Manage stored credentials

The gcloud CLI stores the credential files it uses in the gcloud CLI configuration directory. To find the location of the credential files, run gcloud info:

gcloud info

The gcloud CLI prints information about your installation. Credential files are stored in the User Config Directory defined in the output:

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

For Linux and macOS, the gcloud CLI configuration directory is typically /home/USERNAME/.config/gcloud. For Windows, it's %APPDATA%\gcloud.

What's next

• To learn more about customizing the gcloud CLI, see gcloud CLI properties.

• To learn more about managing named sets of gcloud CLI properties, see gcloud CLI configurations.

• To authenticate code-based workloads that use Cloud Client Libraries or Google API Client Libraries, see How Application Default Credentials works.