Obtén tokens de corta duración para la federación de identidades de personal

En esta guía, se muestra cómo usar un grupo de Workforce Identity y un proveedor de grupos de Workforce Identity para obtener tokens de corta duración del servicio de tokens de seguridad. Puedes usar los tokens para acceder a los recursos de Google Cloud que admiten la federación de identidades de personal y a los que se te otorgó acceso.

Obtén tokens de corta duración mediante este proceso:

  1. Obtén una credencial del proveedor de identidad de confianza.
  2. Intercambia la credencial por un token del servicio de tokens de seguridad.

Antes de comenzar

  1. Configura la federación de Workforce Identity o, para obtener instrucciones específicas del IdP, consulta las siguientes guías:

  2. Debes conocer el ID de tu grupo de personal o el ID de tu proveedor.

  3. Asegúrate de tener el permiso de Identity and Access Management (IAM) serviceusage.services.use. El rol con privilegios mínimos que contiene este permiso es Service Usage Consumer (roles/serviceusage.serviceUsageConsumer).

  4. Enable the IAM and Security Token Service APIs.

    Enable the APIs

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

    gcloud init

Intercambia credenciales externas por un token de acceso de Google Cloud

En esta sección, se muestra cómo usar el servicio de tokens de seguridad para intercambiar tus credenciales externas por un token de acceso que otorgue acceso a Google Cloud. Para ello, usa la CLI de gcloud, la API de REST y las bibliotecas cliente de Cloud, como se describe más adelante en esta guía.

Si necesitas acceso de larga duración, puedes configurar un proceso de larga duración para actualizar las credenciales de esa máquina de forma continua. Como alternativa, puedes ejecutar un servidor local en segundo plano con un extremo que muestre las credenciales.

Acceso basado en el navegador con la CLI de gcloud

En esta sección, se describe cómo configurar la CLI de gcloud para usar un flujo de acceso basado en el navegador. Para ello, debes crear un archivo de configuración de acceso y hacer referencia al archivo en las llamadas a gcloud auth login o activarlo para que se use de forma predeterminada.

Crea el archivo de configuración de acceso

Para crear el archivo de configuración de acceso, ejecuta el siguiente comando. De manera opcional, puedes activar el archivo como predeterminado para la CLI de gcloud mediante la marca --activate. 

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal
  • 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 contiene los extremos que usa la gcloud CLI para habilitar el flujo de autenticación basado en el navegador y establecer el público en el proveedor que creaste antes en esta guía. El archivo no contiene información confidencial.

El resultado es similar al siguiente:

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

Accede con autenticación basada en el navegador

Para autenticar con la autenticación de acceso basada en el navegador, puedes usar uno de los siguientes métodos:

  • Si usaste la marca --activate cuando creaste el archivo de configuración o si activaste el archivo de configuración con gcloud config set auth/LOGIN_CONFIG_FILE, gcloud CLI usa el archivo de configuración de forma automática: 

    gcloud auth login

  • Para acceder mediante la especificación de la ubicación del archivo de configuración, ejecuta el siguiente comando: 

    gcloud auth login --login-config=LOGIN_CONFIG_FILE
  • Para usar una variable de entorno a fin de especificar la ubicación del archivo de configuración, establece CLOUDSDK_AUTH_LOGIN_CONFIG_FILE en la ruta de configuración.

Inhabilita el acceso basado en el navegador

Para dejar de usar el archivo de configuración de acceso, haz lo siguiente:

  • Si usaste la marca --activate cuando creaste el archivo de configuración o si activaste el archivo de configuración con gcloud config set auth/LOGIN_CONFIG_FILE, debes ejecutar el siguiente comando para anularlo: 

    gcloud config unset auth/login_config_file
  • Borra la variable de entorno CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, si está configurada.

Usa archivos de configuración para el acceso

Como alternativa al acceso basado en el navegador, en esta sección, se muestran diferentes formas de usar los archivos de configuración de credenciales para proporcionar acceso a acciones autenticadas de Google Cloud. Para establecer los archivos de configuración, no es necesario que accedas a gcloud CLI.

