Autorizar la CLI de gcloud

Para poder acceder Google CloudNormalmente, tendrás que autorizar la CLI de Google Cloud. Esta página muestra las opciones de autorización disponibles y cómo administrar las cuentas que usas para la autorización. Si usas una instancia de Compute Engine o Cloud Shell, no es necesario autorizar la CLI de gcloud.

Tipos de cuentas

Para otorgar autorización a la CLI de gcloud para accederGoogle Cloud, puede utilizar una cuenta de usuario o una cuenta de servicio .

Una cuenta de usuario es una Google Cloud Cuenta que permite a los usuarios finales autenticarse en la aplicación. Para la mayoría de los casos de uso, especialmente al usar la CLI de gcloud de forma interactiva, se recomienda usar una cuenta de usuario.

Una cuenta de servicio es una Google Cloud cuenta asociada a suGoogle Cloud Proyecto, no un usuario específico. Puedes usar la cuenta de servicio integrada disponible al usar las funciones de Cloud Run, App Engine, Compute Engine o Google Kubernetes Engine. Se recomienda usar una cuenta de servicio para ejecutar scripts de la CLI de gcloud en varias máquinas.

Elija un tipo de autorización

Debe autorizar la CLI de Google Cloud para administrar Google Cloudrecursos. Tanto Google Cloud CLI como Google Cloud Utilice OAuth2 para autenticación y autorización.

Elija uno de los siguientes tipos de autorización:

Tipo Descripción
Cuenta de usuario Recomendado si está utilizando la CLI de gcloud desde la línea de comandos o está escribiendo scripts con la CLI de gcloud para usar en una sola máquina.
Cuenta de servicio Se recomienda si está instalando y configurando la CLI de gcloud como parte de un proceso de implementación de máquina en producción, o para usar en instancias de máquinas virtuales de Compute Engine donde todos los usuarios tienen acceso a root .

Para obtener más información sobre la autenticación y Google Cloud, consulte Descripción general de autenticación .

Autorizar con una cuenta de usuario

En esta sección se describe cómo autorizar con una cuenta de usuario.

Autenticación con una cuenta de Google

Utilice los siguientes comandos CLI de gcloud para autorizar el acceso con una cuenta de usuario:

Dominio Descripción
gcloud init Autoriza el acceso y realiza otros pasos de configuración comunes.
gcloud auth login Autoriza únicamente el acceso.

Durante la autorización, estos comandos obtienen las credenciales de la cuenta deGoogle Cloud y almacenarlas en el sistema local. La cuenta especificada se convierte en la cuenta activa en su configuración . La CLI de gcloud usa las credenciales almacenadas para acceder.Google CloudPuede tener cualquier cantidad de cuentas con credenciales almacenadas para una sola instalación de gcloud CLI, pero solo una cuenta está activa a la vez.

Ejecutar gcloud init

gcloud init autoriza el acceso y realiza otros pasos de configuración comunes . gcloud init utiliza un flujo de autorización basado en web para autenticar la cuenta de usuario y otorgar permisos de acceso.

Para autorizar el acceso y realizar otros pasos de configuración comunes:

  1. Ejecute gcloud init :

    gcloud init

    O bien, para evitar que el comando abra automáticamente un navegador web:

    gcloud init --console-only

    Usar la opción --console-only es útil si ejecuta el comando en un sistema remoto mediante ssh y no tiene acceso a un navegador en ese sistema. A continuación, debe abrir manualmente la URL proporcionada en un navegador de su sistema local para completar el proceso de autorización.

  2. Siga el flujo de autorización basado en el navegador para autenticar la cuenta y otorgar permisos de acceso.

Para obtener más información sobre gcloud init , consulte Inicialización de la CLI de gcloud .

Ejecutar gcloud auth login

