Soluciona problemas de la federación de identidades de personal

En esta página, se muestra cómo resolver problemas habituales con la federación de identidades de personal.

Inspecciona la respuesta del IdP

En esta sección, se muestra cómo inspeccionar la respuesta de tu proveedor de identidad (IdP) para solucionar los problemas enumerados en este documento.

Acceso basado en el navegador

Para inspeccionar la respuesta que muestra tu IdP, genera un archivo HAR con la herramienta que elijas. Por ejemplo, puedes usar HAR Analyzer de la Caja de herramientas para administradores de Google, que proporciona instrucciones a fin de generar un archivo HAR y las herramientas para subirlo y analizarlo.

SAML

Para inspeccionar la respuesta del IdP de SAML, sigue estos pasos:

  1. Ubica el valor del parámetro de la solicitud SAMLResponse en el archivo HAR que se registra en la URL con la ruta de acceso /signin-callback.
  2. Decodifícalo mediante la herramienta que prefieras, por ejemplo, puedes usar la codificación o decodificación de la Caja de herramientas para administradores de Google.

OIDC

Para inspeccionar la respuesta del IdP de OIDC, sigue estos pasos. Este enfoque no funciona con el flujo de código.

  1. Busca el parámetro de solicitud id_token en el archivo HAR que se registra en una URL con la ruta de acceso /signin-callback.
  2. Decodifícala mediante la herramienta de depuración de JWT que elijas.

gcloud CLI

Para inspeccionar la respuesta de tu IdP cuando usas la gcloud CLI, copia el contenido del archivo que pasaste en la marca --credential-source-file cuando ejecutaste el comando gcloud iam workforce-pools create-cred-config y, luego, realiza los siguientes pasos:

SAML

Para decodificar la respuesta del IdP de SAML mediante la herramienta que prefieras, por ejemplo, puedes usar la codificación o decodificación de la Caja de herramientas para administradores de Google.

OIDC

Decodifica la respuesta del IdP de OIDC con la herramienta de depuración de JWT que elijas.

Revisión de los registros

Para determinar si Google Cloud se comunica con tu IdP y revisar la información de la transacción, puedes inspeccionar los registros de auditoría de Cloud.

Para ver ejemplos de registros, consulta Ejemplos de registros de auditoría.

Errores de administración de grupos de trabajadores y proveedores

En esta sección, se proporcionan sugerencias para corregir errores comunes que pueden surgir cuando administras grupos y proveedores.

Errores generales de asignación de atributos

Para solucionar problemas de asignación de atributos del proveedor de grupos de identidades de personal, haz lo siguiente:

  • Inspecciona los atributos, también conocidos como reclamaciones, en la configuración de tu IdP. Verifica cómo tus asignaciones de atributos convierten los atributos de IdP en atributos de Google Cloud y cómo tus condiciones evalúan esos atributos para permitir o denegar el acceso en la consola de Google Cloud .

    1. Asegúrate de tener el rol de editor de grupos de trabajadores de IAM (roles/iam.workforcePoolEditor).
    2. Para habilitar el flujo de acceso basado en el navegador para la federación de identidades de personal, agrega https://auth.cloud.google/signin-callback/locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID a la lista de URIs de redireccionamiento permitidos de tu IdP.

    3. En la consola de Google Cloud , ve a Grupos de identidades de personal.

      Ir a Grupos de identidades de personal
    4. En la lista de grupos, haz clic en el nombre del grupo que quieres verificar.
    5. En la página Detalles del grupo de personal, haz clic en el nombre del IdP que deseas verificar.
    6. En la página Detalles del proveedor, haz clic en Depurar token de IdP.
    7. En el cuadro de diálogo Acceder, accede a tu IdP como usuario de prueba.

    En la página Valida los atributos de tu proveedor, se muestran los atributos asignados y el resultado de tu condición de atributo.

    En la sección Atributos asignados de tu token de IdP, se muestra cómo se propagan los atributos de Google, como google.subject, desde el token de tu IdP según tu configuración de asignación. Si una asignación es incorrecta, aparecerá un ícono de error.

    En la sección Condición de atributo, se muestra el resultado booleano de tu condición. Si la condición se evalúa como false, se bloquea el acceso.

    Para ver el token de aserción completo, haz clic en Ver token completo. Aquí se muestra el objeto JSON sin procesar de tu IdP. Haz referencia a una propiedad de nivel superior en tus asignaciones con el formato assertion.PROPERTY_NAME.

    Para corregir cualquier error, puedes editar la configuración:

    1. En la página Valida los atributos de tu proveedor, haz clic en Editar.
    2. Realiza los cambios necesarios.
    3. Para iniciar una prueba nueva y ver los resultados actualizados, haz clic en Guardar y volver a recuperar el token.

  • Inspecciona los tokens que se generan desde tu IdP. Para aprender a generar un token desde tu IdP, consulta la documentación de tu IdP.

  • Revisa el registro de auditoría detallado de la federación de identidades de personal en los Registros de auditoría de Cloud.

El registro de auditoría detallado registra los errores de autenticación y autorización junto con las reclamaciones que recibió la federación de identidades de personal.

Puedes habilitar el registro de auditoría detallado cuando creas tu proveedor de grupos de Workforce Identity. Para habilitar el registro de auditoría detallado, agrega la marca --detailed-audit-logging cuando crees tu proveedor de grupos de Workforce Identity.

