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.

Los métodos que se describen en esta guía se pueden usar en máquinas sin interfaz gráfica.

Puedes obtener tokens de corta duración mediante este proceso de alto nivel, que se describe en detalle más adelante en este documento:

  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 identidades de personal o, para obtener instrucciones específicas del IdP, consulta las siguientes guías:

    Anota el ID de tu grupo de identidades de personal y el ID del proveedor de este.

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

  3. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  4. 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 gcloud CLI, 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 gcloud CLI mediante la marca --activate. 

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

Reemplaza lo siguiente:

  • WORKFORCE_POOL_ID: el ID del grupo de la identidad de personal
  • WORKFORCE_PROVIDER_ID: El ID del proveedor del grupo de identidades de personal
  • LOGIN_CONFIG_FILE: Una ruta de acceso al archivo de configuración de acceso 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 IdP que se configuró en el proveedor del grupo de identidad de personal. 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/WORKFORCE_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

Cuando usas credenciales provistas por el archivo, 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/WORKFORCE_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 la identidad de personal
  • WORKFORCE_PROVIDER_ID: El ID del proveedor del grupo de identidades de personal
  • 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/WORKFORCE_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

Cuando usas 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 un 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/WORKFORCE_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 Workforce Identity.
  • WORKFORCE_PROVIDER_ID: El ID del proveedor de grupo de identidades de personal.
  • 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/WORKFORCE_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

Cuando usas 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 establecen las siguientes variables de entorno cuando se ejecuta el ejecutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: el campo de público de la configuración de las credenciales. Esta variable siempre se establece.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: el tipo de token del asunto esperado. Esta variable siempre se establece.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: ubicación del archivo de salida de la configuración de credenciales. Esta variable 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/WORKFORCE_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 Workforce Identity.
  • WORKFORCE_PROVIDER_ID: El ID del proveedor de grupo de identidades de personal.
  • 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 Es una duración en milisegundos que se esperará para que se ejecute el ejecutable (el valor predeterminado es de 30 segundos).
  • EXECUTABLE_OUTPUT_FILE: Opcional Es una ruta de acceso 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/WORKFORCE_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

Cuando usas credenciales interactivas de origen ejecutable, 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 para las credenciales interactivas y no interactivas con origen ejecutable.

Las variables de entorno también son las mismas para las credenciales interactivas y no interactivas 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/WORKFORCE_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 Workforce Identity.
  • WORKFORCE_PROVIDER_ID: El ID del proveedor de grupo de identidades de personal.
  • 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: Es una ruta de acceso a las credenciales de terceros que genera el ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de autenticación 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/WORKFORCE_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",
    }
  }
}