Al ejecutar gcloud auth login se autoriza únicamente la cuenta de usuario. Para autorizar el acceso sin realizar otros pasos de configuración, utilice una de las siguientes opciones.

  • Si desea autorizar la CLI de gcloud en una máquina con un navegador, siga estos pasos.

    1. Autorizar la CLI de gcloud:

      gcloud auth login

    2. Siga el flujo de autorización basado en el navegador para autenticar la cuenta y otorgar permisos de acceso.

  • Si desea autorizar la CLI de gcloud en una máquina que no tiene un navegador y puede instalar la CLI de gcloud en otra máquina con un navegador, use el indicador --no-browser .

    1. Autorizar la CLI de gcloud:

      gcloud auth login --no-browser

    2. Copie el comando largo que comienza con gcloud auth login --remote-bootstrap=" .

    3. Pegue y ejecute este comando en la línea de comandos de una máquina diferente y confiable que tenga instalaciones locales de un navegador web y la herramienta CLI gcloud versión 372.0 o posterior.

    4. Copie la salida URL larga de la máquina con el navegador web.

    5. Pegue la URL larga en la primera máquina debajo del mensaje "Ingrese la salida del comando anterior" y presione Entrar para completar la autorización.

  • Si desea autorizar la CLI de gcloud en una máquina sin navegador y no puede instalarla en otra máquina con navegador, use el indicador --no --no-launch-browser --no-launch-browser . Este indicador impide que el comando abra automáticamente un navegador web.

    1. Autorizar la CLI de gcloud:

      gcloud auth login --no-launch-browser

    2. Copie la URL larga que comienza con https://accounts.google.com/o/oauth2/auth...

    3. Pegue esta URL en el navegador de una máquina diferente y confiable que tenga un navegador web.

    4. Copie el código de autorización de la máquina con el navegador web.

    5. Pegue el código de autorización en la primera máquina cuando aparezca el mensaje "Ingresar código de verificación" y presione Entrar para completar la autorización.

  • Si ya tiene un token de acceso, utilice uno de los siguientes métodos para pasar el token de acceso a la CLI de gcloud:

    • Almacene el token de acceso en un archivo y establezca su ruta a través del indicador --access-token-file .
    • Almacene el token de acceso en un archivo y establezca su ruta en la propiedad auth/access_token_file .
    • Establezca la variable de entorno CLOUDSDK_AUTH_ACCESS_TOKEN en el valor del token de acceso.

Autenticación con Workforce Identity Federation

Esta sección describe cómo iniciar sesión en la CLI de gcloud usando Workforce Identity Federation.

Inicio de sesión basado en navegador de la CLI de gcloud

Para iniciar sesión en la CLI de gcloud mediante un flujo de inicio de sesión basado en navegador, haga lo siguiente:

  1. Crear un archivo de configuración de inicio de sesión.

    Para crear el archivo de configuración de inicio de sesión, ejecute el siguiente comando. Opcionalmente, puede activar el archivo como predeterminado para la CLI de gcloud añadiendo el indicador --activate . A continuación, puede ejecutar gcloud auth login sin especificar la ruta del archivo de configuración cada vez.

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

    Reemplace lo siguiente:

    • WORKFORCE_POOL_ID : el identificador del grupo de fuerza laboral
    • PROVIDER_ID : el ID del proveedor
    • LOGIN_CONFIG_FILE_PATH : la ruta a un archivo de configuración que usted especifique, por ejemplo, login.json

    El archivo contiene los puntos finales que utiliza la CLI de gcloud para habilitar el flujo de autenticación basado en navegador y establecer la audiencia en el IdP configurado en el proveedor del grupo de identidades de la fuerza laboral. El archivo no contiene información confidencial.

    El resultado será similar al siguiente:

    {
  "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.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://googleapis.com/v1/introspect",
}

    Para evitar que gcloud auth login use este archivo de configuración automáticamente, puedes deshabilitarlo ejecutando gcloud config unset auth/login_config_file .

  2. Inicie sesión mediante la autenticación basada en navegador.

    Para autenticarse mediante la autenticación de inicio de sesión basada en navegador, puede utilizar uno de los siguientes métodos:

    • Si utilizó el indicador --activate cuando creó el archivo de configuración, o si activó el archivo de configuración con gcloud config set auth/login_config_file , la CLI de gcloud utiliza su archivo de configuración automáticamente:

      gcloud auth login

    • Para iniciar sesión especificando la ubicación del archivo de configuración, ejecute el siguiente comando: 

      gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
    • Para utilizar una variable de entorno para especificar la ubicación del archivo de configuración, establezca CLOUDSDK_AUTH_LOGIN_CONFIG_FILE en la ruta de configuración.

Para dejar de utilizar el archivo de configuración de inicio de sesión, haga lo siguiente:

  • Si utilizó el indicador --activate cuando creó el archivo de configuración, o si activó el archivo de configuración con gcloud config set auth/login_config_file , debe ejecutar el siguiente comando para desconfigurarlo: 

    gcloud config unset auth/login_config_file
  • Borre la variable de entorno CLOUDSDK_AUTH_LOGIN_CONFIG_FILE , si está configurada.

Inicio de sesión sin interfaz gráfica de usuario de gcloud CLI