Permiso denegado

Este error se produce cuando el usuario que intenta configurar la federación de identidades de personal no tiene el rol de Administrador de grupos de trabajadores de IAM (roles/iam.workforcePoolAdmin).

INVALID_ARGUMENT: falta la configuración de inicio de sesión único de OIDC en la Web

El siguiente error ocurre cuando los campos web-sso-response-type y web-sso-assertion-claims-behavior no están configurados cuando se crea un proveedor de grupos de identidades de personal de OIDC:

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

Para resolver este error, sigue los pasos de la sección Crea un proveedor a fin de configurar los campos de forma adecuada cuando crees el proveedor de grupos de identidades de personal de OIDC.

Se superó el límite de frecuencia (HTTP 429)

Este error se produce cuando tu organización agotó su cuota para el intercambio de tokens del grupo de personal (sts.googleapis.com/workforce_requests).

Esta cuota se aplica a cada organización y, de forma predeterminada, es de 1,000 solicitudes por minuto. Debido a que esta cuota se comparte entre todos los grupos de personal, proveedores, usuarios y cargas de trabajo automatizadas de tu organización, un solo cliente de alta frecuencia puede causar errores HTTP 429 en toda la organización, incluso para los administradores. Para obtener más información, consulta Cuotas y límites.

Antes de comenzar

Si accediste a través de la federación de identidades de personal, es posible que se limiten los comandos de Google Cloud CLI y las sesiones de acceso nuevas a la consola de Google Cloud . Para realizar estos pasos cuando se exceda tu cuota, usa una cuenta de administrador que no se autentique a través de la federación de identidades de personal, como una cuenta de administrador avanzado de Cloud Identity de acceso de emergencia.

Paso 1: Confirma que se agotó la cuota

En la consola de Google Cloud , ve a IAM y administración > Cuotas, configura el selector de recursos en tu organización (no en un proyecto) y selecciona Solicitudes de intercambio de tokens del grupo de personal.

Ir a Cuotas de IAM y administración

Paso 2: Identifica la fuente del tráfico

Los intercambios de tokens limitados se rechazan antes de que se validen las credenciales, por lo que no aparecen en los Registros de auditoría de Cloud. Para identificar el origen del tráfico, usa uno de los siguientes métodos:

  • Revisa los registros de acceso de tu IdP: En tu proveedor de identidad, como el registro del sistema de Okta o los registros de acceso de Microsoft Entra ID, busca una aplicación, una principal de servicio o una cuenta de usuario específicas que emitan tokens con una frecuencia inusualmente alta.
  • Revisa las configuraciones de las cargas de trabajo: Verifica tus trabajos automatizados, canalizaciones de CI/CD, agentes de daemon y cargas de trabajo de GKE configurados con un archivo de configuración de credenciales de personal.

Paso 3: Contén el tráfico

Elige la opción que resuelva el tráfico con la menor cantidad de interrupciones para tu personal:

AcciónEfecto en tus usuarios
Detén la carga de trabajo (reduce la implementación a cero, borra el trabajo o revoca el cliente en tu IdP). Ninguno Se recomienda cuando puedes identificar la carga de trabajo específica.
Inhabilitar el acceso programático en el grupo de personal Bloquea todo el intercambio de tokens programático para el grupo, incluidos gcloud y kubectl para tus usuarios humanos. Google Cloud El acceso a la consola sigue funcionando.

Se recomienda cuando no puedes ubicar la carga de trabajo de inmediato.
Inhabilita el grupo o el proveedor Bloquea la autenticación para todo el grupo o proveedor de personal.

Para inhabilitar el acceso programático, haz lo siguiente:

gcloud iam workforce-pools update WORKFORCE_POOL_ID \
    --location=global \
    --disable-programmatic-signin

Después de detener la carga de trabajo problemática, vuelve a habilitar el acceso programático ejecutando el comando con la marca --no-disable-programmatic-signin.

Paso 4: Evita que se repita el problema

  • Migra las cargas de trabajo automatizadas a la federación de identidades para cargas de trabajo.
  • Vuelve a intentar las solicitudes limitadas con retirada exponencial y Jitter. Los bucles de reintentos ajustados profundizan la saturación y extienden la interrupción.
  • Alerta al 80% de tu cuota para que recibas una advertencia antes de la saturación.
  • Si tu demanda de estado estable supera el límite con regularidad, te recomendamos que solicites un aumento de cuota a través de Atención al cliente de Cloud antes de que lo necesites.

Errores de acceso

En esta sección, se proporcionan sugerencias para corregir errores comunes que puede encontrar un usuario de federación de identidades de personal cuando accede.

Errores de acceso comunes

La condición del atributo rechaza la credencial determinada

Este error ocurre cuando no se cumplió la condición de atributo establecida en el proveedor de grupo de identidades de personal.

Por ejemplo, considera la siguiente condición de atributo:

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

En este caso, verás el error si la lista de grupos que envió tu IdP en el atributo groups no contiene gcp-users.

Para resolver este error, realiza los siguientes pasos:

  1. Describe el proveedor que se usó para acceder y verifica que la attributeCondition sea correcta. Para obtener información sobre las operaciones que son compatibles con las condiciones, consulta la definición del lenguaje.

  2. Sigue los pasos en Inspecciona la respuesta del IdP para ver los atributos que muestra el IdP y confirma si la condición del atributo tiene el formato correcto y es precisa.

  3. Accede a la Consola del administrador del IdP y verifica si los atributos de IdP a los que se hace referencia en la condición del atributo estén configurados de forma correcta. Si es necesario, consulta la documentación de tu IdP.

