Autentícate en gcloud CLI

Este documento solo trata sobre la autenticación de Google Cloud CLI para acceder a los recursos deGoogle Cloud . Si necesitas autenticar cargas de trabajo con las bibliotecas cliente de Cloud o las bibliotecas cliente de las APIs de Google, consulta Cómo funcionan las credenciales predeterminadas de la aplicación.

Antes de comenzar

Si no conoces Google Cloud y solo quieres comenzar a usar los comandos de gcloud CLI en tu entorno de desarrollo local, puedes inicializar la CLI de gcloud con el siguiente comando:

gcloud init

La inicialización te guía por un flujo de autenticación, configura una configuración de la CLI de gcloud y autoriza a gcloud CLI a actuar en tu nombre. No es necesario realizar un paso de autenticación independiente.

En el resto de este documento, se abordan situaciones más complejas, como el uso de gcloud CLI con diferentes tipos de principales, los métodos de autenticación adecuados para diferentes entornos, el cambio de principales y la administración de credenciales almacenadas.

Métodos de autenticación

Todos los comandos de gcloud CLI deben autenticarse en las APIs de Google Cloud. Puedes autenticarte de las siguientes maneras:

  • Autoriza y almacena credenciales: Es adecuado para que los usuarios lo utilicen en un entorno de desarrollo local. Puedes autorizar a gcloud CLI para que actúe en nombre de una principal con el comando gcloud auth login. Después de la autenticación inicial, este comando almacena las credenciales en el directorio de configuración de gcloud CLI. La gcloud CLI usa estas credenciales almacenadas para autenticarse automáticamente para los comandos posteriores hasta que venza tu sesión o revoques la autorización.

  • Autenticación con un archivo de credenciales: Adecuado para cargas de trabajo que se ejecutan fuera de Google Cloud. Puedes usar variables de entorno o propiedades de configuración de la gcloud CLI para especificar un archivo de credenciales para la autenticación automática. Este archivo puede ser uno de los siguientes:

    • Un archivo de configuración de credenciales de la federación de identidades para cargas de trabajo

    • Una clave de cuenta de servicio

  • Proporciona un token de acceso: Adecuado para flujos de trabajo automatizados altamente aislados o sesiones sin estado en máquinas compartidas. Puedes omitir el almacenamiento de credenciales si proporcionas un token de acceso directamente a gcloud CLI. Para ello, puedes configurar una variable de entorno específica en la cadena del token de acceso sin procesar o hacer que gcloud CLI apunte a un archivo que contenga el token de acceso.

Después de la autenticación, puedes permitir que la gcloud CLI use la identidad de una cuenta de servicio proporcionando la dirección de correo electrónico de la cuenta de servicio.

Puedes usar varios métodos de autenticación en un solo entorno. Sin embargo, solo se usa una principal para cualquier comando gcloud determinado. Para determinar qué principal usar, gcloud CLI sigue un orden de prioridad.

Cuándo no necesitas autenticarte

No necesitas autenticarte en la gcloud CLI en las siguientes situaciones:

  • Inmediatamente después de inicializar la CLI de gcloud La autenticación y la autorización se incluyen en el proceso de inicialización. Es posible que debas volver a autenticarte si necesitas acceder a diferentes recursos con un principal diferente o si necesitas volver a autenticar tu principal.
  • Cuando usas gcloud CLI desde un recurso que expone un servidor de metadatos de Compute Engine. Esto incluye recursos como instancias de VM de Compute Engine, servicios de Cloud Run y compilaciones de Cloud Build. Gcloud CLI se autentica con la cuenta de servicio adjunta a la VM y está autorizada para acceder a los mismos recursos que esa cuenta de servicio dentro de los límites de los permisos de acceso que se hayan aplicado.
  • Cuando se usa Cloud Shell La gcloud CLI se autentica automáticamente con la entidad con la que accediste a la consola de Google Cloud . Cuando ejecutas un comando de gcloud CLI por primera vez en una nueva sesión de Cloud Shell, se te solicita que autorices Cloud Shell con esa principal.

Elige la principal adecuada para la tarea

