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, 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 proporcionas credenciales de usuario para crear un archivo de ADC local, debes tener en cuenta los siguientes datos:

  • 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 Solucionar problemas de la configuración de ADC.

  • Las ADC locales contienen tus tokens de acceso y actualización. Cualquier usuario con acceso al sistema de archivos puede usar esas credenciales. Si ya no necesitas estas credenciales locales, puedes revocarlas mediante el comando 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, alguien debe otorgarte los roles necesarios.

  • 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 no afecta el archivo de ADC local ni las credenciales proporcionadas a ADC.

La forma de proporcionar tus credenciales de usuario a ADC 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 la federación de identidades de personal.

Proporciona credenciales de usuario para tu Cuenta de Google

A fin de proporcionar tus credenciales de usuario a ADC para una Cuenta de Google, usa Google Cloud CLI:

  1. Instala e inicializa gcloud CLI

    Cuando inicialices gcloud CLI, asegúrate de especificar un proyecto de Google Cloud en el que tengas permiso para acceder a los recursos que necesita tu aplicación.

  2. Crea tu archivo de credenciales:

    gcloud auth application-default login

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

Proporciona credenciales de usuario para una cuenta administrada por un IdP externo

A fin de proporcionar tus credenciales de usuario para una cuenta de usuario administrada por un IdP externo y federada con la federación de identidades de personal, necesitas el nombre de tu proveedor de grupos de personal. El administrador debería poder proporcionarte esta información. El nombre del proveedor de grupos de personal tiene el siguiente formato:

locations/global/workforcePools/POOL_ID/provider/PROVIDER_ID

Proporciona tus credenciales de usuario a ADC para una cuenta de usuario federada:

  1. Crea tu archivo de configuración de acceso y configura la propiedad auth/login_config_file de la CLI de gcloud para que apunte a su ubicación, mediante el comando iam workload-pools create-login-config:

    gcloud iam workforce-pools create-login-config PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE --activate
    

    Reemplaza lo siguiente:

    • PROVIDER_ID: el ID del proveedor
    • LOGIN_CONFIG_FILE: una ruta de acceso al archivo de configuración que especifiques, por ejemplo, login.json

    El archivo que se crea es similar al siguiente ejemplo:

    {
    "type": "external_account_authorized_user_login_config",
    "audience": "//iam.googleapis.com/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",
    }
    

  2. Accede a gcloud CLI con el archivo de acceso:

    gcloud auth login
    
  3. Inicializa la CLI de gcloud:

    gcloud init
    
  4. Crea tu archivo local de ADC:

    gcloud auth application-default login
    

Para obtener más información, consulta federación de identidades de personal.

Credenciales de cuenta de servicio

Puedes configurar ADC con credenciales de una cuenta de servicio mediante el uso de la identidad de una 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

Claves de cuenta de servicio

Si no puedes usar credenciales de usuario o la identidad de una 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.

  2. 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.

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 puedes usar la CLI de gcloud para proporcionar credenciales a ADC en estos entornos. Si necesitas proporcionar una cuenta de usuario diferente a ADC o proporcionar credenciales mediante 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 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 o GKE Enterprise

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 contexto:

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 diferente 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.

A fin de obtener ayuda con la configuración de la federación de Workload Identity para ADC, consulta Configura la federación de entidades para cargas de trabajo 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 identidades para cargas de trabajo, 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?