El atributo asignado debe ser del tipo STRING

Este error ocurre en un proveedor de grupos de identidades de personal de SAML cuando el atributo especificado en el mensaje de error es una STRING de un solo valor, pero se asigna a una lista en la asignación de atributos.

Por ejemplo, considera un proveedor de grupo de identidades de personal de SAML que tiene la asignación de atributos, attribute.role=assertion.attributes.userRole. En una aserción de SAML, un Attribute puede tener varias etiquetas AttributeValue como se muestra en el siguiente ejemplo. Por lo tanto, todos los atributos de SAML se consideran listas, por lo que assertion.attributes.userRole es una lista.

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

En este ejemplo, es posible que veas el siguiente error:

The mapped attribute 'attribute.role' must be of type STRING

Para resolver este problema, realiza los siguientes pasos:

  1. Describe el proveedor que se usó para acceder y, luego, identifica el atributo de IdP que se establece en attributeMapping. Compara el atributo y el atributo que se presenta en el mensaje de error. En el ejemplo anterior, un atributo de IdP llamado userRole se asigna al atributo role y el atributo role aparece en la muestra de error.

  2. Cuando actualices la asignación de atributos, ten en cuenta lo siguiente:

    • Si el atributo que causa el error es un valor de lista, identifica un atributo alternativo, estable y con valores de string. Luego, actualiza la asignación de atributos para usarla; para ello, haz referencia a su primer elemento. Para el ejemplo anterior, si myRole se identificó como el atributo de IdP de solo valor alternativo, la asignación de atributos es la siguiente:

      attribute.role=assertion.attributes.myRole[0]

    • De manera alternativa, si se sabe que el atributo es de un solo valor, actualiza la asignación de atributos para usar el primer elemento de la lista. Para el ejemplo anterior, si userRole contiene solo un rol, puedes usar la siguiente asignación:

      attribute.role=assertion.attributes.userRole[0]

    • Para derivar un identificador estable y de un solo valor de la lista, consulta la sección sobre definición del lenguaje y actualiza la asignación de atributos según corresponda.

Consulta la sección Inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP.

No se pudo obtener un valor para google.subject a partir de la credencial determinada

Este error se produce cuando el reclamo google.subject obligatorio no se pudo asignar mediante la asignación de atributos que estableciste en la configuración de tu proveedor de identidades de personal.

Para resolver este error, realiza los siguientes pasos:

  1. Describe el proveedor y, luego, inspecciona el attributeMapping. Identifica la asignación que está configurada para google.subject. Si la asignación no es correcta, actualiza el proveedor de grupo de identidades de personal.

  2. Consulta la sección Inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP. Inspecciona el valor del atributo de la respuesta del IdP que se asigna a google.subject en tus asignaciones de atributos.

    Si el valor está vacío o es incorrecto, accede a la Consola del administrador del IdP y, luego, inspecciona los atributos configurados. Para los atributos, verifica si tu usuario afectado tiene datos correspondientes en tu IdP. Actualiza tu configuración de IdP para corregir los atributos o la información del usuario según corresponda.

  3. Intenta acceder de nuevo.

El tamaño de los atributos asignados supera el límite

El siguiente error se produce cuando un usuario federado intenta acceder:

The size of the entire mapped attributes exceeds the 16 KB limit.

Para resolver este problema, pídele al administrador de tu IdP que reduzca la cantidad de atributos que emite. Tu IdP solo necesita emitir los atributos que se requieren para federar usuarios a Google Cloud. Para obtener más información sobre los límites de asignación de atributos, consulta Asignaciones de atributos.

Por ejemplo, si tu IdP emite una gran cantidad de google.groups que son atributos asignados en tu proveedor de grupos de Workload Identity, un intento de acceso puede fallar. Pídele al administrador que restrinja la cantidad de grupos que emite tu IdP.

La cantidad de grupos supera el límite

El siguiente error se produce cuando un usuario federado intenta acceder:

The current count of GROUPS_COUNT mapped attribute google.groups exceeds the GROUPS_COUNT_LIMIT count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that has fewer than GROUPS_COUNT_LIMIT groups.

Este error incluye los siguientes valores:

  • GROUPS_COUNT: Es el recuento de grupos que emite el IdP.

  • GROUPS_COUNT_LIMIT: Es el límite de recuento de Google Cloud para los grupos.

Este error se produce cuando la cantidad de grupos que emite el IdP supera el límite deGoogle Cloud. Los grupos se asignan a Google Cloud con el atributo google.groups.

Para resolver este problema, pídele al administrador que reduzca la cantidad de grupos que emite tu IdP. Tu IdP solo necesita emitir grupos que se usen para federar usuarios a Google Cloud. Obtén más información sobre los límites relacionados con los grupos en las asignaciones de atributos.

400. Se trata de un error.

Este error se produce cuando la solicitud no se recibió como se esperaba o si tenía un formato incorrecto.

Para resolver este error, realiza los siguientes pasos:

  1. Sigue los pasos en la sección Informa a tus usuarios cómo acceder a fin de verificar si sigues los pasos correctos para acceder.

  2. Compara la configuración del proveedor de grupo de identidades de personal con la configuración de IdP.

