Aprovisionamiento de SCIM para la federación de identidades de personal

Si tu proveedor de identidad (IdP) admite el Sistema para la administración de identidades entre dominios (SCIM), puedes configurarlo para aprovisionar y administrar usuarios y grupos en Google Cloud.

Funciones

La compatibilidad con SCIM de la federación de identidades de personal proporciona las siguientes funciones:

  • Sincronización de identidades: Sincroniza usuarios y grupos de tu IdP externo con Google Cloud para mantener una vista integral de las identidades del personal.
  • Fuente principal de las reclamaciones: Cuando se habilita SCIM para un proveedor de personal, Google Cloud usa los usuarios y grupos de SCIM sincronizados como la fuente de información para los atributos de usuario y las membresías de grupos para la evaluación de políticas de IAM.
  • Autocompletado de identidad: Habilita el autocompletado de usuarios y grupos cuando se otorga acceso y se comparten recursos (como notebooks y agentes) en Gemini Enterprise.

Consideraciones

Cuando usas la compatibilidad con SCIM de la federación de identidades de personal, se aplican las siguientes consideraciones:

  • Debes configurar un grupo y un proveedor de Workforce Identity antes de configurar un usuario de SCIM.
  • Cada grupo de identidades de personal admite solo un usuario de SCIM, vinculado a un único proveedor. No puedes habilitar el uso de SCIM (--scim-usage) en ningún otro proveedor del mismo grupo. Para configurar un nuevo usuario de SCIM en el mismo grupo de Workforce Identity, primero debes borrar el existente. Para borrar un usuario de SCIM, usa uno de los siguientes métodos:
    • Borrado no definitivo (predeterminado): Cuando borras un usuario de SCIM, se inicia un período de borrado no definitivo de 30 días. Durante este tiempo, el usuario está oculto y no se puede usar, y no puedes crear un usuario de SCIM nuevo en el mismo grupo de identidades de personal.
    • Borrado definitivo: Para borrar de forma permanente y de inmediato un usuario de SCIM, usa la marca --hard-delete con el comando delete. Esta acción es irreversible y te permite crear un nuevo usuario de SCIM en el mismo grupo de identidades del personal de inmediato sin esperar el período de retención de 30 días. Como alternativa, puedes crear un grupo de identidades de personal nuevo y un usuario de SCIM nuevo, o bien usar un grupo de identidades de personal que no se haya configurado antes con un usuario de SCIM.
  • Modos de uso de SCIM (--scim-usage):
    • enabled-for-groups (Gemini Enterprise): Usa grupos sincronizados con SCIM para la autorización de IAM y la evaluación de políticas. Los atributos de usuario se siguen obteniendo de los tokens de acceso. Solo se evalúan las asignaciones de google.subject y google.group.
    • enabled-for-users-groups (Gemini Enterprise y Looker): Usa los datos de usuarios y grupos sincronizados con SCIM como la fuente de reclamaciones para la autorización de IAM en los flujos de trabajo de acceso web y de OAuth. Evalúa google.subject, google.group y todas las reclamaciones de usuario configuradas (como google.display_name, google.profile_photo, google.email, google.posix_username y attribute.<var>KEY</var> personalizada).
  • Exclusividad mutua: El parámetro de configuración --scim-usage=enabled-for-users-groups es mutuamente excluyente con los atributos adicionales (extra_attributes_oauth2_client) y los atributos extendidos (extended_attributes_oauth2_client).
  • Cuando usas SCIM, asignas atributos tanto en el proveedor del grupo de identidades de personal como en el inquilino de SCIM. El atributo google.subject debe hacer referencia de forma inequívoca a las mismas identidades. Especifica google.subject en el proveedor de grupos de identidades de personal con la marca --attribute-mapping y en el usuario de SCIM con la marca --claim-mapping. Asignar valores de identidad no únicos puede hacer que Google Cloud trate diferentes identidades de IdP como la misma identidad. Como resultado, el acceso que se otorga a una identidad de usuario o grupo puede extenderse a otras, pero revocar el acceso de una podría no quitarlo de todas.
  • Si habilitas el uso de SCIM en un proveedor sin un usuario de SCIM adjunto, los intentos de acceso fallarán porque Google Cloud no puede encontrar un usuario de SCIM para ese proveedor.
  • Aplicación de la unicidad: Google Cloud Valida y aplica la unicidad en los atributos asignados a google.subject (usuarios) y google.group (grupos) en un usuario de SCIM. Si los atributos asignados aprovisionados por tu IdP generan valores duplicados para google.subject o google.group durante la sincronización, el aprovisionamiento falla con un error de HTTP 409 Conflict. Si un atributo asignado se evalúa como nulo o vacío, el aprovisionamiento falla con un error de HTTP 400 Bad Request.
  • Límites de tamaño de los atributos: El tamaño máximo de los atributos de usuario asignados serializados (sin incluir google.group) es de 16 kB. Si los atributos asignados superan este límite, los intentos de acceso fallarán.
  • Límite de tokens de SCIM: Cada usuario de SCIM admite un máximo de dos tokens de SCIM (por ejemplo, para admitir la rotación de tokens sin tiempo de inactividad). Si tienes dos tokens, borra uno existente antes de crear uno nuevo.
  • La API de SCIM (iamscim.googleapis.com) está sujeta a cuotas de frecuencia que difieren de las cuotas de la API de recursos de IAM estándar. De forma predeterminada, las solicitudes de escritura y lectura se limitan a 3,000 solicitudes por usuario de SCIM por organización por minuto. Para obtener más información, consulta Cuotas y límites.

