Configura la federación de Workforce Identity

En esta guía, se describe cómo configurar la federación de Workforce Identity con un proveedor de identidad (IdP) compatible con OIDC o SAML 2.0.

Para obtener instrucciones específicas del IdP, consulta lo siguiente:

Antes de comenzar

Debes tener configurada una organización de Google Cloud.
Habilita las API de Identity and Access Management (IAM) and Resource Manager.
Habilita las API
Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando:
```
gcloud init
```
Nota: Si ya instalaste la CLI de gcloud, asegúrate de que tienes la versión más reciente mediante la ejecución de gcloud components update.
Tu IdP debe proporcionar información de autenticación firmada: los IdP de OIDC deben proporcionar un JWT y las respuestas del IdP de SAML deben estar firmadas.

Roles obligatorios

A fin de obtener los permisos que necesitas para configurar la federación de Workforce Identity, pídele a tu administrador que te otorgue el rol de IAM Workforce Identity Pool Admin (roles/iam.workforcePoolAdmin) en la organización. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Como alternativa, el rol básico Owner (roles/owner) también incluye permisos para configurar la federación de Workforce Identity. No deberías otorgar funciones básicas en un entorno de producción, pero puedes otorgarlas en un entorno de desarrollo o de prueba.

Configura la federación de Workforce Identity

Para configurar la federación de Workforce Identity, crea un grupo de Workforce Identity y un proveedor de grupo de Workforce Identity.

Crea un grupo de Workforce Identity

Para crear el grupo, ejecuta el siguiente comando:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --description="DESCRIPTION" \
    --location=global

Reemplaza lo siguiente:

WORKFORCE_POOL_ID: el ID del grupo de Workforce Identity
ORGANIZATION_ID: el ID numérico de la organización
DESCRIPTION: una descripción del grupo de Workforce Identity

Crea un proveedor de grupos de Workforce Identity

Puedes configurar los proveedores de grupos de Workforce Identity de las siguientes maneras:

OIDC

Para configurar el proveedor de OIDC, sigue estos pasos:

En tu IdP de OIDC, registra una aplicación nueva para la federación de Workforce Identity de Google Cloud. Toma nota del ID de cliente y el URI del emisor que proporcionó el IdP. Los usarás en este documento.
Si planeas configurar el acceso de usuario a la consola, agrega la siguiente URL de redireccionamiento a tu IdP de OIDC:
```
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
```
Para obtener información sobre cómo configurar el acceso de la consola (federada), consulta Configura el acceso del usuario a la consola (federada).
En Google Cloud, a fin de crear un proveedor de grupos de Workforce Identity de OIDC que use el flujo implícito para el acceso web, ejecuta el siguiente comando:

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
  --workforce-pool=WORKFORCE_POOL_ID \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --issuer-uri="ISSUER_URI" \
  --client-id="CLIENT_ID" \
  --web-sso-response-type="id-token" \
  --web-sso-assertion-claims-behavior="only-id-token-claims" \
  --attribute-mapping="ATTRIBUTE_MAPPING" \
  --attribute-condition="ATTRIBUTE_CONDITION" \
  --location=global

Reemplaza lo siguiente:

PROVIDER_ID: un ID de proveedor único.
WORKFORCE_POOL_ID: el ID del grupo de Workforce Identity al que se conecta el IdP
DISPLAY_NAME: un nombre visible opcional, fácil de usar para el proveedor, por ejemplo, idp-eu-employees
DESCRIPTION: una descripción opcional del proveedor de personal, por ejemplo, IdP for Partner Example Organization employees
ISSUER_URI: el URI de problema de OIDC del emisor, en un formato de URI válido, que comienza con https, por ejemplo, https://example.com/oidc
CLIENT_ID: El ID de cliente de OIDC que está registrado con el IdP de OIDC. El ID debe coincidir con la reclamación aud del JWT que emite el IdP
ATTRIBUTE_MAPPING: una asignación de atributo; por ejemplo, google.subject=assertion.sub, google.groups=[assertion.group1,assertion.group2], attribute.costcenter=assertion.costcenter
ATTRIBUTE_CONDITION: una condición de atributo; por ejemplo, assertion.role == 'gcp-users'