Existen diferentes tipos de principales para el uso humano y las cargas de trabajo automatizadas. El tipo de principal que necesitas usar afecta la forma en que te autenticas.

  • Cuentas de usuario: Son Cuentas de Google para que las personas realicen trabajos interactivos, como tareas administrativas incidentales, configuración no programática de servicios de Google Cloud , pruebas, experimentación y observabilidad.

    Te autenticas como una cuenta de usuario con credenciales de usuario, como una contraseña y un código de un solo uso.

  • Cuentas de servicio: Son cuentas específicas de Google Cloud que las cargas de trabajo pueden usar para acceder a servicios o recursos. Por lo general, no te autenticas directamente como una cuenta de servicio. En su lugar, adjunta una cuenta de servicio a un recurso, como una VM de Compute Engine, o usa la identidad temporal como cuenta de servicio.

  • Principales federadas: Son identidades que hacen referencia a cuentas de usuario o de servicio en un proveedor de identidad externo. Google Cloudadmite dos tipos de principales federados, que tienen nombres similares:

Usa gcloud CLI como un humano

Para las tareas interactivas, por lo general, te autenticas con una de las siguientes opciones:

  • Una cuenta de usuario

  • Una identidad de usuario federada, que usa la federación de identidades de personal

Cuentas de usuario

La forma en la que te autenticas con una cuenta de usuario para gcloud CLI depende de si hay un navegador web instalado en tu dispositivo.

Mi dispositivo tiene un navegador web

Para autenticarte con una cuenta de usuario en un dispositivo con un navegador web, completa los siguientes pasos:

  1. Ejecuta el siguiente comando para iniciar el proceso:

    gcloud auth login

  2. Sigue el flujo basado en el navegador para autenticar y autorizar la gcloud CLI a acceder a los recursos en tu nombre para futuros comandos.

El comando gcloud auth login almacena las credenciales de acceso en tu directorio principal. La principal autenticada se convierte en la principal activa en tu configuración activa de gcloud CLI. A menos que se anulen, la gcloud CLI usa estas credenciales almacenadas para acceder a Google Cloud.

Mi dispositivo no tiene un navegador web

Si el dispositivo en el que necesitas usar la gcloud CLI no tiene un navegador web, puedes autenticarte con tu cuenta de usuario en otro dispositivo de confianza. Este proceso cambia según el software instalado en el otro dispositivo de confianza.

Autentícate con otro dispositivo de confianza

Selecciona qué software está disponible en el otro dispositivo de confianza.

Gcloud CLI y un navegador web

Usa la marca --no-browser para completar el proceso de autenticación en otro dispositivo con un navegador web y la gcloud CLI instalada:

  1. Ejecuta el siguiente comando en el dispositivo original en el que deseas usar gcloud CLI:

    Linux y macOS 

    gcloud auth login \
    --no-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-browser

  2. Copia el comando gcloud que comienza con gcloud auth login --remote-bootstrap=" para usarlo en el otro dispositivo.

  3. Ve a otro dispositivo de confianza que tenga un navegador web y la versión 372.0.0 de gcloud CLI o una posterior instalada.

  4. En la terminal, ejecuta el comando que copiaste antes y que comienza con gcloud auth login --remote-bootstrap=", y completa el flujo basado en el navegador.

  5. En la terminal, copia la URL que comienza con https://localhost para usarla en el dispositivo original.

  6. Regresa al dispositivo original.

  7. En la terminal, en el mensaje, pega la URL https://localhost que copiaste antes. Presiona Intro o Retorno en el teclado para completar el proceso.

El comando gcloud auth login almacena las credenciales de acceso en tu directorio principal. La principal autenticada se convierte en la principal activa en tu configuración activa de gcloud CLI. A menos que se anulen, gcloud CLI usa estas credenciales almacenadas para acceder a Google Cloud.

Solo en el navegador web

