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 a través de un flujo de autenticación, configura una configuración de gcloud CLI 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: Adecuado para que los humanos lo usen 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. Gcloud CLI usa estas credenciales almacenadas para autenticarse automáticamente en 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 la 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 de la gcloud CLI para que actúe en tu nombre 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 la 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. La gcloud CLI se autentica con la cuenta de servicio adjunta a la VM y puede 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 que se utilizan para que las personas realicen trabajos interactivos, como tareas administrativas incidentales, configuración no programática de servicios de Google Cloud , pruebas, experimentos 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:

  • Federación de identidades de personal: Permite que los usuarios humanos accedan a Google Cloud con identidades administradas por un proveedor de identidad externo. Si tu organización ya configuró el inicio de sesión único (SSO), puedes usar este tipo de identidad para autenticarte en Google Cloud.

    Tu proveedor de identidad debe admitir OpenID Connect (OIDC) o SAML 2.0 para usar la federación de identidades de personal.

  • Federación de identidades para cargas de trabajo: Permite que las cargas de trabajo que se ejecutan fuera de Google Cloud operen en recursos de Google Cloud .

    Puedes usar la federación de identidades para cargas de trabajo con cargas de trabajo que se autentican con certificados de cliente X.509, que se ejecutan en Amazon Web Services (AWS) o Azure, en Active Directory locales, en servicios de implementación, como GitHub y GitLab, y con cualquier proveedor de identidad que admita OpenID Connect (OIDC) o Security Assertion Markup Language (SAML) V2.0.

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 la gcloud CLI depende de si hay un navegador web instalado en tu dispositivo.

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