La forma en que estableces tu archivo de configuración depende de si tu IdP usa OIDC o SAML.

OIDC

Puedes obtener las credenciales que usas para preparar tu archivo de configuración desde las siguientes fuentes:

Credenciales basadas en archivos

Los tokens se cargan desde un archivo. Otro proceso debe actualizar este archivo con un token de OIDC nuevo antes de que caduque el token anterior. Por ejemplo, si el token tiene un ciclo de vida de 1 hora, debes actualizar el archivo antes de que tenga 1 hora de antigüedad.

Para generar el archivo de configuración con una credencial basada en archivos, ejecuta el siguiente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal
  • PROVIDER_ID: el ID del proveedor
  • PATH_TO_OIDC_TOKEN: la ruta de acceso al archivo de credenciales del IdP de OIDC
  • WORKFORCE_POOL_USER_PROJECT: El número o ID del proyecto asociado con el proyecto de usuario de grupos de trabajadores.

La principal debe tener el permiso serviceusage.services.use en este proyecto.

Cuando ejecutas el comando, se produce un archivo de configuración de IdP de OIDC similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

Credenciales basadas en URL

Los tokens se cargan desde un servidor local con un extremo que responde a las solicitudes HTTP GET. La respuesta debe ser un token de ID de OIDC, ya sea en texto sin formato o en formato JSON.

Para generar el archivo de configuración con una credencial basada en URL, ejecuta el siguiente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • URL_TO_RETURN_OIDC_ID_TOKEN: la URL a la que se debe llamar para recuperar las credenciales de OIDC, como un token de ID de OIDC, por ejemplo: http://localhost:5000/token.
  • WORKFORCE_POOL_USER_PROJECT: es el número de proyecto que se usa para la cuota y la facturación. La principal debe tener serviceusage.services.use permission en este proyecto.

Cuando ejecutas el comando, se produce un archivo de configuración de IdP de OIDC similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Credenciales no interactivas basadas en ejecutables

Los tokens se cargan desde un ejecutable local. El ejecutable debe proporcionar un token de ID de OIDC válido y no vencido en formato JSON a stdout:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Estos campos son obligatorios para una respuesta exitosa, con la excepción de expiration_time. El campo expiration_time solo es obligatorio cuando se especifica un archivo de salida en la configuración de la credencial.

El ejecutable debe mostrar cualquier error en stdout en el siguiente formato JSON:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos estos campos son obligatorios para una respuesta de error. Las bibliotecas cliente usan los códigos y campos de mensaje cuando se genera el error adecuado.

El comando puede mostrar los siguientes campos:

  • version: Es la versión del resultado de JSON. Solo se admite la versión 1.

  • success: Es el estado de la respuesta. Cuando el estado es true, el ejecutable debe salir con el código de salida 0 y la respuesta debe contener los siguientes campos:

    • token_type: id_token
    • expiration_time si se especificó un archivo de salida en la configuración de credenciales

    Cuando el estado es false, el ejecutable debe salir con un valor distinto de cero y la respuesta debe contener los siguientes campos:

    • code
    • message

  • token_type: es el tipo de token del asunto de terceros, que debe ser urn:ietf:params:oauth:token-type:id_token.

  • id_token: es el token de OIDC de terceros.

  • expiration_time: es el tiempo de vencimiento del token de OIDC de terceros en segundos (tiempo de época Unix).

  • code: es la cadena de código de error.

  • message: es el mensaje de error.

Las bibliotecas cliente propagarán las siguientes variables de entorno cuando se ejecute el ejecutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: el campo de público de la configuración de las credenciales. Siempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: el tipo de token del asunto esperado. Siempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: ubicación del archivo de salida de la configuración de credenciales. Solo está presente cuando se especifica en la configuración de credenciales.

El ejecutable puede usar estas variables de entorno para evitar la codificación de estos valores.

Para habilitar este método de obtención de credenciales con las bibliotecas cliente, la variable de entorno GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES debe configurarse como 1.