Errores de acceso de atributos adicionales

En esta sección, se proporcionan sugerencias para corregir errores cuando se usan atributos adicionales.

El acceso falla cuando se configuran atributos adicionales

Si configuraste atributos adicionales, cualquier problema de configuración, como un ID de cliente, un secreto del cliente o un URI de emisor incorrectos, hará que falle el intento de acceso.

Para resolver este error, realiza los siguientes pasos:

  1. Describe el proveedor y verifica que el ID de cliente y el URI de la entidad emisora sean correctos.
  2. Verifica que el secreto del cliente sea válido y no haya vencido.
  3. En tu IdP, verifica que la aplicación tenga los permisos necesarios.

Se ignoran los grupos de la aserción de SAML o de OIDC

Cuando se configuran atributos adicionales, la federación de identidades de personal ignora cualquier información de grupo proporcionada directamente en las reclamaciones de SAML o de OIDC. En cambio, solo usa los grupos recuperados con el canal secundario (por ejemplo, con la API de Microsoft Graph).

Si tus usuarios no ven los grupos esperados, asegúrate de que los grupos se recuperen correctamente con el canal de retorno y de que los filtros de atributos estén configurados de forma correcta.

Errores de acceso de OIDC

En esta sección, se proporcionan sugerencias para corregir errores específicos de OIDC que un usuario de federación de identidades de personal puede encontrar cuando acceda.

Error en la conexión con la entidad emisora de la credencial

Este error se produce cuando un proveedor de grupo de identidades de personal de OIDC no puede acceder al documento de descubrimiento de OIDC o URI de JWKS.

Para resolver este error, realiza los siguientes pasos:

  1. Describe el proveedor y, luego, inserta el issuerUri configurado. Construye la URL del documento de descubrimiento mediante la adición de /.well-known/openid-configuration al URI de la entidad emisora. Por ejemplo, si tu issuerUri es https://example.com, la URL del documento de descubrimiento sería https://example.com/.well-known/openid-configuration.

  2. Abre la URL del documento de descubrimiento en una ventana de navegación de incógnito.

    1. Si la URL no se abre o en el navegador se muestra un error 404, consulta la documentación de tu IdP para identificar el URI de la entidad emisora correcto. Si es necesario, actualiza el issuerUri en tu proveedor de grupos de federación de identidades de personal.

      Si tu IdP se ejecuta de forma local, consulta la documentación de tu IdP para aprovisionarlo a fin de acceder a través de Internet.

    2. Si se abre la URL, verifica estas condiciones:

      1. Comprueba que la URL no redireccione demasiadas veces antes de entregar el documento de descubrimiento. Si es así, consulta con el administrador de tu IdP para solucionar el problema.
      2. Verifica el tiempo de respuesta del IdP. Consulta con el administrador del IdP para reducir la latencia de respuesta.
      3. El documento de descubrimiento abierto debe estar en formato JSON.

      4. Busca un campo jwks_uri en el archivo JSON.

        1. Verifica que también se abra el valor de la URL asociada.
        2. Verifica que la URL cumpla con las condiciones como se describió antes en esta guía.

    3. Intenta acceder de nuevo.

Errores de acceso de SAML

En esta sección, se proporcionan sugerencias para corregir errores específicos de SAML que un usuario de federación de identidades de personal puede encontrar cuando acceda.

No se pudo verificar la firma en SAMLResponse

Este error ocurre en un proveedor de grupos de identidades de trabajadores de SAML cuando la firma en la respuesta de IdP no se puede verificar mediante ninguno de los certificados X.509 proporcionados en el archivo XML de metadatos de IdP que configuraste en tu proveedor de identidades de personal. Una causa común de este error es que se rotó el certificado de verificación en tu IdP, pero no actualizaste la configuración del proveedor de grupo de identidades de personal con el archivo XML de metadatos de IdP más reciente.

Para resolver este error, realiza los siguientes pasos:

  1. Sigue los pasos que se indican en inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP y ubica el campo X509Certificate en ella (opcional). Describe el proveedor que usaste para acceder y, luego, inspecciona el campo X509Certificate presente en el valor idpMetadataXml que se establece en el proveedor de grupo de identidades de personal. Compara el certificado con el que se ve en la respuesta que muestra tu IdP. Los certificados deben coincidir.

  2. Accede a la Consola del administrador del IdP y descarga el último archivo XML de metadatos.

  3. Actualiza el proveedor de grupo de identidades de personal con el archivo XML de metadatos de IdP descargado.

  4. Intenta acceder de nuevo.

El destinatario de la aserción de SAML no está configurado en la URL de ACS correcta

Este error se produce en un proveedor de grupo de identidades de personal de SAML cuando la respuesta del IdP contiene un valor incorrecto para el campo Recipient en la etiqueta SubjectConfirmationData.

Si deseas resolver este error, actualiza Recipient URL o Redirect URL, o el campo equivalente en la configuración de tu IdP para usar la URL de redireccionamiento que se describe en la sección Configura las URLs de redireccionamiento en tu IdP y vuelve a acceder.

Sigue los pasos en la página Inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP y confirma que el campo Recipient sea correcto.