Asignación de reclamaciones

Cuando configuras SCIM, defines asignaciones de reclamaciones (--claim-mapping) en el usuario de SCIM para asignar atributos de usuario y grupo de SCIM a atributos de Google.

Atributos de Google Cloud compatibles para la asignación de reclamaciones

En la siguiente tabla, se enumeran los atributos de Google Cloud que puedes asignar en tu usuario de SCIM (--claim-mapping) con Common Expression Language (CEL):

AtributoGoogle Cloud Requisito Descripción Expresiones y límites admitidos
google.subject Obligatorio

Es el identificador único del usuario que se autentica.

El atributo de IdP subyacente que se usa para propagar google.subject debe ser idéntico tanto en la asignación del proveedor (--attribute-mapping) como en el usuario de SCIM (--claim-mapping). Si estas asignaciones no son coherentes, es posible que los usuarios puedan acceder, pero no se los reconocerá como miembros de los grupos aprovisionados por SCIM.

Se restringe a las siguientes expresiones base (o con .lowerAscii()):
  • user.externalId
  • user.userName
  • user.emails[0].value

Longitud máxima: 127 bytes.

Nota: Esta asignación es inmutable una vez que se crea el usuario de SCIM. Para actualizarla, debes borrar de forma definitiva y volver a crear el usuario de SCIM.

google.group Obligatorio para los grupos de SCIM Es el identificador único de la membresía del grupo sincronizada con SCIM. Se restringe a las siguientes expresiones base (o con .lowerAscii()):
  • group.externalId
  • group.displayName

Nota: Esta asignación es inmutable una vez que se crea el usuario de SCIM. Para actualizarla, debes borrar de forma definitiva y volver a crear el usuario de SCIM.

google.display_name Opcional Es un atributo que establece el nombre del usuario que accedió a la consola de Google Cloud . No se puede usar en las políticas de permisos de IAM. Se asigna a un atributo de cadena (como user.displayName o user.name.formatted). Longitud máxima: 100 bytes.
google.profile_photo Opcional Es una URL de la foto en miniatura del usuario que se puede ver como su foto de perfil en la consola de Google Cloud . No se puede usar en las políticas de permisos de IAM. Debe evaluarse como una cadena de URL válida (como user.photos.filter(p, p.type == 'thumbnail')[0].value o user.photos[0].value).
google.email Opcional Es un atributo que se usa para asignar direcciones de correo electrónico del IdP a productos integrados con la integración de clientes de OAuth de la federación de identidades de personal. No se puede usar en las políticas de permisos de IAM. Se asigna a un atributo de correo electrónico (como user.emails.filter(e, e.type == 'work')[0].value o user.emails[0].value).
google.posix_username Opcional Es una cadena de nombre de usuario única que cumple con POSIX y se usa para SSH en el navegador y el Acceso al SO con la federación de identidades de personal. Este atributo no se puede usar en las políticas de permiso de IAM. La longitud máxima es de 32 caracteres.
attribute.KEY Opcional

Atributos personalizados de tu IdP que puedes usar para definir tu estrategia de autorización en una política de permisos de IAM. Reemplaza KEY por el nombre del atributo que quieras usar.

Por ejemplo, puedes definir un atributo personalizado, como costcenter = "1234", y hacer referencia a él con principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234. Otorgar acceso a este identificador de principal otorga acceso a todas las identidades configuradas en el IdP con ese centro de costo.