Para generar el archivo de configuración con una credencial basada en un ejecutable, ejecuta el siguiente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • EXECUTABLE_COMMAND: el comando completo, incluidos los argumentos, para ejecutar a fin de recuperar el token del asunto, como un token de ID de OIDC, en el siguiente formato: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (opcional) una duración en milisegundos para esperar que el archivo ejecutable se ejecute (el valor predeterminado es de 30 segundos).
  • EXECUTABLE_OUTPUT_FILE: (opcional) una ruta de acceso de archivos a las credenciales de terceros que genera el ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de Auth primero comprueban esta ruta antes de ejecutar el archivo ejecutable.
  • WORKFORCE_POOL_USER_PROJECT: es el número o ID del proyecto que se usa para la cuota y la facturación. La principal debe tener el permiso serviceusage.services.use configurado en este proyecto.

Cuando ejecutas el comando, se produce un archivo de configuración de IdP de OIDC similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Credenciales interactivas basadas en ejecutables

Puedes proporcionar un ejecutable que interactúe con el usuario a través de stdin y stdout. Si el usuario accede de forma correcta, el ejecutable escribe una credencial válida y no vencida en el archivo especificado.

Para usar este modo, se requieren las siguientes marcas:

  • --executable-output-file: el archivo en el que el ejecutable escribe la información de la credencial
  • --exeutable-interactive-timeout-millis: un valor distinto de cero que indica el modo interactivo y establece el tiempo de espera, por ejemplo, 6000 para un tiempo de espera de 60 segundos

Los siguientes campos son obligatorios para una respuesta exitosa, con la excepción de expiration_time:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

El ejecutable debe escribir cualquier error en el archivo especificado en --executable-output-file en el siguiente formato JSON. Los siguientes campos son obligatorios para mostrar una respuesta de error.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Los campos code y message deben indicar el error adecuado. Las bibliotecas cliente usan estos campos cuando se genera el error.

Cuando se ejecuta de manera correcta, el comando muestra los mismos campos, sin importar si se usaron los resultados de credenciales interactivas o no interactivas con origen ejecutable anteriores.

Las variables de entorno también son las mismas que las credenciales normales basadas en ejecutables.

Para generar una credencial interactiva basada en un ejecutable, agrega el parámetro --executable-interactive-timeout-millis y el parámetro --executable-output-file.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • EXECUTABLE_COMMAND: es el comando completo, incluidos los argumentos, que se ejecuta para recuperar el token del asunto, con el siguiente formato: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una duración en milisegundos que se esperará para que se ejecute el ejecutable.
  • EXECUTABLE_OUTPUT_FILE: una ruta de acceso de archivos a las credenciales de terceros que genera el ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de Auth primero comprueban esta ruta antes de ejecutar el archivo ejecutable.
  • WORKFORCE_POOL_USER_PROJECT: el número o ID del proyecto que se usa para la cuota y la facturación. La principal debe tener el permiso serviceusage.services.use en este proyecto.

Cuando ejecutas el comando, se produce un archivo de configuración de IdP de OIDC similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

SAML

Puedes obtener las credenciales que usas para preparar tu archivo de configuración desde las siguientes fuentes:

Credenciales basadas en archivos

Las aserciones se cargan desde un archivo. Otro proceso debe actualizar este archivo con una nueva aserción de SAML codificada en base64 antes de que caduque la aserción anterior. Por ejemplo, si la aserción tiene un ciclo de vida de 1 hora, debes actualizar el archivo antes de que tenga 1 hora de antigüedad.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • CREDENTIAL_FILE: la ruta de acceso al archivo de credenciales que genera el IdP.
  • WORKFORCE_POOL_USER_PROJECT: es el número o ID del proyecto que se usa para la cuota y la facturación. La principal debe tener serviceusage.services.use permission en este proyecto.

Credenciales basadas en URL

Las aserciones se cargan desde un servidor local con un extremo que responde a las solicitudes GET HTTP. La respuesta debe ser una aserción de SAML codificada en base64 o JSON que contenga una aserción de SAML codificada en base64.