Usa la marca --no-launch-browser para completar el proceso de autenticación con el navegador web de otro dispositivo:

  1. Ejecuta el siguiente comando en el dispositivo original en el que deseas usar gcloud CLI:

    Linux y macOS 

    gcloud auth login \
    --no-launch-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-launch-browser

  2. Copia la URL que comienza con https://accounts.google.com/o/oauth2/auth para usarla en el otro dispositivo.

  3. Ve a otro dispositivo de confianza que tenga instalado un navegador web.

  4. Abre un navegador web, ve a la URL que copiaste antes y completa el flujo basado en el navegador.

  5. Copia el código de verificación para usarlo en el dispositivo original.

  6. Regresa al dispositivo original.

  7. En la terminal, en el mensaje, pega el código de verificación que copiaste antes. Presiona Intro o Volver en el teclado para completar el proceso.

El comando gcloud auth login almacena las credenciales de acceso en tu directorio principal. La principal autenticada se convierte en la principal activa en tu configuración activa de gcloud CLI. A menos que se anulen, la gcloud CLI usa estas credenciales almacenadas para acceder a Google Cloud.

Identidades de usuario federadas

Puedes usar la gcloud CLI con una identidad de usuario federada que se administra en un proveedor de identidad (IdP) externo. Esto se hace con la federación de identidades de personal.

En las siguientes instrucciones, se supone que ya tienes un grupo y un proveedor de federación de identidades de personal configurados para trabajar con tu IdP.

