Configura credenciales predeterminadas de la aplicación

En esta página, se describe cómo configurar credenciales predeterminadas de la aplicación (ADC) para que las usen las bibliotecas cliente de Cloud, las bibliotecas cliente de la API de Google y las API de REST y RPC en una variedad de entornos. Para configurar ADC, proporciona credenciales a ADC en el entorno en el que se ejecuta el código.

Application Default Credentials (ADC) es una estrategia que usan las bibliotecas de autenticación de Google para encontrar credenciales automáticamente según el entorno de la aplicación. Las bibliotecas de autenticación ponen esas credenciales a disposición de las bibliotecas cliente de Cloud y las bibliotecas cliente de las APIs de Google. Cuando usas ADC, tu código puede ejecutarse en un entorno de desarrollo o de producción sin cambiar la forma en que tu aplicación se autentica en los servicios y las APIs de Google Cloud.

Para obtener 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 es necesario que configures ADC. Para obtener más información, 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:

  • Es posible que las credenciales del usuario no funcionen con algunos métodos y APIs, como la API de Cloud Translation o la API de Cloud Vision, sin parámetros ni configuración adicionales. Si ves un mensaje de error en el que se 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.

Credenciales de ADC y credenciales de gcloud

Cuando accedes a la CLI de gcloud, usas el comando gcloud auth login a fin de proporcionar las credenciales de usuario, que la CLI de gcloud usa para la autenticación y autorización a fin de administrar recursos y servicios de Google Cloud. Como alternativa, puedes usar la marca --impersonate-service-account o la propiedad auth/impersonate_service_account para actuar como una cuenta de servicio. Estas credenciales son tus credenciales de gcloud.

Cuando usas la CLI de gcloud para proporcionar credenciales a ADC, usa el comando gcloud auth application-default login. Este comando coloca tus credenciales en una ubicación conocida para que las usen las ADC en un entorno de desarrollo local. Estas son tus credenciales de ADC locales.

La CLI de gcloud no usa tus credenciales de ADC locales, y ADC no usa tus credenciales de gcloud. Son dos conjuntos distintos de credenciales.

En la siguiente tabla, se muestran los dos comandos y lo que hacen:

Comando Descripción
gcloud auth login

Acepta las credenciales de usuario que se usan para autenticarse en los servicios de Google Cloud y autorizar el acceso a ellos.

gcloud auth application-default login

Acepta las credenciales de usuario que se proporcionan a las credenciales predeterminadas de la aplicación para su uso en un entorno de desarrollo local.

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. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo JSON que contiene la clave de tu cuenta de servicio. Esta variable solo se aplica a la sesión actual de shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.

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. No necesitas usar la CLI de gcloud para proporcionar tus credenciales de usuario.

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 restringe la creación de cuentas de servicio, no puedes usar este método para proporcionar credenciales a ADC.

Entorno alojado en contenedores de Google Cloud

La autenticación de los entornos en contenedores se maneja de forma diferente entre los entornos de desarrollo y de producción.

Desarrollo para entornos en contenedores

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 usas un contenedor local como entorno de desarrollo, debes hacer que el archivo de credenciales personales esté disponible para el contenedor. El complemento de Minikube de GCP Auth es una forma de hacerlo.

Entornos de producción en contenedores

La forma en que configuras la autenticación para los entornos en contenedores de Google Cloud depende del entorno que uses.

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. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo JSON que contiene la clave de tu cuenta de servicio. Esta variable solo se aplica a la sesión actual de shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.

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.

Para solucionar este problema, realiza una de las siguientes acciones:

  1. Actualiza ADC para que use un proyecto diferente como el de facturación:

    gcloud auth application-default set-quota-project YOUR_PROJECT

  2. Si llamas a la API de REST o de RPC directamente, usa el encabezado HTTP x-goog-user-project para especificar un proyecto de facturación en cada solicitud. Para obtener más detalles, consulta Configura el proyecto de cuota con una solicitud de REST.

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.

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:

  • Si usas la CLI de gcloud para acceder a Google Cloud, no debes usar las credenciales que proporcionaste a ADC. En su lugar, debes usar las credenciales que proporcionaste a la CLI de gcloud mediante el comando gcloud auth login. Para obtener más información sobre estos dos conjuntos de credenciales, consulta Credenciales de ADC y credenciales de gcloud.

  • 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?