Para usar credenciales basadas en URL, usa la marca --credential-source-url:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-url=CREDENTIAL_URL \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • CREDENTIAL_URL: URL del extremo del servidor local.
  • WORKFORCE_POOL_USER_PROJECT: El número o ID del proyecto que se usa para la cuota y la facturación. La principal debe tener serviceusage.services.use permission en este proyecto.

Credenciales basadas en ejecutables

Las aserciones se cargan desde un ejecutable local. El ejecutable debe proporcionar una aserción SAML válida no vencida en formato JSON a stdout.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Estos campos son obligatorios para una respuesta exitosa, con la excepción de expiration_time. El campo expiration_time solo es obligatorio cuando se especifica un archivo de salida en la configuración de la credencial.

Si se produce un error, el ejecutable debe mostrarlo en el siguiente formato JSON a stdout: 

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos estos campos son obligatorios para una respuesta de error. Las bibliotecas cliente usan los códigos y campos de mensaje cuando se genera el error adecuado.

El comando puede mostrar los siguientes campos:

  • version: Es la versión del resultado de JSON. Solo se admite la versión 1.

  • success: Es el estado de la respuesta. Cuando el estado es true, el ejecutable debe salir con el código de salida 0 y la respuesta debe contener los siguientes campos:

    • token_type: saml_response
    • expiration_time si se especificó un archivo de salida en la configuración de credenciales

    Cuando el estado es false, el ejecutable debe salir con un valor distinto de cero y la respuesta debe contener los siguientes campos: + code + message

  • token_type: es el tipo de token del asunto de terceros, que debe ser urn:ietf:params:oauth:token-type:saml2.

  • saml_response: es la respuesta de SAML de terceros.

  • expiration_time: es el tiempo de vencimiento de la respuesta SAML externa en segundos (tiempo de época Unix).

  • code: es la cadena de código de error.

  • message: es el mensaje de error.

Las bibliotecas cliente propagarán las siguientes variables de entorno cuando se ejecute el ejecutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: el campo de público de la configuración de las credenciales. Siempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: el tipo de token del asunto esperado. Siempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: ubicación del archivo de salida de la configuración de credenciales. Solo está presente cuando se especifica en la configuración de credenciales.

Para habilitar este método de obtención de credenciales con las bibliotecas cliente, establece la variable de entorno GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES en 1.

Para generar el archivo de configuración con una credencial basada en un ejecutable, ejecuta el siguiente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • EXECUTABLE_COMMAND: es el comando completo, incluidos los argumentos, que se ejecuta para recuperar el token del asunto, en el siguiente formato: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (opcional) la duración en milisegundos para esperar que el archivo ejecutable se ejecute (el valor predeterminado es de 30 segundos).
  • EXECUTABLE_OUTPUT_FILE: (opcional) la ruta de archivo a las credenciales 3PI que genera el archivo ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de Auth verifican su existencia antes de ejecutar el archivo ejecutable.
  • WORKFORCE_POOL_USER_PROJECT: es el número de proyecto que se usa para la cuota y la facturación. La principal debe tener el permiso serviceusage.services.use en este proyecto.

Cuando ejecutas el comando, se produce un archivo de configuración de IdP de SAML similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Credenciales basadas en ejecutables para el modo interactivo de gcloud

Un ejecutable interactúa con el usuario a través de la línea de comandos.

En el comando anterior, reemplaza lo siguiente:

  • EXECUTABLE_OUTPUT_FILE: es la ruta al archivo que proporciona las credenciales que genera el archivo ejecutable (obligatorio).
  • EXECUTABLE_TIMEOUT: un valor de tiempo de espera distinto de cero también indica que el comando usa el modo interactivo (obligatorio).
    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

Estos campos son obligatorios para una respuesta exitosa, con la excepción de expiration_time. Si se omite el expiration_time, se tratará como la señal de que ejecutaremos el ejecutable de cualquier manera.