Con este comando, se asigna la subject, la lista de assertion.group1, assertion.group2 y costcenter en la aserción de OIDC a los atributos google.subject, google.groups y attribute.costcenter , respectivamente. La condición del atributo garantiza que solo los usuarios con funciones gcp-users puedan acceder mediante este proveedor de personal. Configura el proveedor para que solo incluya reclamaciones de token de ID para la asignación de atributos y la condición del atributo.

El prefijo gcp- está reservado y no se puede usar en un ID de grupo ni de proveedor.

Para la federación de OIDC, puedes usar assertion.NAME: una string igual al valor de la reclamación con nombre similar en la carga útil del token de ID.

SAML

Para configurar el proveedor de SAML, sigue estos pasos:

En tu IdP de SAML, registra una aplicación nueva para la federación de Workforce Identity de Google Cloud.
Configura el público para las aserciones de SAML. Por lo general, es el campo SP Entity ID en la configuración de IdP. Debes configurarla en la siguiente URL:
```
https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID
```
Si planeas configurar el acceso de usuario a la consola, agrega la siguiente URL de redireccionamiento a tu IdP de SAML:
```
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
```
Consulta Configura el acceso de usuario a la consola para obtener más detalles sobre la configuración del acceso a la consola.
En Google Cloud, crea un proveedor de grupos de Workforce Identity de SAML mediante el documento de metadatos de SAML de tu IdP. Puedes descargar el documento XML de metadatos de SAML desde tu IdP. El documento debe incluir al menos lo siguiente:
- Un ID de entidad de SAML para tu IdP
- La URL de inicio de sesión único para tu IdP
- Al menos una clave pública de firma.
Consulta los requisitos de las claves más adelante en esta guía para obtener información sobre las claves de firma.
```
gcloud iam workforce-pools providers create-saml PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --idp-metadata-path=METADATA_FILE_PATH \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --location=global
```
Reemplaza lo siguiente:
- PROVIDER_ID: el ID del proveedor.
- WORKFORCE_POOL_ID: el ID del grupo.
- DISPLAY_NAME: el nombre visible del proveedor; por ejemplo, idp-eu-employees
- DESCRIPTION: la descripción del proveedor de grupos de Workforce Identity; por ejemplo, IdP for Partner Example Organization EU employees.
- METADATA_FILE_PATH: la ruta de acceso del archivo de los metadatos de SAML
- ATTRIBUTE_MAPPING: la asignación de atributos; por ejemplo, google.subject=assertion.subject, google.groups=assertion.attributes.groupList, attribute.costcenter=assertion.attributes.costcenter[0]
- ATTRIBUTE_CONDITION: una condición de atributo; por ejemplo: assertion.attributes.role[0] == 'gcp-users'
El prefijo gcp- está reservado y no se puede usar en un ID de grupo ni de proveedor.

Para la federación de SAML, puedes usar las siguientes palabras clave en las condiciones y la asignación de atributos:

assertion.subject: una string igual al atributo NameID en la aserción de SAML.
assertion.attributes.NAME: una lista de strings igual a los valores de los atributos con nombre similar en la aserción de SAML.

Opcional: Acepta las aserciones de SAML encriptadas de tu IdP

Para permitir que tu IdP de SAML 2.0 produzca aserciones de SAML encriptadas que la federación de identidades de personal pueda aceptar, haz lo siguiente:

En la federación de identidades de personal, haz lo siguiente:

Crea un par de claves asimétricas para tu proveedor de grupos de identidades de personal.
Descargar un archivo de certificado que contenga la clave pública
Configura tu IdP de SAML para usar la clave pública a fin de encriptar las aserciones de SAML que emite.

En el IdP, haz lo siguiente:

Habilita la encriptación de aserciones, también conocida como encriptación de tokens.
Sube la clave pública que creaste en la federación de identidades de personal.
Confirma que tu IdP produzca aserciones de SAML encriptadas.

Ten en cuenta que, incluso con las claves de proveedor de encriptación de SAML configuradas, la federación de identidades de personal aún puede procesar una aserción de texto simple.

Crea claves de encriptación de aserciones de SAML de la federación de identidades de personal

En esta sección, se explica cómo crear un par de claves asimétricas que permite que la federación de identidades de personal acepte aserciones de SAML encriptadas.

Google Cloud usa la clave privada para desencriptar las aserciones de SAML que emite tu IdP. Para crear un par de claves asimétricas que se usarán con la encriptación SAML, ejecuta el siguiente comando. Para obtener más información, consulta Algoritmos de encriptación de SAML compatibles.

gcloud iam workforce-pools providers keys create KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION

Reemplaza lo siguiente:

KEY_ID: un nombre de clave que elijas
WORKFORCE_POOL_ID: el ID del grupo
PROVIDER_ID: el ID del proveedor
KEY_SPECIFICATION: la especificación de clave, que puede ser rsa-2048, rsa-3072 y rsa-4096.

Después de crear el par de claves, ejecuta el siguiente comando para descargar la clave pública en un archivo de certificado. Solo la federación de identidades de personal tiene acceso a la clave privada.

gcloud iam workforce-pools providers keys describe KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH

Reemplaza lo siguiente:

KEY_ID: el nombre de la clave
WORKFORCE_POOL_ID: el ID del grupo
PROVIDER_ID: el ID del proveedor
CERTIFICATE_PATH: la ruta en la que se escribe el certificado, por ejemplo, saml-certificate.cer o saml-certificate.pem

Configura tu IdP compatible con SAML 2.0 para emitir aserciones de SAML encriptadas

Configura tu IdP de SAML para usar el certificado público descargado del último paso a fin de encriptar las aserciones de SAML que emite. Consulta al equipo de IdP para obtener instrucciones específicas.

Después de configurar tu IdP para encriptar las aserciones de SAML, te recomendamos que te asegures de que las aserciones que genera en realidad estén encriptadas. Incluso con la encriptación de aserciones de SAML configurada, la federación de identidades de personal puede procesar aserciones de texto simple.

Borra claves de encriptación de la federación de identidades de personal

Para borrar claves de encriptación de SAML, ejecuta el siguiente comando:

  gcloud iam workforce-pools providers keys delete KEY_ID \
      --workforce-pool WORKFORCE_POOL_ID \
      --provider PROVIDER_ID \
      --location global

Reemplaza lo siguiente:

KEY_ID: el nombre de la clave
WORKFORCE_POOL_ID: el ID del grupo
PROVIDER_ID: el ID del proveedor

Algoritmos de encriptación SAML compatibles

La federación de identidades de personal admite los siguientes algoritmos de transporte de claves:

La federación de identidades de personal admite los siguientes algoritmos de encriptación de bloques:

Requisitos de la clave de firma de SAML X.509

Las siguientes especificaciones de claves se aplican a las claves de firma de SAML X.509:

Una clave pública RSA que está unida en un certificado X.509 v3.
A continuación, se detallan los requisitos de validez del certificado:
- notBefore: una marca de tiempo de no más de 7 días en el futuro
- notAfter: una marca de tiempo no más de 14 años en el futuro
Algoritmos recomendados:
- RSAwithSHA256 (tamaños de clave admitidos en bits: 2048, 3072, 4096)
- ECDSAwithSHA256

Un proveedor de grupos de Workforce Identity se puede configurar con un máximo de tres claves de firma en un momento determinado. Cuando existen varias claves, Google Cloud las itera y trata de usar cada clave no vencida para entregar una solicitud de intercambio de tokens.

Como práctica recomendada de seguridad, te recomendamos que no vuelvas a usar el mismo par de claves con otros servicios.

Administración de claves

Para actualizar las claves de firma del IdP, haz lo siguiente:

Crea un nuevo par de claves asimétricas y configura el proveedor de identidad SAML con el par de claves. En un principio, debes marcarlo como inactivo antes de activarlo en un paso posterior.
Descarga un documento XML de metadatos de SAML de tu IdP.

Nota: El documento debe contener la clave de firma existente y la clave de firma recién creada.
Actualiza el recurso del proveedor de grupos de Workforce Identity con el documento de metadatos de SAML. Cuando hay varias claves, Google Cloud itera a través de cada clave no vencida e intenta entregar una solicitud de intercambio de tokens.

Para actualizar el proveedor de grupos de Workforce Identity con los metadatos de SAML, ejecuta el siguiente comando.
```
gcloud iam workforce-pools providers update-saml PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --idp-metadata-path=SAML_METADATA_FILE_PATH \
    --location=global
```
Reemplaza lo siguiente:
- PROVIDER_ID: el ID del proveedor
- WORKFORCE_POOL_ID: el ID del grupo de Workforce Identity
- SAML_METADATA_FILE_PATH: la ruta de acceso al archivo de metadatos de SAML
Espera a que se complete la operación del paso anterior (la operación se marca como completada) y, luego, en el IdP de SAML, activa la clave de firma nueva. La clave de firma anterior se marca como inactiva. Las aserciones emitidas por el IdP se firman con la clave nueva.

Los siguientes pasos son opcionales, pero recomendamos realizarlos como práctica recomendada:

Borra la clave de firma antigua, ahora inactiva, de tu IdP.
Descarga el documento XML de metadatos de SAML de tu IdP.
Actualiza el recurso del proveedor de grupos de Workforce Identity con el documento de metadatos de SAML. Google Cloud rechaza las aserciones que estén firmadas con la clave de firma vencida. Para actualizar el documento, ejecuta el siguiente comando:
```
gcloud iam workforce-pools providers update-saml PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --idp-metadata-path=SAML_METADATA_FILE_PATH \
    --location=global
```
Reemplaza lo siguiente:
- PROVIDER_ID: el ID del proveedor
- WORKFORCE_POOL_ID: el ID del grupo de Workforce Identity
- SAML_METADATA_FILE_PATH: la ruta del archivo de metadatos SAML

Restricción de eliminación de claves

Google Cloud rechaza las aserciones firmadas con una clave borrada.

Representa a los usuarios del grupo de personal en las políticas de IAM

En la tabla siguiente, se muestran los identificadores principales que usas para otorgar roles a un solo usuario, a un grupo de usuarios, a los usuarios que realizan una reclamación particular o a todos los usuarios de un grupo de personal.

Identidades	Formato del identificador
Identidad única en un grupo de identidad de personal	`principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE`
Todas las identidades del personal de un grupo	`principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID`
Todas las identidades del personal con un valor de atributo específico	`principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE`
Todas las identidades en un grupo de identidad de personal	`principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*`

Otorga roles de IAM a las principales

Puedes otorgar roles a las principales, como identidades individuales, grupos de identidades o un grupo completo.

Para otorgar un rol en un proyecto a una principal, ejecuta el siguiente comando:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="ROLE" \
    --member="PRINCIPAL"

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto
ROLE: el rol que se otorgará
PRINCIPAL: la principal; consulta Representa usuarios de grupos de Workforce Identity en políticas de IAM.

En el siguiente ejemplo, el comando otorga Storage Admin (roles/storage.admin) a todas las identidades dentro del grupo GROUP_ID:

gcloud projects add-iam-policy-binding my-project \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

Para obtener más información sobre el formato de la principal, consulta Representa usuarios de grupos de Workforce Identity en las políticas de IAM.

¿Qué sigue?

Obtén credenciales de corta duración para la federación de Workforce Identity
Administra proveedores de grupos de Workforce Identity
Borra los usuarios de la federación de Workforce Identity y sus datos
Obtén información sobre qué productos de Google Cloud admiten la federación de Workforce Identity.
Configura el acceso de usuario a la consola (federada)