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
• Entornos de desarrollo basados en la nube de Google Cloud
• Compute Engine o cualquier otro servicio de Google Cloud que admita la conexión de una cuenta de servicio

• Google Kubernetes Engine

• Proveedor local u otro proveedor de servicios en la nube

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.

   Nota: Para agregar permisos a servicios fuera de Google Cloud, como Google Drive, crea un ID de cliente de OAuth y proporciónalo al comando gcloud auth application-default login; para ello, usa la marca --client-id-file y especifica los permisos con la marca --scopes.

   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.

Nota: Las claves de cuenta de servicio son un riesgo de seguridad si no se administran de forma adecuada. Debes elegir una alternativa más segura a las claves de la cuenta de servicio siempre que sea posible. Si te debes autenticar con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones que se describen en Prácticas recomendadas para administrar claves de cuenta de servicio. Si no se te permite crear una clave de cuenta de servicio, es posible que la creación de claves de cuentas de servicio esté inhabilitada para tu organización. Para obtener más información, consulta Administra los recursos de la organización con seguridad de forma predeterminada.

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.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   Nota: Cuando configuras la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, las ADC primero verifican esta ubicación y, luego, verifican otras ubicaciones solo si es necesario.

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.

Nota: Muchos de estos servicios de Google Cloud también proporcionan una cuenta de servicio predeterminada. No se recomienda usar la cuenta de servicio predeterminada, ya que, según la configuración predeterminada, tiene un gran privilegio, lo que infringe el principio de privilegio mínimo.

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
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
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:

• Para GKE Enterprise, consulta la descripción general de la autenticación y Usa Workload Identity Federation for GKE de la flota.
• En el caso de GKE, consulta Accede a las APIs de Google Cloud desde cargas de trabajo de GKE.
• Para la publicación de Knative, consulta Usa la Workload Identity Federation for GKE en Knative serving.

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 Workload Identity Federation; 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 Workload Identity Federation for ADC, consulta Workload Identity Federation 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.

Nota: Las claves de cuenta de servicio son un riesgo de seguridad si no se administran de forma adecuada. Debes elegir una alternativa más segura a las claves de la cuenta de servicio siempre que sea posible. Si te debes autenticar con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones que se describen en Prácticas recomendadas para administrar claves de cuenta de servicio. Si no se te permite crear una clave de cuenta de servicio, es posible que la creación de claves de cuentas de servicio esté inhabilitada para tu organización. Para obtener más información, consulta Administra los recursos de la organización con seguridad de forma predeterminada.

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.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   Nota: Cuando configuras la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, las ADC primero verifican esta ubicación y, luego, verifican otras ubicaciones solo si es necesario.

¿Qué sigue?

• Obtén más información sobre cómo ADC encuentra credenciales.
• Autentica para usar las bibliotecas cliente de Cloud.
• Explora los métodos de autenticación.