Por ejemplo, para el proveedor de grupo de identidades de personal locations/global/workforcePools/example-pool/providers/example-provider, el Recipient que contiene la URL de redireccionamiento aparece en la respuesta de SAML del IdP, como se muestra a continuación:

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

El destino de SAMLResponse no coincide con la URL de devolución de llamada de RP

Este error se produce en un proveedor de grupo de identidades de personal de SAML cuando la respuesta del IdP contiene un valor incorrecto para el campo Destination en la etiqueta Response.

Si deseas resolver este error, actualiza Destination URL o Redirect URL, o el campo equivalente en la configuración de tu IdP para usar la URL de redireccionamiento que se describe en Configura las URLs de redireccionamiento en tu IdP.

Sigue los pasos en la página Inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP y confirma que el campo Destination sea correcto.

Por ejemplo, para un proveedor de grupo de identidades de personal locations/global/workforcePools/example-pool/providers/example-provider, el Destination que contiene la URL de redireccionamiento aparecerá en la respuesta SAML de IdP de la siguiente manera:

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

Aserción no válida: NameID vacío o faltante

Este error se produce cuando la respuesta SAML que se recibió desde el IdP no contiene el campo NameId o tiene un valor vacío.

Si deseas resolver este error, consulta la documentación de tu IdP para configurarla a fin de enviar el NameID, que es el sujeto de una aserción de SAML, que suele ser el usuario que se autentica.

Sigue los pasos en la página Inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP y el NameID que se configuró en ella.

Todos los valores de <AudienceRestriction> deben contener el ID de entidad del RP de SAML

Este error se produce cuando las etiquetas AudienceRestriction en la respuesta de SAML de tu IdP no configuran una etiqueta Audience con un valor que represente el ID de entidad del proveedor de grupo de identidades de personal.

Para resolver este error, realiza los siguientes pasos:

  1. Consulta la documentación de IdP sobre cómo configurar el público en las etiquetas AudienceRestriction que envía en la respuesta de SAML. Por lo general, el público se configura con los campos Entity ID o Audience en la configuración de IdP. Consulta la sección de SAML Crea un proveedor de grupo de identidades de personal para ver el valor SP Entity ID que se debe configurar.

  2. Después de actualizar tu configuración de IdP, vuelve a acceder.

Sigue los pasos que aparecen en Inspecciona la respuesta de IdP para ver la respuesta que muestra el IdP y los valores de AudienceRestriction que se configuran en ella.

Errores de acceso de SCIM

En esta sección, se describe cómo resolver errores específicos de SCIM que un usuario de la federación de identidades de personal puede encontrar cuando accede.

No se pudo encontrar el usuario de SCIM

Este error ocurre cuando un usuario intenta acceder con un proveedor de grupos de identidades de personal que está configurado para usar SCIM, pero no se configuró ningún usuario de SCIM para ese proveedor.

Cuando esto sucede, los usuarios reciben el siguiente error cuando intentan acceder:

There was an issue signing in with your identity provider.

Para resolver este error, haz lo siguiente con tu proveedor de identidad:

  1. Configura un inquilino y un token de SCIM en Google Cloud (Microsoft Entra ID | Okta).
  2. Vincula el proveedor a un usuario de SCIM (Microsoft Entra ID | Okta).

Se produce un error en el acceso cuando se habilita el uso de SCIM para usuarios y grupos (versión preliminar)

Cuando --scim-usage se establece en enabled-for-users-groups, los intentos de acceso pueden fallar con mensajes de error específicos:

  • No se encontró el usuario de SCIM o está inactivo:

    • Error: The workforce identity pool provider is configured to use identity information that is provided using SCIM, but a SCIM User could not be associated with the google.subject from the given credential. o ... the SCIM User associated with the google.subject from the given credential is not active.
    • Causa: El usuario no se sincronizó con Google Cloud con SCIM, el google.subject asignado en el proveedor no coincide con la asignación de usuarios de SCIM o el usuario está marcado como active: false en el IdP.
    • Resolución: En tu IdP, verifica que el usuario se aprovisione con SCIM, asegúrate de que su estado sea activo y verifica que la asignación de atributos del proveedor y la asignación de reclamaciones de SCIM para google.subject hagan referencia a la misma identidad.

  • Error de evaluación de CEL o de asignación de reclamaciones:

    • Error: Failed to map attributes from the given credential with SCIM Tenant config.
    • Causa: Una expresión CEL en --claim-mapping no es válida o falló durante la evaluación.
    • Resolución: Revisa las expresiones --claim-mapping de tu usuario de SCIM para asegurarte de que la sintaxis de CEL sea válida y de que los nombres de los atributos sean compatibles.

  • Se superaron los límites de tamaño de los atributos asignados:

    • Error: The size of SCIM mapped attribute google.display_name exceeds the 100 bytes limit. o The size of entire SCIM mapped attributes exceeds the 16 kB limit.
    • Causa: Un atributo asignado individual superó su límite de tamaño (por ejemplo, 100 bytes para google.display_name, 32 bytes para google.posix_username, 127 bytes para google.subject) o el total de reclamaciones asignadas serializadas superó los 16 kB.
    • Resolución: Ajusta las asignaciones de reclamaciones de tu usuario de SCIM o actualiza los valores de los atributos del IdP para que se mantengan dentro de los límites permitidos.

Errores de aprovisionamiento y sincronización de SCIM

