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 tu código.

Application Default Credentials (ADC) es una estrategia que usan las bibliotecas de autenticación 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, el código puede ejecutarse en un entorno de producción o de desarrollo sin cambiar la forma en que la 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 necesitas configurar ADC. Para obtener más información, consulta Usa claves de API.

Cómo proporcionar credenciales a ADC

Elige el entorno en el que se ejecuta tu código:

Entorno de desarrollo local

Puedes proporcionar tus credenciales de usuario o credenciales de la cuenta de servicio a ADC en un 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 las credenciales asociadas con tu cuenta de usuario.

Cuando configures ADC con tu cuenta de usuario, debes tener en cuenta los siguientes datos:

  • Es posible que la configuración de ADC con una cuenta de usuario no funcione 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 Las credenciales de usuario no funcionan.

  • El archivo local de ADC contiene tu token de actualización. Cualquier usuario con acceso al sistema de archivos puede usarlo para obtener un token de acceso válido. Si ya no necesitas estas credenciales locales, puedes revocarlas mediante el comando gcloud auth application-default revoke.

  • El archivo de ADC local está asociado con tu cuenta de usuario, no con la configuración de la CLI de gcloud. Cambiar a una configuración de la CLI de gcloud diferente podría cambiar la identidad que usa gcloud CLI, pero no afecta el archivo de ADC local ni la configuración de ADC.

La forma de configurar ADC con tu cuenta de usuario depende de si tu cuenta de usuario es administrada por Google (en otras palabras, es una Cuenta de Google) o por otro proveedor de identidad (IdP), y si es federada mediante Workforce Identity Federation.

Configura ADC con tu Cuenta de Google

Para configurar ADC con una Cuenta de Google, usa Google Cloud CLI:

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

  2. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

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

Configura ADC con una cuenta administrada por un IdP externo

Para configurar ADC para una cuenta de usuario administrada por un IdP externo y federada con Workforce Identity Federation, haz lo siguiente:

  1. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command: 

    gcloud init

  2. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

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

Credenciales de cuenta de servicio

Puedes configurar ADC con credenciales de una cuenta de servicio mediante el uso de la identidad temporal como cuenta de servicio o de una clave de cuenta de servicio.

Uso de identidad temporal como cuenta de servicio

Puedes usar la identidad de una cuenta de servicio para configurar un archivo de credenciales predeterminadas de la aplicación (ADC) local. Las bibliotecas cliente que admiten el uso de identidad pueden utilizar esas credenciales automáticamente. Los archivos de ADC locales creados mediante el uso de identidad se admiten en los siguientes idiomas:

  • C#
  • Go
  • Java
  • Node.js
  • Python

Debes tener el rol de IAM de creador de tokens de cuentas de servicio (roles/iam.serviceAccountTokenCreator) en la cuenta de servicio que suplantas. Para obtener más información, consulta los Roles requeridos.

Usa la identidad de la cuenta de servicio para crear un archivo de ADC local: 

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Ahora puedes usar bibliotecas cliente con los idiomas admitidos de la misma manera que lo harías después de configurar un archivo ADC local con credenciales de usuario. Las bibliotecas de autenticación encuentran las credenciales automáticamente. Si deseas obtener más información, consulta Autentícate para usar las bibliotecas cliente.

Claves de cuenta de servicio

Si no puedes usar una cuenta de usuario o la identidad temporal como cuenta de servicio para el desarrollo local, puedes usar una clave de cuenta de servicio.

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.

    Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

Entornos de desarrollo basados 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 puedes usar la gcloud CLI para configurar ADC en estos entornos. Si necesitas usar una cuenta de usuario diferente para configurar ADC o configurar ADC con una cuenta de servicio, usa un entorno de desarrollo local o un recurso de procesamiento de Google Cloud como tu entorno de desarrollo.

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 Run 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 sobre cómo 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.

Set up authentication:

  1. Create the service account: 

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Replace SERVICE_ACCOUNT_NAME with a name for the service account.

  2. To provide access to your project and your resources, grant a role to the service account: 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • ROLE: the role to grant
  3. To grant another role to the service account, run the command as you did in the previous step.

  4. Grant the required role to the principal that will attach the service account to other resources. 

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • USER_EMAIL: the email address for a Google Account

GKE

La autenticación para aplicaciones alojadas en contenedores que se ejecutan en GKE o GKE Enterprise se controla de manera diferente entre los entornos de prueba locales y los de Google Cloud.

Prueba las aplicaciones alojadas en contenedores de forma local

Para probar la aplicación alojada en contenedores en la estación de trabajo local, puedes configurar contenedores para autenticarte con tu archivo de credenciales local. Para probar los contenedores, usa una implementación local de Kubernetes, como minikube y el complemento gcp-auth.

Ejecuta aplicaciones alojadas en contenedores en Google Cloud

La configuración de la autenticación para los entornos alojados en contenedores de Google Cloud es diferente según el entorno:

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 identidades para cargas de trabajo

La forma preferida de autenticarte con Google Cloud mediante credenciales de un IdP externo es usar la federación de identidades para cargas de trabajo; 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.

Para obtener ayuda con la configuración de la federación de identidades para cargas de trabajo for ADC, consulta federación de identidades para cargas de trabajo con otras nubes.

Clave de cuenta de servicio

Si no puedes configurar Workload Identity Federation, 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.

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.

    Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

¿Qué sigue?