El ejecutable debe mostrar cualquier error en executable-output-file en el siguiente formato JSON:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos estos campos son obligatorios para una respuesta de error. Las bibliotecas cliente usan los códigos y campos de mensaje cuando se genera el error adecuado.

Los campos de retorno de comandos para una ejecución exitosa son los mismos, con los resultados de las credenciales basadas en ejecutables anteriores.

Las variables de entorno también son las mismas que las credenciales normales basadas en ejecutables.

Para generar una credencial interactiva basada en un ejecutable, agrega el parámetro --executable-interactive-timeout-millis.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de personal.
  • PROVIDER_ID: el ID del proveedor.
  • EXECUTABLE_COMMAND: es el comando completo, incluidos los argumentos, que se ejecuta a fin de recuperar el token del asunto, con el siguiente formato: --executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una duración en milisegundos que se esperará para que se ejecute el ejecutable.
  • EXECUTABLE_OUTPUT_FILE: una ruta de acceso de archivos a las credenciales de terceros que genera el ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de Auth primero comprueban esta ruta antes de ejecutar el archivo ejecutable.
  • WORKFORCE_POOL_USER_PROJECT: el número o ID del proyecto que se usa para la cuota y la facturación. La principal configuró el permiso serviceusage.services.use en este proyecto.

Cuando ejecutas el comando, se produce un archivo de configuración de IdP de SAML similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

Para acceder, ejecuta el siguiente comando:

gcloud auth login --cred-file=/path/to/config.json

Ten en cuenta que las CLI (gcloud, bq o gsutil) no admiten tipos de credenciales de origen ejecutable.

Para los flujos sin interfaz gráfica, gcloud usa de forma automática el siguiente alcance: https://www.googleapis.com/auth/cloud-platform. Luego, gcloud publica con transparencia tus credenciales en el extremo del servicio de tokens de seguridad, en el que se intercambia por tokens de acceso temporales de Google Cloud.

Ahora puedes ejecutar comandos de gcloud mediante la CLI de gcloud.

Usa las bibliotecas cliente de Google Cloud

Si usas una biblioteca cliente compatible, puedes configurar la biblioteca cliente para que genere credenciales de Google automáticamente. Cuando sea posible, te recomendamos que generes las credenciales automáticamente, para que no tengas que implementar el proceso de intercambio de tokens por tu cuenta.

La biblioteca cliente de Google Cloud para los grupos de personal se admite en los siguientes lenguajes: Node.js, Java, Python, Go y C++ (gRPC).

Para usar bibliotecas cliente con estos servicios o lenguajes, haz lo siguiente:

bq

Para autenticar con la federación de Workforce Identity, usa el comando gcloud auth login:

gcloud auth login --cred-file=FILEPATH.json

En el ejemplo anterior, FILEPATH es la ruta de acceso al archivo de configuración de credenciales.

La asistencia para la federación de Workforce Identity en bq está disponible en la versión 390.0.0 y posteriores de Google Cloud CLI.

C++

La mayoría de las bibliotecas cliente de Google Cloud para C++ admiten la federación de Workforce Identity mediante un objeto ChannelCredentials, que se crea mediante una llamada a grpc::GoogleDefaultCredentials(). Para inicializar esta credencial, debes compilar las bibliotecas cliente con la versión 1.42.0 o posterior de gRPC.

La biblioteca cliente de Cloud Storage para C++ usa la API de REST, no gRPC, por lo que no admite la federación de Workforce Identity.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

Para autenticar con la federación de Workforce Identity, usa el comando gcloud auth login:

gcloud auth login --cred-file=FILEPATH.json

En el ejemplo anterior, FILEPATH es la ruta de acceso al archivo de configuración de credenciales.

La asistencia para la federación de Workforce Identity en gcloud está disponible en la versión 392.0.0 y posteriores de Google Cloud CLI.

Go

Las bibliotecas cliente para Go admiten la federación de Workforce Identity si usan la versión v0.0.0-20211005180243-6b3c2da341f1 o posterior del módulo golang.org/x/oauth2.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