En esta sección, se describe cómo resolver problemas con el aprovisionamiento y la sincronización de SCIM en la federación de identidades de personal.

Falla de autenticación del token de SCIM (HTTP 401 o 403)

Este error ocurre cuando los registros del proveedor de identidad (IdP) informan fallas de autenticación (HTTP 401 Unauthorized o HTTP 403 Forbidden). Entre las causas comunes, se incluyen las siguientes:

  • Falta el token de SCIM, no es válido o venció.
  • El token de SCIM contiene espacios adicionales.
  • La solicitud no tiene el encabezado Authorization: Bearer <TOKEN>.
  • El token de SCIM no tiene permisos suficientes.

Para solucionar este problema, haz lo siguiente:

  1. En la configuración de aprovisionamiento de tu IdP, verifica que el token de SCIM coincida con el token secreto generado en Google Cloud sin espacios en blanco adicionales.

  2. Si el token se pierde o no es válido, genera un token de SCIM nuevo:

    gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --scim-tenant="SCIM_TENANT_ID" \
    --location="global"

    Reemplaza lo siguiente:

    • SCIM_TOKEN_ID: Es un ID para el nuevo token de SCIM.
    • WORKFORCE_POOL_ID: Es el ID del grupo de identidades de personal.
    • PROVIDER_ID: Es el ID del proveedor del grupo de personal.
    • SCIM_TENANT_ID: Es el ID del usuario de SCIM.

  3. Actualiza el token secreto en la configuración de tu IdP.

Se excedió el límite de frecuencia (HTTP 429 Demasiadas solicitudes)

Este error se produce cuando los porcentajes de solicitudes del IdP superan la cuota de usuario de SCIM. De forma predeterminada, las solicitudes de escritura y lectura están limitadas a 3,000 solicitudes por usuario de SCIM por organización por minuto, lo que equivale a 50 consultas por segundo (QPS). Para obtener más información, consulta Cuotas y límites.

Para solucionar este problema, haz lo siguiente:

  1. Verifica que el porcentaje de solicitudes de sincronización de tu IdP esté dentro de los límites de la cuota.
  2. En la consola de Google Cloud , ve a IAM y administración > Cuotas y filtra por iamscim.googleapis.com para supervisar el uso de la cuota.
  3. Si necesitas una capacidad de procesamiento más alta, solicita un aumento de cuota en la consola de Google Cloud .

Falla en la creación del usuario de SCIM

Este error se produce cuando falla el comando gcloud iam workforce-pools providers scim-tenants create.

Entre las causas comunes, se incluyen las siguientes:

  • Ya existe un usuario de SCIM en el grupo de personal. Cada grupo de personal solo admite un usuario de SCIM.
  • Un usuario de SCIM borrado recientemente aún se encuentra en su período de eliminación no definitiva de 30 días.
  • No tienes el rol de Administrador de grupos de trabajadores de IAM (roles/iam.workforcePoolAdmin).
  • La marca --claim-mapping contiene expresiones de Common Expression Language (CEL) no admitidas.

Para solucionar este problema, haz lo siguiente:

  1. Verifica que tengas el rol de IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

  2. Enumera los usuarios de SCIM existentes para verificar si ya existe un usuario:

    gcloud iam workforce-pools providers scim-tenants list \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --location="global"

    Reemplaza lo siguiente:

    • WORKFORCE_POOL_ID: Es el ID del grupo de identidades de personal.
    • PROVIDER_ID: Es el ID del proveedor del grupo de personal.

  3. Si un usuario que se borró antes se borra de forma no definitiva, bórralo de forma permanente con la marca --hard-delete:

    gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --location="global" \
    --hard-delete

    Reemplaza SCIM_TENANT_ID por el ID del inquilino de SCIM.

  4. Asegúrate de que --claim-mapping solo use expresiones de CEL compatibles. Para obtener más información, consulta Asignación de reclamaciones.

Falla la creación del token de SCIM

Este error se produce cuando falla el comando gcloud iam workforce-pools providers scim-tenants tokens create.

Entre las causas comunes, se incluyen las siguientes:

  • El usuario de SCIM ya tiene el máximo de dos tokens de SCIM.
  • No tienes el rol de Administrador de grupos de trabajadores de IAM (roles/iam.workforcePoolAdmin).

Para solucionar este problema, haz lo siguiente:

  1. Verifica que tengas el rol de administrador de grupos de IAM Workforce (roles/iam.workforcePoolAdmin).

  2. Enumera los tokens de SCIM existentes para verificar si se alcanzó el límite de dos tokens:

    gcloud iam workforce-pools providers scim-tenants tokens list \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --scim-tenant="SCIM_TENANT_ID" \
    --location="global"

    Reemplaza lo siguiente:

    • WORKFORCE_POOL_ID: Es el ID del grupo de identidades de personal.
    • PROVIDER_ID: Es el ID del proveedor del grupo de personal.
    • SCIM_TENANT_ID: Es el ID del usuario de SCIM.

  3. Si el usuario de SCIM ya tiene dos tokens, borra uno que no se use o que no sea válido:

    gcloud iam workforce-pools providers scim-tenants tokens delete SCIM_TOKEN_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --scim-tenant="SCIM_TENANT_ID" \
    --location="global"

    Reemplaza SCIM_TOKEN_ID por el ID del token de SCIM que deseas borrar.

  4. Después de borrar el token, vuelve a intentar crear el nuevo token de SCIM.