Para iniciar sesión en gcloud CLI, utilizando un flujo sin interfaz gráfica, haga lo siguiente:

OIDC

  1. Inicie sesión con un usuario en su aplicación IdP y obtenga el token OIDC.

    Para obtener información sobre cómo obtener el token, consulte la documentación OIDC de su IdP.

  2. Guarde el token OIDC devuelto por IdP en una ubicación segura en su máquina local.

  3. Genere un archivo de configuración ejecutando el siguiente comando: 

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
    --credential-source-file="PATH_TO_OIDC_ID_TOKEN" \
    --workforce-pool-user-project="WORKFORCE_POOL_USER_PROJECT" \
    --output-file="config.json"

Reemplace lo siguiente:

  • WORKFORCE_POOL_ID : el identificador del grupo de fuerza laboral
  • PROVIDER_ID : el ID del proveedor
  • PATH_TO_OIDC_TOKEN : la ruta al archivo de credenciales del IdP de OIDC
  • WORKFORCE_POOL_USER_PROJECT : el número de proyecto asociado con el proyecto de usuario de los grupos de fuerza de trabajo

El director debe tener permiso serviceusage.services.use en este proyecto.

Cuando ejecuta el comando, se produce un archivo de configuración de IdP de OIDC con un formato similar al siguiente: 

{
  "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"
  }
}

SAML

  1. Inicie sesión con un usuario en su aplicación IdP y obtenga la afirmación SAML.

    Para obtener información sobre cómo obtener la afirmación SAML de su IdP, consulte la documentación SAML de su IdP.

  2. Guarde la respuesta SAML devuelta por IdP en una ubicación segura en su máquina local y luego almacene la ruta de la siguiente manera: 

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. Para generar un archivo de configuración, ejecute el siguiente comando: 

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:saml2" \
    --credential-source-file="SAML_ASSERTION_PATH"  \
    --workforce-pool-user-project="PROJECT_ID"  \
    --output-file="config.json"

    Reemplace lo siguiente:

    • WORKFORCE_PROVIDER_ID : el ID del proveedor de fuerza laboral que creó anteriormente en esta guía.
    • WORKFORCE_POOL_ID : el ID del grupo de fuerza de trabajo que creó anteriormente en esta guía.
    • SAML_ASSERTION_PATH : la ruta del archivo de aserción SAML.
    • PROJECT_ID : el ID del proyecto

    El archivo de configuración que se genera es similar al siguiente: 

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

Para iniciar sesión en gcloud mediante el intercambio de tokens, ejecute el siguiente comando: 

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

Luego, gcloud intercambia de forma transparente sus credenciales de IdP por credenciales temporales. Google Cloud tokens de acceso, lo que le permite realizar otras llamadas gcloud a Google Cloud.

La salida es similar a la siguiente: 

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

Para enumerar las cuentas acreditadas y su cuenta actualmente activa, ejecute el siguiente comando: 

gcloud auth list

Autorizar con una cuenta de servicio

El comando gcloud auth login permite autorizar el acceso a una cuenta de servicio mediante un archivo de credenciales almacenado en el sistema de archivos local. Esta credencial puede ser una credencial de usuario con permiso para suplantar la cuenta de servicio, un archivo de configuración de credenciales para Workload Identity Federation o una clave de cuenta de servicio.

Autorizar una cuenta de servicio mediante la suplantación de cuenta de servicio

Para autorizar a la CLI de gcloud a utilizar credenciales de cuenta de servicio suplantadas , haga lo siguiente:

  1. En el Google Cloud consola, vaya a la página Cuentas de servicio.

    Ir a Cuentas de servicio

  2. Elija una cuenta existente o cree una nueva cuenta haciendo clic en Crear cuenta de servicio .

  3. Para obtener el permiso necesario para suplantar una cuenta de servicio, solicite a su administrador que le otorgue el rol de IAM " Creador de tokens de cuenta de servicio" ( roles/iam.serviceAccountTokenCreator ) en la cuenta de servicio. Para obtener más información sobre cómo otorgar roles, consulte "Administrar el acceso a proyectos, carpetas y organizaciones" .

    Esta función predefinida contiene el permiso iam.serviceAccounts.getAccessToken , que es necesario para suplantar una cuenta de servicio.

    También es posible que puedas obtener este permiso con roles personalizados u otros roles predefinidos .

  4. Autorice la CLI de gcloud con su identidad de usuario ejecutando gcloud auth login .

  5. Para configurar la CLI de gcloud para usar la identidad y el acceso proporcionados por una cuenta de servicio de manera predeterminada, utilice el comando config de la CLI de gcloud : 

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. Para dejar de usar credenciales de cuenta de servicio suplantadas con la CLI de gcloud de manera predeterminada, desactive la marca con el comando config de la CLI de gcloud : 

    gcloud config unset auth/impersonate_service_account