Para usar gcloud CLI con una identidad de usuario federada, crea un archivo de configuración de acceso y, luego, accede con un flujo basado en el navegador:

  1. Ejecuta el siguiente comando para crear un archivo de configuración de acceso:

    Linux y 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

    Reemplaza lo siguiente:

    • WORKFORCE_POOL_ID: Es el ID del grupo de federación de identidades de personal.
    • WORKFORCE_PROVIDER_ID: Es el ID del proveedor de la federación de identidades de personal.
    • LOGIN_CONFIG_PATH: Es la ruta de acceso en la que se escribirá el archivo de configuración de acceso. Por ejemplo, login-config.json

    El archivo de configuración de acceso contiene los extremos que usa la gcloud CLI para habilitar el flujo de autenticación basado en el navegador y establecer el público en el IdP que se configuró en el proveedor del grupo de identidades de personal. El archivo no contiene información confidencial.

    El contenido del archivo de configuración de acceso se ve de la siguiente manera:

    {
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "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://sts.googleapis.com/v1/introspect"
}

  2. Apunta al archivo de configuración de acceso con una variable de entorno, una propiedad en la configuración activa de la gcloud CLI o úsalo directamente con el comando gcloud auth login:

    Variable de entorno

    Para usar el archivo de configuración de acceso con una variable de entorno, completa las siguientes instrucciones:

    1. Establece la variable de entorno CLOUDSDK_AUTH_LOGIN_CONFIG_FILE en la ruta de acceso del archivo de configuración de acceso.

    2. Ejecuta el comando siguiente:

      gcloud auth login
    3. Gcloud CLI hace referencia a la variable de entorno para encontrar el archivo de configuración de acceso y, luego, inicia el proceso de autenticación. Sigue el flujo basado en el navegador para autenticar y autorizar gcloud CLI a acceder a los recursos en tu nombre para futuros comandos.

    Para dejar de usar el archivo de configuración de acceso para los comandos gcloud auth login, borra la variable de entorno CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

    Configuración de gcloud CLI

    Para usar el archivo de configuración de acceso con una propiedad de configuración de gcloud CLI, completa las siguientes instrucciones:

    1. Establece la propiedad auth/login_config_file de la configuración activa de la gcloud CLI en la ruta de acceso del archivo de configuración de acceso con el siguiente comando: 

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

    2. Ejecuta el comando siguiente:

      gcloud auth login
    3. Gcloud CLI hace referencia a la propiedad de configuración para encontrar el archivo de configuración de acceso y, luego, inicia el proceso de autenticación. Sigue el flujo basado en el navegador para autenticar y autorizar gcloud CLI a acceder a los recursos en tu nombre para futuros comandos.

    Para dejar de usar el archivo de configuración de acceso para los comandos de gcloud auth login, anula la configuración de la propiedad con el siguiente comando: 

    gcloud config unset auth/login_config_file

    gcloud auth login

    Para usar el archivo de configuración de acceso directamente con el comando gcloud auth login, sigue estas instrucciones:

    • Si usaste la marca --activate cuando creaste el archivo de configuración de acceso, ejecuta el siguiente comando: 

      gcloud auth login

    • Si no usaste la marca --activate cuando creaste el archivo de configuración de acceso, ejecuta el siguiente comando:

      Linux y macOS

      gcloud auth login \
    --login-config=LOGIN_CONFIG_PATH

      Windows (PowerShell)

      gcloud auth login `
    --login-config=LOGIN_CONFIG_PATH

      Reemplaza LOGIN_CONFIG_PATH por la ruta de acceso del archivo de configuración de acceso.

    El comando gcloud auth login almacena las credenciales de acceso en tu directorio principal. La principal autenticada se convierte en la principal activa en tu configuración activa de gcloud CLI. A menos que se anulen, gcloud CLI usa estas credenciales almacenadas para acceder a Google Cloud.

Usa gcloud CLI con cargas de trabajo

Para las cargas de trabajo automatizadas, por lo general, te autenticas con una de las siguientes opciones:

  • Una identidad para cargas de trabajo federada, que usa la federación de identidades para cargas de trabajo

  • Una cuenta de servicio que usa la identidad temporal

Identidades federadas para cargas de trabajo

Puedes usar la gcloud CLI con una identidad para cargas de trabajo federada. Esto se hace con la federación de identidades para cargas de trabajo.

Una carga de trabajo puede acceder a los recursos Google Cloud directamente actuando como una principal definida por un grupo de identidades para cargas de trabajo o suplantar la identidad de una cuenta de servicio adjunta a un grupo de identidades para cargas de trabajo.

Te recomendamos que uses el método de acceso directo para evitar cuentas de servicio con permisos excesivos y registrar el acceso a los recursos con el identificador de la principal federada. Solo usa la identidad temporal de la cuenta de servicio cuando las APIs deGoogle Cloud no admitan la federación de identidades para cargas de trabajo.

En las siguientes instrucciones, se supone que ya tienes un grupo y un proveedor de federación de identidades para cargas de trabajo configurados para trabajar con tu IdP.

  1. Crea un archivo de configuración de credenciales para la federación de identidades para cargas de trabajo siguiendo las instrucciones de tu proveedor de identidad compatible.

  2. Define la ruta de acceso al archivo de configuración de credenciales en una variable de entorno, como una propiedad en la configuración activa de la gcloud CLI o con el comando gcloud auth login:

    Variable de entorno

    Establece la variable de entorno CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE en la ruta de acceso al archivo de configuración de credenciales. Gcloud CLI hace referencia al archivo cada vez que ejecuta un comando y obtiene una credencial de tu IdP. Esta credencial se intercambia por un token de acceso a Google Cloud.

    Para dejar de usar el archivo de configuración de credenciales, borra la variable de entorno CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    Configuración de gcloud CLI

    Establece la propiedad auth/credential_file_override de la configuración activa de la gcloud CLI en la ruta del archivo de configuración de credenciales con el siguiente comando:

    gcloud config set auth/credential_file_override CONFIGURATION_PATH

    Reemplaza CONFIGURATION_PATH por la ruta de acceso al archivo de configuración de credenciales.

    Para dejar de usar el archivo de configuración de credenciales de forma predeterminada para los comandos de gcloud, anula la configuración de la propiedad con el siguiente comando:

    gcloud config unset auth/credential_file_override

    gcloud auth login

    Ejecuta el siguiente comando con la marca --cred-file:

    Linux y macOS 

    gcloud auth login \
    --cred-file=CONFIGURATION_PATH

    Windows (PowerShell) 

    gcloud auth login `
    --cred-file=CONFIGURATION_PATH

    Reemplaza CONFIGURATION_PATH por la ruta de acceso a un archivo de configuración de credenciales.

    El comando gcloud auth login almacena las credenciales de acceso en tu directorio principal. La principal autenticada se convierte en la principal activa en tu configuración activa de gcloud CLI. A menos que se anulen, gcloud CLI usa estas credenciales almacenadas para acceder a Google Cloud.