Conflicto de asignación de atributos duplicados (conflicto HTTP 409)

Este error se produce cuando los registros del proveedor de identidad (IdP) informan un HTTP 409 Conflict durante la sincronización porque el IdP envía valores duplicados para google.subject o google.group, o valores no únicos de userName o displayName.

Para solucionar este problema, haz lo siguiente:

  1. En la consola del administrador de tu IdP, verifica que los atributos asignados a google.subject y google.group produzcan valores que no se superpongan.
  2. Asegúrate de que cada usuario tenga un userName único y cada grupo tenga un displayName único.

Las solicitudes PATCH de Microsoft Entra ID fallan

Este error se produce cuando las actualizaciones de usuarios o las solicitudes PATCH de Microsoft Entra ID fallan porque a la URL de usuario le falta el parámetro de consulta ?aadOptscim062020, que es obligatorio para las solicitudes PATCH que cumplen con RFC.

Para solucionar este problema, haz lo siguiente:

  1. En Microsoft Entra ID, ve a tu aplicación empresarial y selecciona Aprovisionamiento > Administrar aprovisionamiento > Credenciales de administrador.

  2. En el campo URL del usuario, agrega ?aadOptscim062020 al URI base:

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

    Reemplaza SCIM_TENANT_UID por el ID único de tu usuario de SCIM.

  3. Haz clic en Probar conexión y, luego, guarda la configuración.

No funciona el acceso o el uso compartido basado en usuarios o grupos

Este problema se produce cuando los usuarios sincronizados no pueden acceder a los recursos de Google Cloud o cuando falla el uso compartido de notebooks en Gemini Notebook Enterprise o de agentes en la app de Gemini Enterprise.

Entre las causas comunes, se incluyen las siguientes:

  • Fallas o demoras de sincronización silenciosas del IdP.
  • Asignaciones de reclamaciones incoherentes entre el proveedor (--attribute-mapping) y el usuario de SCIM (--claim-mapping).
  • Cambios en el IdP en los atributos asignados a google.subject o google.group. Google Cloud espera que los valores asignados a estos atributos sean inmutables.
  • El uso de SCIM no está habilitado para los grupos en el proveedor.

Para solucionar este problema, haz lo siguiente:

  1. Verifica la sincronización y la membresía: Confirma que los usuarios, los grupos y las membresías de los grupos se hayan sincronizado correctamente con Google Cloud:

    • Verifica la sincronización de usuarios:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users" \
  --data-urlencode 'filter=userName eq "USER_NAME"'

    • Verifica la sincronización de grupos:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
  --data-urlencode 'filter=displayName eq "GROUP_NAME"'

    • Verifica la membresía del grupo: Confirma que un usuario sea miembro de un grupo:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
  --data-urlencode 'filter=id eq "GROUP_ID" and members eq "USER_ID"'

      Si el usuario es miembro del grupo, la respuesta devuelve totalResults: 1. Si el usuario no es miembro, la respuesta devuelve totalResults: 0.

    Reemplaza lo siguiente:

    • SCIM_TOKEN: Es tu token secreto de SCIM.
    • SCIM_TENANT_UID: Es el ID único de tu usuario de SCIM.
    • USER_NAME: Es el nombre de usuario del usuario sincronizado.
    • GROUP_NAME: Es el nombre visible del grupo sincronizado.
    • GROUP_ID: Es el ID de SCIM del grupo sincronizado, que se muestra en el campo id de la respuesta de la consulta del grupo.
    • USER_ID: Es el ID de SCIM del usuario sincronizado, que se devuelve en el campo id de la respuesta de la consulta del usuario.

  2. Verifica las asignaciones de reclamaciones: Asegúrate de que el atributo asignado a google.subject en el proveedor (por ejemplo, google.subject=assertion.email.lowerAscii()) coincida con la identidad asignada en el usuario de SCIM (por ejemplo, google.subject=user.emails[0].value.lowerAscii()). Debido a que las asignaciones de reclamaciones son inmutables, si las asignaciones son incoherentes, debes borrar de forma definitiva el usuario de SCIM y volver a crearlo con la asignación correcta.

  3. Garantiza la inmutabilidad de los identificadores: Verifica que los atributos del IdP asignados a google.subject y google.group no hayan cambiado. Google Cloud trata los valores asignados a estos atributos como identificadores inmutables. Si un valor de atributo cambió en tu IdP, revierte el cambio en tu IdP o borra de forma permanente el usuario o grupo afectado de tu IdP y vuelve a crearlo con el valor nuevo para que el identificador coincida con lo que espera Google Cloud.

  4. Habilita el uso de grupos de SCIM: Actualiza tu proveedor para habilitar SCIM para grupos:

    gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --location="global" \
    --scim-usage="enabled-for-groups"

    Reemplaza lo siguiente:

    • PROVIDER_ID: Es el ID del proveedor del grupo de personal.
    • WORKFORCE_POOL_ID: Es el ID del grupo de identidades de personal.

Los cambios realizados en el IdP se retrasan o no se reflejan

Este problema se produce cuando las actualizaciones del IdP para los usuarios, las membresías de grupos o las eliminaciones no aparecen de inmediato en Google Cloud.

Debido a que SCIM se basa en envíos, las actualizaciones dependen de tu programa de sincronización del IdP. Por ejemplo, Microsoft Entra ID se sincroniza aproximadamente cada 40 minutos.