Autorizar una cuenta de servicio mediante Workload Identity Federation

Para autorizar la CLI de gcloud con una cuenta de servicio usando credenciales externas de Workload Identity Federation, haga lo siguiente:

  1. En el Google Cloud consola, vaya a la página Cuentas de servicio.

    Ir a Cuentas de servicio

  2. Elija una cuenta existente o cree una nueva cuenta haciendo clic en Crear cuenta de servicio .

  3. Cree un archivo de configuración de credenciales para Workload Identity Federation siguiendo las instrucciones de su proveedor de identidad compatible.

  4. Para activar su cuenta de servicio, ejecute gcloud auth login con el indicador --cred-file : 

    gcloud auth login --cred-file=CONFIGURATION_FILE

    Reemplace CONFIGURATION_FILE con la ruta a un archivo de configuración de credenciales para Workload Identity Federation.

Autorizar una cuenta de servicio utilizando una clave de cuenta de servicio

Para autorizar la CLI de gcloud con una cuenta de servicio usando una clave de cuenta de servicio, haga lo siguiente:

  1. En el Google Cloud consola, vaya a la página Cuentas de servicio.

    Ir a Cuentas de servicio

  2. Elija una cuenta existente o cree una nueva cuenta haciendo clic en Crear cuenta de servicio .

  3. Para crear claves de cuenta de servicio, consulte las instrucciones de IAM para Crear una clave de cuenta de servicio .

  4. Para activar su cuenta de servicio, ejecute gcloud auth login con el indicador --cred-file : 

    gcloud auth login --cred-file=KEY_FILE

    Reemplace KEY_FILE con la ruta a un archivo de clave de cuenta de servicio.

Lista de cuentas

Para enumerar las cuentas cuyas credenciales están almacenadas en el sistema local, ejecute gcloud auth list : 

gcloud auth list

La CLI de gcloud enumera las cuentas y muestra qué cuenta está activa: 

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

Cambiar la cuenta activa

Para cambiar la cuenta activa, ejecute gcloud config set : 

gcloud config set account ACCOUNT

donde [ACCOUNT] es la dirección de correo electrónico completa de la cuenta.

También puedes cambiar de cuenta creando una configuración independiente que especifique las diferentes cuentas y alternando entre configuraciones: 

gcloud config configurations activate CONFIGURATION

Si desea cambiar la cuenta utilizada por la CLI de gcloud en cada invocación, anule la cuenta activa utilizando el indicador --account .

Establecer la duración de la sesión autorizada

Como administrador, puede controlar el tiempo que los distintos usuarios pueden acceder a la CLI de gcloud sin tener que volver a autenticarse. Por ejemplo, puede obligar a los usuarios con privilegios elevados a volver a autenticarse con más frecuencia que los usuarios normales.

Para obtener más información, consulte Establecer la duración de la sesión para Google Cloud servicios .

Revocar credenciales para una cuenta

Puedes revocar las credenciales cuando quieras impedir el acceso a la CLI de gcloud a una cuenta específica. No es necesario revocarlas para cambiar de cuenta.

Para revocar las credenciales, ejecute gcloud auth revoke : 

gcloud auth revoke ACCOUNT

Para revocar todo acceso a la CLI de gcloud para todas las máquinas, elimine la CLI de gcloud de la lista de aplicaciones que tienen acceso a su cuenta .

Trabajar con archivos de credenciales

Encuentra tus archivos de credenciales

Para encontrar la ubicación de sus archivos de credenciales, ejecute gcloud info : 

gcloud info

La CLI de gcloud imprime información sobre la instalación. Los archivos de credenciales se almacenan en el directorio de configuración del usuario: 

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

Configurar las credenciales predeterminadas de la aplicación

La CLI de gcloud permite administrar las Credenciales Predeterminadas de la Aplicación (ADC) con el grupo de comandos gcloud auth application-default . Para que las credenciales de usuario estén disponibles para el ADC, ejecute gcloud auth application-default login : 

gcloud auth application-default login

La CLI de gcloud no utiliza estas credenciales. Para más información sobre cómo configurar ADC, consulte Configurar las credenciales predeterminadas de la aplicación .

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

¿Qué sigue?