Cuentas de servicio

Puedes usar gcloud CLI con una cuenta de servicio de las siguientes maneras:

  • En un recurso que expone un servidor de metadatos de Compute Engine, como una instancia de VM de Compute Engine o un servicio de Cloud Run De forma predeterminada, gcloud CLI usa cualquier cuenta de servicio conectada al recurso para la autenticación.

  • Usando otra principal para suplantar una cuenta de servicio

  • Usando una clave de cuenta de servicio

Identidad temporal como cuenta de servicio

Para el acceso a recursos que, por lo general, no están disponibles para tu entidad, te recomendamos que administres la elevación de privilegios con Privileged Access Manager en lugar de usar la identidad temporal como cuenta de servicio.

Si Privileged Access Manager no se ajusta a tu caso de uso, completa los siguientes pasos para usar la gcloud CLI con una cuenta de servicio:

  1. Para actuar en nombre de una cuenta de servicio, asegúrate de que la API de Service Account Credentials esté habilitada en tu proyecto.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la API

  2. Elige una principal para suplantar una cuenta de servicio.

  3. Para garantizar que la principal tenga el permiso necesario para suplantar la identidad de una cuenta de servicio, pídele a tu administrador que le otorgue el rol de IAM Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) a la principal en la cuenta de servicio. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    Este rol predefinido contiene el permiso iam.serviceAccounts.getAccessToken, que se requiere para usar la identidad de otra cuenta de servicio.

    Es posible que tu administrador también pueda otorgar este permiso a la cuenta principal con roles personalizados o con otros roles predefinidos.

  4. Autentica la gcloud CLI con la entidad principal que elegiste antes, ya sea una cuenta de usuario, identidad de usuario federada, identidad de carga de trabajo federada o cualquier otra cuenta de servicio.

  5. Elige una cuenta de servicio para suplantar. Busca una cuenta de servicio existente o crea una nueva.

  6. Copia la dirección de correo electrónico de la cuenta de servicio.

  7. Elige si deseas suplantar la identidad de la cuenta de servicio para todos los comandos o solo para uno:

    Todos los comandos

    Para usar la identidad temporal como cuenta de servicio con gcloud CLI en comandos futuros, puedes establecer una variable de entorno o una propiedad en la configuración activa de gcloud CLI:

    • Variable de entorno: Establece la variable de entorno CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT en la dirección de correo electrónico de la cuenta de servicio.

      Para dejar de usar la cuenta de servicio, borra la variable de entorno CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

    • Configuración de la CLI de gcloud: Establece la propiedad auth/impersonate_service_account de la configuración activa de gcloud CLI con el siguiente comando:

      gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL

      Reemplaza SERVICE_ACCOUNT_EMAIL por la dirección de correo electrónico de la cuenta de servicio.

      Para dejar de usar la identidad temporal como cuenta de servicio de forma predeterminada para los comandos de gcloud, anula la configuración de la propiedad con el siguiente comando:

      gcloud config unset auth/impersonate_service_account

    Un solo comando

    Para usar la identidad temporal como cuenta de servicio con gcloud CLI para un solo comando, puedes agregar la marca --impersonate-service-account a un comando de servicio de gcloud CLI.

    Por ejemplo, para enumerar las instancias de VM de Compute Engine con la identidad temporal como cuenta de servicio, ejecuta el siguiente comando:

    Linux y macOS 

    gcloud compute instances list \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Windows (PowerShell) 

    gcloud compute instances list `
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Reemplaza SERVICE_ACCOUNT_EMAIL por la dirección de correo electrónico de la cuenta de servicio.

Clave de cuenta de servicio

Te recomendamos que uses la federación de identidades para cargas de trabajo para la mayoría de las cargas de trabajo que se ejecutan fuera de Google Cloud. Solo usa claves de cuentas de servicio si tu carga de trabajo se ejecuta en un entorno externo aislado que no admite la federación de identidades para cargas de trabajo.

La federación de identidades para cargas de trabajo ofrece las siguientes ventajas:

  • El acceso a los recursos se otorga a través de Identity and Access Management (IAM), y las cargas de trabajo se tratan como principales individuales. Esto significa que no necesitas otorgar permisos excesivos a una cuenta de servicio para varios casos de uso.

  • Puedes auditar qué carga de trabajo realiza qué tarea; las acciones no se ocultan detrás de una dirección de correo electrónico de cuenta de servicio.

  • La federación de identidades para cargas de trabajo usa tokens de acceso de corta duración para reducir el riesgo de exfiltración. Las claves de cuentas de servicio no vencen, a menos que se revoquen manualmente.

Para usar una cuenta de servicio con gcloud CLI en comandos futuros, haz lo siguiente:

  1. Crea una clave de cuenta de servicio y almacénala como un archivo en una ubicación segura de tu entorno.

  2. Define la ruta de acceso al archivo de claves de la cuenta de servicio en una variable de entorno, como una propiedad en la configuración activa de la gcloud CLI o con el comando gcloud auth login:

    • Variable de entorno: Establece la variable de entorno CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE en la ruta de acceso al archivo de claves de la cuenta de servicio.

      Para dejar de usar la clave de la cuenta de servicio, borra la variable de entorno CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    • Configuración de gcloud CLI: Establece la propiedad auth/credential_file_override de la configuración activa de gcloud CLI en la ruta de acceso de la clave de la cuenta de servicio con el siguiente comando:

      gcloud config set auth/credential_file_override KEY_PATH

      Reemplaza KEY_PATH por la ruta de acceso al archivo de claves de la cuenta de servicio.

      Para dejar de usar la clave de la cuenta de servicio de forma predeterminada para los comandos de gcloud, anula la configuración de la propiedad con el siguiente comando:

      gcloud config unset auth/credential_file_override

    • gcloud auth login: Ejecuta el siguiente comando con la marca --cred-file:

      Linux y macOS 

      gcloud auth login \
    --cred-file=KEY_PATH

      Windows (PowerShell) 

      gcloud auth login `
    --cred-file=KEY_PATH

      Reemplaza KEY_PATH por la ruta de acceso al archivo de claves de la cuenta de servicio.

      El comando gcloud auth login almacena las credenciales de acceso en tu directorio principal. La principal autenticada se convierte en la principal activa en tu configuración activa de gcloud CLI. A menos que se anulen, la gcloud CLI usa estas credenciales almacenadas para acceder a Google Cloud.

