Proporciona credenciales para credenciales predeterminadas de la aplicación

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En esta página, se describe cómo proporcionar credenciales a las credenciales predeterminadas de la aplicación (ADC) para que las usen las bibliotecas cliente de Cloud y las bibliotecas cliente de las APIs de Google en una variedad de entornos.

Las ADC son una estrategia que usan las bibliotecas cliente de Cloud y las bibliotecas cliente de las APIs de Google para encontrar credenciales automáticamente según el entorno de la aplicación y usarlas a fin de autenticarse en las APIs de Google Cloud. Cuando configuras ADC y usas una biblioteca cliente, el código puede ejecutarse en un entorno de desarrollo o de producción sin cambiar la forma en que la aplicación se autentica en los servicios y las APIs de Google Cloud.

Para obtener más información sobre dónde ADC busca credenciales y en qué orden, consulta Cómo funcionan las credenciales predeterminadas de la aplicación.

Si usas claves de API, no necesitas proporcionar credenciales mediante ADC. Para obtener ayuda sobre cómo determinar si una API acepta claves de API, consulta Usa claves de API.

Cómo proporcionar credenciales a ADC

La forma en que proporcionas credenciales a ADC depende del lugar en el que se ejecuta tu código:

Entorno de desarrollo local

Credenciales de usuario

Cuando tu código se ejecuta en un entorno de desarrollo local, como una estación de trabajo de desarrollo, la mejor opción es usar credenciales asociadas con tu Cuenta de Google, también llamadas credenciales de usuario.

Para proporcionar tus credenciales de usuario a ADC, usa Google Cloud CLI:

  1. Instala y, luego, inicializa la CLI de gcloud, si aún no lo hiciste.

  2. Crea el archivo de credenciales:

    gcloud auth application-default login

    Se muestra una pantalla de acceso. Después de acceder, tus credenciales se almacenan en el archivo de credenciales local que usa ADC.

El uso de la CLI de gcloud para proporcionar credenciales a ADC tiene las siguientes limitaciones:

  • Las credenciales de usuario no funcionan para algunos métodos y API, como la API de Cloud Translation o la API de Cloud Vision. Si ves un mensaje de error que indica que la API no está habilitada en el proyecto o que no hay ningún proyecto de cuota disponible, consulta Soluciona problemas de la configuración de ADC.

  • Este método almacena tus credenciales en un archivo del sistema de archivos. Cualquier usuario con acceso al sistema de archivos puede usar esas credenciales. Cuando ya no necesites estas credenciales, debes revocarlas:

    gcloud auth application-default revoke
  • Si tu Cuenta de Google no tiene los roles necesarios de Identity and Access Management (IAM) en tu proyecto, es posible que el código no pueda acceder a algunos recursos. Si esto sucede, pídele a tu administrador de seguridad que te otorgue los roles necesarios.

Tipos de credenciales de gcloud

El comando gcloud auth application-default login proporciona una forma de almacenar las credenciales de tu Cuenta de Google en la ubicación conocida para que las use ADC, pero solo las bibliotecas cliente y ADC las usan. Cuando ejecutas comandos en la CLI de gcloud, usas las credenciales que proporcionaste cuando accediste a la CLI de gcloud con el comando gcloud auth login.

Por lo general, usarás la misma cuenta para acceder a la CLI de gcloud y proporcionar credenciales de usuario a ADC, pero puedes usar cuentas diferentes si es necesario.

Para obtener información sobre cómo acceder a la CLI de gcloud, consulta Inicializa la CLI de gcloud.

Claves de cuenta de servicio

Si no puedes usar credenciales de usuario para el desarrollo local, puedes usar una clave de cuenta de servicio. Las claves de las cuentas de servicio crean riesgos innecesarios y deben evitarse siempre que sea posible.

Si la política de la organización tiene una restricción que evita la creación de una clave de cuenta de servicio, este método no estará disponible para ti.

A fin de crear una clave de cuenta de servicio y hacer que esté disponible para las ADC, haz lo siguiente:

  1. A fin de crear una cuenta de servicio con las funciones que necesita tu aplicación y una clave para esa cuenta de servicio, sigue las instrucciones en Crea una clave de cuenta de servicio.

  2. Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ubicación de la clave.

Entorno de desarrollo basado en la nube de Google Cloud

Cuando usas un entorno de desarrollo basado en la nube de Google Cloud, como Cloud Shell o Cloud Code, la herramienta usa las credenciales que proporcionaste cuando accediste y administra las autorizaciones necesarias.

Entorno de desarrollo alojado en contenedores

Si realizas desarrollos locales en un entorno alojado en contenedores, debes hacer que tu archivo de credenciales personales esté disponible para el contenedor. El complemento de Minikube de GCP Auth es una forma de hacerlo.

Servicios de Google Cloud que admiten la conexión de una cuenta de servicio

Algunos servicios de Google Cloud, como Compute Engine, App Engine y Cloud Functions, admiten adjuntar una cuenta de servicio administrada por el usuario a algunos tipos de recursos. Por lo general, se admite la conexión de una cuenta de servicio cuando los recursos de ese servicio pueden ejecutarse o incluir el código de la aplicación. Cuando conectas una cuenta de servicio a un recurso, el código que se ejecuta en el recurso puede usar esa cuenta de servicio como su identidad.

Es preferible conectar una cuenta de servicio administrada por el usuario a fin de proporcionar credenciales a las ADC para el código de producción que se ejecuta en Google Cloud.