Hasta 50 reglas de asignación de atributos personalizados Tamaño máximo por regla: 256 caracteres.

Comportamiento según el uso de SCIM del proveedor (--scim-usage)

La evaluación de las asignaciones de reclamaciones de SCIM depende del modo --scim-usage configurado en el proveedor de grupos de Workload Identity:

  • enabled-for-groups (Gemini Enterprise): Solo se evalúan las asignaciones de google.subject y google.group. Se ignoran las asignaciones de reclamaciones de usuarios adicionales en --claim-mapping.
  • enabled-for-users-groups (Gemini Enterprise y Looker): Evalúa google.subject, google.group y todas las reclamaciones de usuario configuradas (como google.display_name, google.profile_photo, google.email, google.posix_username y attribute.<var>KEY</var> personalizada). Google Cloud usa reclamaciones de SCIM en los siguientes flujos de trabajo de acceso:
    • Acceso web: Cuando los usuarios acceden a Gemini Enterprise, Google Cloud usa las reclamaciones de usuarios y grupos sincronizadas con SCIM. Cuando los usuarios acceden a otros productos, como la consola de Google Cloud , Google Cloud usa los atributos asignados desde el token de IdP por la marca --attribute-mapping del proveedor.
    • Acceso con OAuth: Cuando los usuarios acceden a las aplicaciones de Gemini Enterprise y Looker que usan el flujo de OAuth de la federación de identidades de personal, Google Cloud usa las reclamaciones de usuarios y grupos sincronizadas con SCIM. Cuando los usuarios acceden a otras aplicaciones, Google Cloud usa los atributos asignados desde el token de IdP por la marca --attribute-mapping del proveedor.

Ejemplos de asignaciones para la coherencia del sujeto

Como se describe en Atributos admitidos para la asignación de reclamaciones, el atributo del IdP subyacente que se usa para propagar google.subject debe ser idéntico en la asignación del proveedor (--attribute-mapping) y el inquilino de SCIM (--claim-mapping). En la siguiente tabla, se muestran ejemplos de referencia:

Atributo de Google Asignación de proveedores de grupos de identidades de personal Asignación de usuarios de SCIM (SCIM)
google.subject assertion.oid (Entra ID) user.externalId
google.subject assertion.sub (Okta) user.externalId
google.subject assertion.preferred_username user.userName
google.subject assertion.preferred_username.lowerAscii() user.userName.lowerAscii()
google.subject assertion.email user.emails[0].value
google.subject assertion.email.lowerAscii() user.emails[0].value.lowerAscii()

Extremos compatibles y no compatibles

El servicio de SCIM de IAM (iamscim.googleapis.com) implementa el protocolo SCIM 2.0 (RFC 7644) y entrega solicitudes en el baseUri de tu usuario de SCIM:

https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID

En este URI, SCIM_TENANT_UID es el identificador único de tu usuario de SCIM.

El servicio de SCIM de IAM admite los siguientes extremos del protocolo de SCIM estándar en relación con el inquilino baseUri:

  • /Users: Administra los recursos de los usuarios. Operaciones admitidas: Create, Get, Update, Delete, Patch y Put.

  • /Groups: Administra los recursos del grupo. Operaciones admitidas: Create, Get, Update, Delete y Patch. El método PUT no se admite para los grupos.

  • /Schemas: Recupera información del esquema.

  • /ServiceProviderConfig: Recupera la configuración del proveedor de servicios.

No se admiten los siguientes extremos del protocolo SCIM:

  • /Me

  • /Bulk

  • /Search

  • /ResourceTypes

Limitaciones

En las siguientes secciones, se describen las limitaciones y desviaciones de la implementación de SCIM de la federación de identidades de personal de las especificaciones de SCIM (RFC 7643 y 7644).