Usa gcloud CLI con un token de acceso

Si ya te autenticaste en la gcloud CLI en otro dispositivo, puedes obtener un token de acceso para la entidad activa de ese dispositivo con el siguiente comando:

gcloud auth print-access-token

Luego, puedes usar este token de acceso en otro dispositivo para acceder a los recursos de Google Cloud. El uso de un token de acceso evita la necesidad de establecer un principal activo y anula cualquier principal activo establecido en la configuración activa de gcloud CLI.

Los tokens de acceso para las cuentas de usuario tienen una vida útil predeterminada de una hora.

Puedes usar un token de acceso con gcloud CLI para comandos futuros o solo para un comando.

Todos los comandos

Para usar un token de acceso con gcloud CLI en comandos futuros, puedes establecer una variable de entorno o una propiedad en la configuración activa de gcloud CLI:

  • Variable de entorno: Establece la variable de entorno CLOUDSDK_AUTH_ACCESS_TOKEN en la cadena del token de acceso.

    Para dejar de usar el token de acceso, borra la variable de entorno CLOUDSDK_AUTH_ACCESS_TOKEN.

  • Configuración de la CLI de gcloud: Almacena el token de acceso en un archivo y, luego, establece la propiedad auth/access_token_file de la configuración activa de gcloud CLI en la ruta de acceso del archivo con el siguiente comando:

    gcloud config set auth/access_token_file ACCESS_TOKEN_PATH

    Reemplaza ACCESS_TOKEN_PATH por la ruta de acceso al archivo del token de acceso.

    Para dejar de usar un token de acceso de forma predeterminada para los comandos de gcloud, anula la configuración de la propiedad con el siguiente comando:

    gcloud config unset auth/access_token_file