Para obtener ayuda con la creación de una cuenta de servicio, consulta Crea y administra cuentas de servicio. Para obtener ayuda a fin de determinar los roles que debes proporcionar a tu cuenta de servicio, consulta Elige roles predefinidos.

Para obtener información sobre los recursos a los que puedes conectar una cuenta de servicio y ayudar a conectar la cuenta de servicio al recurso, consulta la documentación de IAM sobre cómo conectar una cuenta de servicio.

Si la política de la organización tiene una restricción que limita la creación de cuentas de servicio, no puedes usar este método para configurar credenciales para ADC.

Entorno alojado en contenedores de Google Cloud

Si planeas alojar tu aplicación en contenedores mediante Google Kubernetes Engine o Anthos, puedes usar ADC para el desarrollo local con la CLI de gcloud o usar un contenedor local.

Cuando estés listo para migrar al entorno alojado en contenedores de Google Cloud, debes comprender cómo tu entorno admite la autenticación y las cuentas de servicio.

Proveedor local u otro proveedor de servicios en la nube

Si ejecutas tu aplicación fuera de Google Cloud, debes proporcionar credenciales que Google Cloud reconozca para usar los servicios de Google Cloud.

Federación de Workload Identity

La forma preferida de autenticarte con Google Cloud mediante credenciales de un proveedor de identidad diferente es usar la federación de Workload Identity; debes crear un archivo de configuración de credenciales y establecer la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para que apunte a él. Este enfoque es más seguro que crear una clave de cuenta de servicio.

A fin de obtener ayuda con la configuración de la federación de Workload Identity para ADC, consulta Configura la federación de Workload Identity y Obtén credenciales de corta duración con federación de identidades.

Clave de cuenta de servicio

Si no puedes configurar la federación de Workload Identity, debes crear una cuenta de servicio, otorgarle los roles de IAM que requiera tu aplicación y crear una clave para la cuenta de servicio.

Si la política de la organización tiene una restricción que evita la creación de una clave de cuenta de servicio, este método no estará disponible para ti.

A fin de crear una clave de cuenta de servicio y hacer que esté disponible para las ADC, haz lo siguiente:

  1. A fin de crear una cuenta de servicio con las funciones que necesita tu aplicación y una clave para esa cuenta de servicio, sigue las instrucciones en Crea una clave de cuenta de servicio.

  2. Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ubicación de la clave.

Soluciona problemas de configuración de ADC

Algunos problemas comunes que pueden surgir cuando usas ADC incluyen las siguientes situaciones:

Las credenciales de usuario no funcionan

Si tu solicitud de API muestra un mensaje de error sobre credenciales de usuario final que no son compatibles con esta API, que la API no está habilitada en el proyecto o que no se estableció ningún proyecto de cuota, revisa la siguiente información.

Existen dos tipos de API de Google Cloud:

  • APIs basadas en recursos, que usan el proyecto asociado con los recursos a los que se accede para la facturación y la cuota.

  • APIs basadas en el cliente, que usan el proyecto asociado con la cuenta que accede a los recursos para facturación y cuota.

Cuando usas las credenciales de la Cuenta de Google con una API basada en cliente, el proyecto predeterminado asociado a la cuenta no se puede usar para facturación.

A fin de resolver este problema, debes actualizar ADC para que use un proyecto diferente como el de facturación:

gcloud auth application-default set-quota-project YOUR_PROJECT

Debes tener el permiso de IAM serviceusage.services.use para que un proyecto pueda designarlo como tu proyecto de facturación. El permiso serviceusage.services.use se incluye en el rol de IAM Service Usage Consumer. Si no tienes el permiso serviceusage.services.use para ningún proyecto, comunícate con tu administrador de seguridad o un propietario del proyecto que pueda otorgarte el rol Service Usage Consumer en el proyecto.

El proyecto de facturación no se incluye en el token que muestra ADC para las solicitudes REST. Si usas ADC con una solicitud de REST, consulta Configura el proyecto de cuota con una solicitud de REST.

Las credenciales son incorrectas

Si parece que tus credenciales no proporcionan el acceso que esperas o no se encuentran, inspecciona las credenciales disponibles para ADC, en el orden en que ADC busca las credenciales, a fin de ver qué podría estar mal. A continuación, se indican algunos aspectos que debes verificar:

  • Asegúrate de que la variable de entorno GOOGLE_APPLICATION_CREDENTIALS se configure solo si usas una clave de cuenta de servicio u otro archivo JSON para ADC. Las credenciales a las que apunta la variable de entorno tienen prioridad sobre otras credenciales, incluido Workload Identity.

  • Confirma que el principal que realiza la solicitud tenga los roles de IAM necesarios. Si usas credenciales de usuario, las funciones deben otorgarse a la dirección de correo electrónico asociada con la Cuenta de Google. Si usas una cuenta de servicio, esa cuenta debe tener los roles necesarios.

  • Si proporcionas una clave de API con la solicitud a la API, esta tendrá prioridad sobre ADC en cualquier ubicación. Si configuraste la variable de entorno GOOGLE_APPLICATION_CREDENTIALS y usas una clave de API, es posible que la API muestre una advertencia que te indique que se ignoran las credenciales que proporcionaste a ADC. Para detener la advertencia, desactiva la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

Tipo de credencial no reconocido

Si tu solicitud a la API muestra un error que incluye "Error al crear la credencial desde JSON. No se reconoce el tipo de credencial", asegúrate de usar una credencial válida. Los archivos de ID de cliente no son compatibles con el fin de proporcionar credenciales para ADC.

¿Qué sigue?