Para solucionar este problema, haz lo siguiente:

  1. Espera al siguiente ciclo de sincronización programado de tu IdP.
  2. Para aplicar los cambios de inmediato, activa una sincronización on demand en la consola del administrador de tu IdP.

El aprovisionamiento de usuarios falla debido al formato del correo electrónico

Este error se produce cuando usuarios específicos no se sincronizan con Google Cloud, y los registros de tu proveedor de identidad (IdP) informan un HTTP 400 Bad Request con un error de SCIM invalidValue.

Google Cloud SCIM requiere exactamente un correo electrónico laboral por usuario. El aprovisionamiento falla si el IdP envía varios correos electrónicos o si el correo electrónico no es del tipo work.

Para resolver este problema, configura la asignación de atributos de tu IdP para que envíe solo el correo electrónico de trabajo principal.

Las actualizaciones de grupos fallan (no se admite HTTP PUT)

Este error se produce cuando las actualizaciones de grupo fallan porque el cliente usa HTTP PUT, que no es compatible. La API de SCIM de Google Cloud solo admite HTTP PATCH para las actualizaciones de grupos.

Para resolver este problema, configura tu IdP o cliente personalizado para que use HTTP PATCH en las actualizaciones de grupos.

La actualización del proveedor falla con parámetros de configuración que se excluyen mutuamente

Este error se produce cuando la creación o actualización del proveedor falla con uno de los siguientes mensajes:

  • Select one of scim_usage - ENABLED_FOR_USERS_GROUPS or extra_attributes_oauth2_client, but not both.
  • Select one of scim_usage or extended_attributes_oauth2_client, but not both.

La configuración --scim-usage=enabled-for-users-groups (versión preliminar) es mutuamente excluyente con los atributos adicionales (extra_attributes_oauth2_client) y los atributos extendidos (extended_attributes_oauth2_client).

Para resolver este problema, quita la configuración de atributos adicionales o extendidos en conflicto del proveedor, o bien cambia el parámetro de configuración --scim-usage.

Errores de intercambio de tokens de la API de OAuth de Cloud

Cuando falla una solicitud de intercambio de tokens, la API de OAuth de Cloud devuelve un estado HTTP 400 Bad Request o 401 Unauthorized con una respuesta JSON de error de OAuth 2.0 (RFC 6749). El campo error indica uno de los siguientes códigos de error:

Código de error Descripción Acciones
invalid_request A la solicitud le falta un parámetro obligatorio, incluye un valor de parámetro no válido, incluye un parámetro más de una vez o tiene un formato incorrecto. Verifica que se proporcionen todos los parámetros codificados en URL obligatorios (grant_type, code o refresh_token, redirect_uri).
invalid_client No se pudo realizar la autenticación del cliente. Verifica que el client_id y el client_secret de OAuth registrados coincidan, que el cliente de OAuth esté habilitado para tu grupo de identidades de personal y que el encabezado Authorization: Basic esté codificado en Base64 correctamente.
invalid_grant El código de autorización o el token de actualización proporcionados no son válidos, vencieron, se revocaron, no coinciden con el URI de redireccionamiento que se usó en la solicitud de autorización o se emitieron para otro cliente. Asegúrate de que el código o el token no hayan vencido ni se hayan canjeado anteriormente.
unauthorized_client El cliente de OAuth autenticado no tiene autorización para usar el grant_type solicitado. Verifica que el registro de tu cliente de OAuth permita otorgar códigos de autorización o tokens de actualización.
unsupported_grant_type El servidor de autorización no admite el tipo de permiso de autorización. Establece grant_type en authorization_code o refresh_token.
invalid_scope El permiso solicitado no es válido, es desconocido, tiene un formato incorrecto o excede los permisos otorgados por el propietario del recurso. Verifica que los permisos solicitados coincidan con los configurados en el cliente de OAuth y que sean válidos para tu aplicación.
resource_exhausted La solicitud superó la cuota de intercambio de tokens de la API de OAuth de Cloud. Verifica el uso de la API en la consola de Google Cloud o solicita un aumento de cuota.

Errores de grupos y de información del usuario de OAuth de Cloud

Cuando falla una solicitud al extremo /userinfo o /groups, la API de OAuth de Cloud devuelve un estado HTTP 400 Bad Request, 401 Unauthorized o 403 Forbidden con una respuesta de error de token del portador de OAuth 2.0 (RFC 6750/OpenID Connect Core). El campo error indica uno de los siguientes códigos de error:

Código de error Estado de HTTP Descripción Acciones
invalid_request 400 Bad Request/401 Unauthorized A la solicitud le falta el encabezado Authorization obligatorio o el encabezado tiene un formato incorrecto (por ejemplo, no comienza con Bearer). Verifica que el encabezado Authorization: Bearer ACCESS_TOKEN tenga el formato correcto.
invalid_token 401 Unauthorized El token de acceso proporcionado no es válido, venció o se revocó. Actualiza el token de acceso con el otorgamiento de refresh_token o repite el flujo de código de autorización.
insufficient_scope 403 Forbidden El token de acceso no tiene el permiso openid requerido o el usuario del token no coincide con la organización especificada en la URL del extremo con alcance de organización. Verifica que el token se haya solicitado con el permiso openid requerido y que estés llamando al extremo correcto.