Un solo comando

Para usar un token de acceso con gcloud CLI para un solo comando, puedes agregar la marca --access-token-file a un comando de servicio de gcloud CLI:

  1. Almacena el token de acceso en un archivo.

  2. Usa la marca --access-token-file con cualquier comando de servicio gcloud.

    Por ejemplo, para enumerar instancias de VM de Compute Engine con un token de acceso, ejecuta el siguiente comando:

    Linux y macOS 

    gcloud compute instances list \
    --access-token-file ACCESS_TOKEN_PATH

    Windows (PowerShell) 

    gcloud compute instances list `
    --access-token-file ACCESS_TOKEN_PATH

    Reemplaza ACCESS_TOKEN_PATH por la ruta de acceso al archivo del token de acceso.

Prioridad de las credenciales

Dado que es posible que se usen varios métodos de autenticación en un mismo entorno, gcloud CLI evalúa los métodos en un orden específico para determinar qué entidad usar. La gcloud CLI comienza con las credenciales proporcionadas y, luego, evalúa si se solicitó la identidad temporal como cuenta de servicio.

El orden de evaluación de las credenciales proporcionadas es el siguiente:

  1. La variable de entorno CLOUDSDK_AUTH_ACCESS_TOKEN, establecida en la cadena del token de acceso.

  2. Son los archivos de tokens de acceso. Los métodos que se usan para definir las rutas de acceso a los archivos de tokens de acceso se evalúan en el siguiente orden:

    1. La marca de línea de comandos --access-token-file, que se usa con cualquier comando de gcloud CLI

    2. Es la variable de entorno CLOUDSDK_AUTH_ACCESS_TOKEN_FILE.

    3. La propiedad auth/access_token_file en la configuración activa de gcloud CLI

  3. Archivos de credenciales Los métodos que se usan para definir las rutas de acceso a los archivos de credenciales se evalúan en el siguiente orden:

    1. Es la variable de entorno CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    2. La propiedad auth/credential_file_override en la configuración activa de gcloud CLI

  4. Es el principal activo establecido por el comando gcloud auth login o por la configuración de la propiedad core/account.

Prioridad de la identidad temporal como cuenta de servicio

Si se solicitó la suplantación de identidad de la cuenta de servicio, gcloud CLI verifica qué cuenta de servicio suplantar después de que se proporcionaron las credenciales para la principal que realiza la suplantación de identidad. Los métodos que se usan para definir las cuentas de servicio para la suplantación se evalúan en el siguiente orden:

  1. La marca de línea de comandos --impersonate-service-account

  2. Es la variable de entorno CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

  3. Es la cuenta de servicio definida por la propiedad auth/impersonate_service_account en la configuración activa.

Agrega Google Drive a tu alcance

El alcance de gcloud CLI se puede expandir para incluir el acceso a Google Drive, además de Google Cloud. Esto significa que puedes usar Google Cloud tokens de acceso con Google Drive.

Para expandir el alcance y que incluya Google Drive, agrega la marca --enable-gdrive-access cuando autorices gcloud CLI:

Linux y macOS 

gcloud auth login \
    --enable-gdrive-access

Windows (PowerShell) 

gcloud auth login `
    --enable-gdrive-access

Luego, puedes realizar llamadas a las APIs de Google Drive con la gcloud CLI para proporcionar un token de acceso. Por ejemplo, para enumerar todos los archivos de tu unidad de Google Drive, puedes realizar la siguiente solicitud:

Linux y macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

Luego, por ejemplo, puedes usar un ID de archivo de la respuesta del comando anterior para extraer texto de un archivo de Documentos de Google:

Linux y macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Un caso de uso común para el acceso a Google Drive es usar BigQuery con datos almacenados en Hojas de cálculo de Google.

Para obtener más información sobre la API de Google Drive, consulta la descripción general de la API de Google Drive.