Limitaciones de las funciones del protocolo

  • Compatibilidad con filtros: Cuando enumeras usuarios o grupos con los extremos /Users o /Groups, las expresiones de filtro solo admiten el operador eq (igual a). Puedes combinar varios filtros eq con and. No se admiten otros operadores de filtro de SCIM, como co (contiene) o sw (comienza con).

  • Paginación: La API de SCIM de IAM no admite la paginación estándar para enumerar usuarios o grupos.

    • startIndex: Este parámetro siempre es 1. La API devuelve hasta 100 resultados, independientemente del valor que proporciones para startIndex.

    • itemsPerPage: La cantidad máxima de recursos que se devuelven en una sola respuesta es 100.

    • totalResults: la API no devuelve el recuento total real de recursos coincidentes. El campo totalResults de la respuesta siempre es igual a la cantidad de elementos que se devuelven en esa respuesta, con un máximo de 100.

  • Obtener grupo y enumerar grupos sin filtro: Las APIs de GetGroup y ListGroups devuelven una lista de miembros vacía. Para recuperar miembros de un grupo específico, usa la API de ListGroups con un filtro de miembros.

  • Respuesta JSON que no cumple con los requisitos y tiene tokens no válidos: Las solicitudes que contienen un token de API no válido devuelven un código de estado HTTP 401 de Google Cloud. La respuesta no es un JSON válido, como lo requiere la especificación de SCIM.

Limitaciones de comportamiento de SCIM

  • Identificadores inmutables: Los valores de los atributos de SCIM que se asignan a google.subject o google.group se tratan como identificadores inmutables dentro de Google Cloud. Si necesitas cambiar estos valores, debes borrar de forma permanente el usuario o grupo de tu IdP y, luego, volver a crearlo con el valor nuevo.

  • Identificadores únicos y no vacíos: Google Cloud aplica la unicidad en los valores asignados a google.subject y google.group en un usuario de SCIM. La sincronización de los atributos asignados que generan valores duplicados para google.subject o google.group falla con un error de HTTP 409 Conflict. Los atributos asignados que se evalúan como nulos o vacíos fallan con un error de HTTP 400 Bad Request.

  • Requisito de correo electrónico único: Para que la sincronización de SCIM se realice correctamente, cada usuario debe tener exactamente una dirección de correo electrónico del tipo work. El aprovisionamiento o las actualizaciones fallarán si tu IdP envía varios correos electrónicos o si el único correo electrónico proporcionado no es del tipo work.

  • Transformaciones que no distinguen mayúsculas de minúsculas: Se admiten transformaciones limitadas de Common Expression Language (CEL) para las asignaciones de reclamaciones de SCIM. Solo se admite .lowerAscii() para las comparaciones que no distinguen mayúsculas de minúsculas en user.userName y user.emails[0].value.

Limitaciones de los atributos

En las siguientes secciones, se describe la compatibilidad de atributos para los usuarios, los grupos y la extensión del esquema de usuario empresarial.

Atributos de usuario

En la siguiente tabla, se enumeran los atributos de usuario y su disponibilidad en las reclamaciones de la federación de identidades de personal:

Atributo Atributos secundarios Compatible con el aprovisionamiento de SCIM Limitaciones Compatible con --claim-mapping
userName N/A Sí N/A Sí
name formatted, familyName, givenName, middleName, honorificPrefix, honorificSuffix Sí N/A Sí
displayName N/A Sí N/A Sí
nickName N/A Sí N/A Sí
profileUrl N/A Sí N/A Sí
title N/A Sí N/A Sí
userType N/A Sí N/A Sí
preferredLanguage N/A Sí N/A Sí
locale N/A Sí N/A Sí
timezone N/A Sí N/A Sí
active N/A Sí N/A Sí
password N/A No N/A No
emails display, type, value, primary Sí Solo se admite el tipo de correo electrónico work. Sí
phoneNumbers display, type, value, primary Sí N/A Sí
ims display, type, value Sí N/A Sí
photos display, type, value Sí N/A Sí
addresses formatted, streetAddress, locality, region, postalCode, country Sí N/A Sí
groups N/A No N/A No
entitlements display, type, value Sí N/A Sí
roles type, value Sí display no es compatible. Sí
x509Certificates type, value Sí display no es compatible. No

Atributos del grupo

En la siguiente tabla, se enumeran los atributos de grupo y su disponibilidad en las reclamaciones de la federación de identidades de personal:

Atributo Atributos secundarios admitidos Compatible con --claim-mapping
displayName N/A Sí
externalId N/A Sí
members value, type, $ref, display No

Atributos de extensión del esquema de usuario empresarial

En la siguiente tabla, se detalla la compatibilidad con la extensión del esquema de usuario empresarial:

Atributo Atributos secundarios admitidos Compatible con --claim-mapping
employeeNumber N/A Sí
costCenter N/A Sí
organization N/A Sí
division N/A Sí
department N/A Sí
manager value, $ref, displayName Sí ($ref solo se admite en el aprovisionamiento de SCIM, no en --claim-mapping)

¿Qué sigue?