gsutil

Para autenticar mediante la federación de Workforce Identity, usa uno de los siguientes métodos:

Cuando uses gsutil junto con gcloud, accede con normalidad:

gcloud auth login --cred-file=FILEPATH.json

Cuando uses gsutil como una aplicación de línea de comandos independiente, edita el archivo .boto para incluir la siguiente sección:

[Credentials]
gs_external_account_file = FILEPATH

FILEPATH en ambos casos es la ruta de acceso al archivo de configuración de la credencial.

La asistencia para la federación de Workforce Identity en gsutil está disponible en la versión 379.0.0 y posteriores de Google Cloud CLI.

Java

Las bibliotecas cliente para Java admiten la federación de Workforce Identity si usan la versión 1.2.0 o posterior del artefacto com.google.auth:google-auth-library-oauth2-http.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Las bibliotecas cliente para Node.js admiten la federación de Workforce Identity. Debes usar la versión 7.10.0 o una posterior del paquete google-auth-library. A diferencia de los grupos de Workload Identity, los grupos de personal se asocian a una organización y no a un proyecto de Google Cloud. Cuando creas un objeto GoogleAuth, debes especificar un ID de proyecto. A fin de obtener más información, consulta el archivo README para el paquete google-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

Las bibliotecas cliente para Python admiten la federación de Workforce Identity si usan la versión 2.3.0 o posterior del paquete google-auth.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

En el ejemplo anterior, el valor project puede ser None si la biblioteca no puede descubrirlo automáticamente. Puedes pasarlo de forma explícita cuando usas una instancia de servicio (como en el ejemplo de cliente de almacenamiento) o configurarlo a través de la variable de entorno GOOGLE_CLOUD_PROJECT.

Para obtener más información, consulta la guía del usuario del paquete google-auth.

Usa la API de REST

Puedes llamar a la API del servicio de tokens de seguridad de Google Cloud a fin de intercambiar tus credenciales externas por tokens de acceso de Google Cloud.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

Reemplaza lo siguiente:

  • AUDIENCE: el nombre de recurso completo del proveedor que emite el token del asunto.
  • PROVIDER_ID: el ID del proveedor

  • SUBJECT_TOKEN_TYPE: configúralo con uno de los siguientes valores:

    • urn:ietf:params:oauth:token-type:id_token para tokens de ID de OIDC
    • urn:ietf:params:oauth:token-type:saml2 para aserciones de SAML

  • EXTERNAL_SUBJECT_TOKEN: el token emitido por el IdP que representa la identidad de la principal para la que se solicita el token de acceso. Nota: Si usas OIDC, el token tiene formato JWT.

  • BILLING_PROJECT_NUMBER: El número o ID del proyecto que se usa para la cuota y la facturación. La principal debe tener el permiso serviceusage.services.use en este proyecto.

La respuesta es similar al ejemplo a continuación:

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Administra sesiones con la CLI de gcloud

Los tokens temporales de Google Cloud que gcloud obtiene del extremo del servicio de tokens de seguridad vencen después de un intervalo especificado. Cuando el token está a punto de vencer, gcloud inspecciona el archivo de credenciales que proporcionaste y la validez de las credenciales que recibiste de tu IdP. Si tus credenciales aún son válidas, gcloud obtiene de forma transparente un nuevo token de acceso de Google Cloud y tu sesión actual se ejecuta sin interrupción.

Si tus credenciales expiraron, no se emiten nuevos tokens de Google Cloud y las llamadas que realizas con esas credenciales fallan. En este punto, debes volver a autenticarte.

Puedes finalizar tu sesión si ejecutas el siguiente comando:

gcloud auth revoke

gcloud admite varias sesiones de usuario. Para obtener la lista de sesiones, incluida la activa actualmente, ejecuta el siguiente comando:

gcloud auth list

El resultado del comando es similar al siguiente:

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

Para cambiar a una sesión diferente y configurarla como activa, ejecuta el siguiente comando:

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

¿Qué sigue?