El campo timeout_millis se muestra porque, en algunos casos, un ejecutable interactivo también puede ejecutarse en modo no interactivo. En el modo interactivo, el comando muestra un tiempo de espera predeterminado.

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/WORKFORCE_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 Workforce Identity.
  • WORKFORCE_PROVIDER_ID: El ID del proveedor de grupo de identidades de personal.
  • 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 HTTP "GET". La respuesta debe ser una aserción de SAML [codificada en base64](https://toolbox.googleapps.com/apps/encode_decode/) o JSON que contenga una aserción de SAML codificada en base64. Para usar credenciales basadas en URL, usa la marca `--credential-source-url`: ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identidad de la fuerza laboral. * WORKFORCE_PROVIDER_ID: El ID del proveedor del grupo de identidades de personal. * CREDENTIAL_URL: La 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 el permiso "serviceusage.services.use" 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 establecen las siguientes variables de entorno cuando se ejecuta el ejecutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: el campo de público de la configuración de las credenciales. Esta variable siempre se establece.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: el tipo de token del asunto esperado. Esta variable siempre se establece.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: ubicación del archivo de salida de la configuración de credenciales. Esta variable 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/WORKFORCE_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 Workforce Identity.
  • WORKFORCE_PROVIDER_ID: El ID del proveedor de grupo de identidades de personal.
  • 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 Es la duración en milisegundos que se esperará para que se ejecute el ejecutable (el valor predeterminado es de 30 segundos).
  • EXECUTABLE_OUTPUT_FILE: Opcional Es la ruta de acceso a las credenciales de identidad de terceros (3PI) que genera el ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de autorización 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/WORKFORCE_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

Cuando usas credenciales basadas en ejecutables para el modo interactivo de gcloud, un ejecutable interactúa con el usuario a través de la interfaz de línea de comandos.

En el comando anterior, reemplaza lo siguiente:

  • EXECUTABLE_OUTPUT_FILE: Obligatorio. Es la ruta de acceso al archivo que proporciona las credenciales que genera el archivo ejecutable.
  • EXECUTABLE_TIMEOUT: Obligatorio. Un valor de tiempo de espera distinto de cero también indica que el comando usa el modo interactivo.
    {
      "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. Cuando se omite expiration_time, el ejecutable se sigue ejecutando.

El ejecutable debe mostrar cualquier error en executable-output-file en el siguiente formato JSON. Cuando el ejecutable informa un error, estos campos son obligatorios. Las bibliotecas cliente usan los campos de código y mensaje cuando se genera el error adecuado.

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

Cuando se ejecuta correctamente, el comando muestra los mismos campos que las credenciales no interactivas con origen ejecutable.

Las variables de entorno también son las mismas que las credenciales no interactivas 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/WORKFORCE_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 Workforce Identity.
  • WORKFORCE_PROVIDER_ID: El ID del proveedor de grupo de identidades de personal.
  • 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: Es una ruta de acceso a las credenciales de terceros que genera el ejecutable. Esto es útil para almacenar en caché las credenciales. Las bibliotecas de autenticación 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 SAML similar al siguiente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>WORKFORCE_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 ni gcloud CLI ni la herramienta de línea de comandos de bq admiten tipos de credenciales de origen ejecutable.

Para los flujos sin interfaz gráfica, gcloud CLI usa automáticamente el siguiente alcance: https://www.googleapis.com/auth/cloud-platform. Luego, gcloud CLI publica con transparencia tus credenciales en el extremo del servicio de tokens de seguridad, en el que se intercambian 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:

Herramienta de bq

Para autenticar con la federación de identidades de personal, 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 compatibilidad con la federación de Workforce Identity en la herramienta de 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 identidades de personal con un objeto ChannelCredentials, que se crea por medio de 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.

Las bibliotecas cliente de Cloud Storage para C++ usan la API de REST, no gRPC, por lo que no admiten 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 identidades de personal, usa el comando gcloud auth login:

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

Reemplaza FILEPATH por la ruta de acceso al archivo de configuración de credenciales.

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

Go

Las bibliotecas cliente de Cloud para Go admiten la federación de identidades de personal cuando usas la versión v0.0.0-20211005180243-6b3c2da341f1 o una 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)
}

Java

Las bibliotecas cliente de Cloud para Java admiten la federación de Workforce Identity cuando usas 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 de Cloud para Node.js admiten la federación de Workforce Identity cuando usas 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 identidad 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 del proyecto. Para obtener más información, consulta el archivo README del 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 de Cloud para Python admiten la federación de identidades de personal cuando usas 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 código de ejemplo, el valor project puede ser None si la biblioteca no puede descubrir automáticamente el ID del proyecto. Puedes pasar el ID del proyecto de forma explícita cuando usas una instancia de servicio, como lo hace el ejemplo del cliente de almacenamiento, o configurar el ID del proyecto 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

Para llamar a la API del servicio de tokens de seguridad de Google Cloud y cambiar tus credenciales externas por tokens de acceso de Google Cloud, ejecuta el siguiente comando:

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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.
  • WORKFORCE_POOL_ID: el ID del grupo de la identidad de personal
  • WORKFORCE_PROVIDER_ID: El ID del proveedor del grupo de identidades de personal

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

    Si configuraste un proveedor de OIDC, el token debe tener 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 CLI 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 CLI 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 CLI 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 que está 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?