Agrega gcloud CLI como auxiliar de credenciales a Docker

Para extraer contenido de los registros de contenedores de Artifact Registry, puedes agregar gcloud CLI como auxiliar de credenciales a tu configuración de Docker.

Para ello, ejecuta el comando gcloud auth configure-docker:

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

Administra entidades y credenciales

Puedes usar el comando gcloud auth login para autenticar varias entidades principales en el mismo entorno y autorizar a gcloud CLI a acceder a los recursos en su nombre. Sin embargo, solo un principal puede estar activo en cualquier momento. En las siguientes secciones, se explica cómo administrar las entidades principales en la configuración de gcloud CLI, lo que incluye cómo enumerarlas, cambiar entre ellas y revocar sus credenciales.

Enumera principales

Para enumerar las entidades principales cuyas credenciales de acceso están almacenadas en el sistema local (es decir, que se autenticaron con gcloud auth login), ejecuta el comando gcloud auth list:

gcloud auth list

Gcloud CLI enumera las entidades principales y muestra qué entidad principal está activa:

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

Los reemplazos para el principal activo no se incluyen en esta lista. Estas incluyen las siguientes variables de entorno:

  • CLOUDSDK_AUTH_ACCESS_TOKEN
  • CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
  • CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

Para verificar si estas variables de entorno están configuradas, ejecuta el siguiente comando para tu sistema operativo:

Linux y macOS 

echo "$ENVIRONMENT_VARIABLE"

Windows (PowerShell) 

echo $env:ENVIRONMENT_VARIABLE

Reemplaza ENVIRONMENT_VARIABLE por la variable de entorno que deseas verificar.

Las anulaciones para el principal activo también incluyen las siguientes propiedades de configuración:

  • auth/access_token_file
  • auth/credential_file_override
  • auth/impersonate_service_account

Para verificar si se establecieron estas propiedades de configuración, ejecuta el siguiente comando:

gcloud config list

Cambiar principales activos

Para cambiar a una principal activa que tenga credenciales almacenadas (es decir, que haya completado el flujo de gcloud auth login anteriormente), ejecuta gcloud config set:

gcloud config set account PRINCIPAL_IDENTIFIER

Reemplaza PRINCIPAL_IDENTIFIER por el identificador completo de la principal.

También puedes cambiar de principal de las siguientes maneras:

Cómo establecer la duración de las sesiones

Los administradores pueden controlar durante cuánto tiempo pueden acceder los diferentes usuarios a gcloud CLI sin tener que volver a autenticarse. Por ejemplo, puedes obligar a los usuarios con privilegios elevados a que vuelvan a autenticarse con más frecuencia que los usuarios normales.

Para obtener más información, consulta Cómo establecer la duración de la sesión para los servicios de Google Cloud .

Revoca las credenciales de una principal

Puedes revocar las credenciales de los principales que se autenticaron con gcloud auth login para que gcloud CLI no pueda actuar en su nombre. La revocación invalida las credenciales en los servidores de autorización de Google y quita al principal de la configuración activa de gcloud CLI.

Para revocar credenciales, ejecuta: gcloud auth revoke:

gcloud auth revoke PRINCIPAL_IDENTIFIER

Reemplaza PRINCIPAL_IDENTIFIER por el identificador completo de la principal.

Para revocar el acceso a gcloud CLI en todos los dispositivos asociados a tu Cuenta de Google, ve a Apps y servicios de terceros en la configuración de tu Cuenta de Google y borra todas las conexiones con el SDK de Google Cloud.

Administra las credenciales almacenadas

Gcloud CLI almacena los archivos de credenciales que usa en el directorio de configuración de gcloud CLI. Para encontrar la ubicación de los archivos de credenciales, ejecuta gcloud info:

gcloud info

La gcloud CLI imprime información sobre tu instalación. Los archivos de credenciales se almacenan en el Directorio de configuración del usuario definido en el resultado:

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

En Linux y macOS, el directorio de configuración de gcloud CLI suele ser /home/USERNAME/.config/gcloud. En Windows, es %APPDATA%\gcloud.

¿Qué sigue?