Soluciona problemas de las políticas de acceso unificado de IAM

En este documento, se te ayuda a diagnosticar y resolver problemas comunes cuando configuras y aplicas las Políticas de acceso unificado (UAPs) de IAM para la salida de Agent Gateway.

Aplicación de políticas y fallas de acceso

En esta sección, se describen los problemas relacionados con la aplicación.

No se aplica la política

Síntoma: Un agente puede acceder a las herramientas de destino, los servidores de MCP o los extremos incluso si se configuró una regla de denegación de IAM o una regla de permiso restrictiva para bloquear el acceso.

Causa: La extensión de autorización de Agent Gateway se ejecuta en modo de ejecución de prueba, o el alcance de la vinculación de políticas no coincide con el recurso de destino. En el modo de ejecución de prueba, las decisiones de acceso se evalúan y se registran para la auditoría, pero las solicitudes nunca se bloquean.

Solución:

  1. Cambia el modo de ejecución de prueba al modo de aplicación forzosa: Primero, revisa el archivo de configuración de la extensión de autorización (iap-request-authz-extension.yaml). Si iamEnforcementMode está configurado como "DRY_RUN", actualízalo a "ENFORCE" (o quita la configuración de DRY_RUN) y vuelve a importar la extensión con la gcloud CLI:

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    Reemplaza lo siguiente:

    • EXTENSION_NAME: el nombre de tu extensión de autorización
    • EXTENSION_FILE: el nombre de archivo de la configuración de la extensión YAML
    • LOCATION: la Cloud de Confiance región en la que se implementa tu puerta de enlace

  2. Verifica la delegación de la política de autorización de la puerta de enlace: Verifica que tu política de autorización de la puerta de enlace (policyProfile: REQUEST_AUTHZ) esté vinculada a la instancia correcta de Agent Gateway (target.resources).

  3. Verifica el alcance de la vinculación de políticas: Verifica que la UAP de IAM esté vinculada al alcance del recurso de destino al que llega el tráfico.

  4. Inspecciona la prioridad de las reglas: En una política combinada, las reglas de denegación anulan explícitamente las reglas de permiso en el mismo alcance. Sin embargo, verifica si una UAP con una regla de permiso más amplia que está vinculada a nivel del registro o del proyecto otorga acceso sin restricciones de condición.

La política de Aplicación de Medidas por Incumplimiento bloquea el acceso del agente

Síntoma: La solicitud de salida de un agente falla con un error 403 Forbidden o PERMISSION_DENIED de HTTP cuando se habilita la aplicación de políticas de Agent Gateway.

Causas:

  • La identidad del agente no se especifica en la UAP.

  • No se le otorgó a la identidad del agente el permiso iap.resources.egressViaIAP en el recurso de destino.

  • El nombre de host de destino exacto no está registrado en Agent Registry.

  • Los atributos de la solicitud no satisfacen las condiciones de Common Expression Language (CEL) en la UAP.

Solución:

  1. Cambia al modo de ejecución de prueba para la depuración no disruptiva: Mientras diagnosticas la falla, cambia temporalmente la extensión de autorización al modo de ejecución de prueba (iamEnforcementMode: "DRY_RUN") para que no se bloquee el tráfico de agentes activos mientras inspeccionas los registros de auditoría.

  2. Consulta los Registros de auditoría de Cloud: Consulta los Registros de auditoría de Cloud para inspeccionar la verificación de autorización exacta y la evaluación de atributos de CEL:

    gcloud

    Ejecuta el siguiente comando gcloud logging read:

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    Reemplaza PROJECT_ID con el ID del proyecto.

    Console

    1. En la Cloud de Confiance consola de, accede a la página Explorador de registros.
    2. Elige tu proyecto.
    3. En el editor de consultas, ingresa la consulta siguiente: 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. Haz clic en Ejecutar consulta.
    5. Expande la entrada de registro y, luego, inspecciona protoPayload.authorizationInfo para ver qué URI y permiso del recurso de destino no pasaron la evaluación.

  3. Verifica la coincidencia exacta del nombre de host: Agent Gateway hace coincidir los nombres de host de destino exactamente. Una API de Google o un servicio de terceros pueden resolverse a través de varias variaciones de nombres de host según la versión del SDK, la configuración regional del cliente o el uso de mTLS, por ejemplo, us-central1-aiplatform.googleapis.com en comparación con us-central1-aiplatform.mtls.googleapis.com en comparación con aiplatform.googleapis.com.

    • Si dependes de los destinos registrados, asegúrate de que cada variación exacta del nombre de host esté registrada en Agent Registry.
    • Si el agente accede a extremos no registrados, verifica que una política de extremos no registrados otorgue iap.resources.egressViaIAP para ese host y ruta de acceso.

  4. Verifica la cobertura de la vinculación de políticas en todos los alcances: Verifica si existe una vinculación de políticas en uno de los tres alcances admitidos:

    • En todo el registro: Otorga acceso a todos los agentes, servidores de MCP y extremos del registro.
    • Por recurso: Otorga acceso a un servidor de MCP, un extremo o un agente registrados específicos.
    • Extremos no registrados: Otorga acceso a destinos fuera de Agent Registry.
    • Nota: Cuando se describen las vinculaciones de políticas para un recurso de destino, si el resultado que se muestra contiene un campo "etag" pero no vinculaciones, no existe una política de IAM para ese destino.

Mensajes de error comunes de la IU, gcloud y la API de REST

En esta sección, se describen los mensajes de error y cómo resolverlos.

No se encontró la política

Mensaje de error:

  • IU de la consola: "La política solicitada no existe. Verifica que la política exista para el recurso seleccionado".
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Causa: El ID de UAP especificado en tu solicitud de actualización o vinculación de políticas no existe en el proyecto o la ubicación, o se borró.

Solución: Enumera todas las UAPs disponibles en tu proyecto con gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global para confirmar el ID y la ubicación exactos de la política antes de vincularla o actualizarla.

Se excedió el límite de vinculación de destino

Mensaje de error:

  • IU de la consola: "El destino seleccionado alcanzó su límite de vinculaciones de políticas de acceso. Borra una vinculación existente antes de agregar una nueva".
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Causa: Intentaste adjuntar más vinculaciones de políticas a un recurso de destino (como un servidor de MCP o un registro) que el límite máximo permitido por destino.

Solución: En lugar de crear una UAP y una vinculación independientes para cada regla individual, consolida varias reglas de permiso o denegación en una sola UAP. Quita las vinculaciones sin usar con gcloud iam policy-bindings delete.

Se excedió el límite de vinculación de políticas

Mensaje de error:

  • IU de la consola: "La política seleccionada alcanzó su límite de vinculaciones. Borra una vinculación existente antes de agregar una nueva".
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Causa: Una sola UAP está adjunta a demasiados recursos de destino distintos en tu proyecto.

Solución: Vincula la política en un alcance más amplio, como el alcance en todo el registro (AgentRegistry) o el alcance del proyecto, y usa condiciones de atributos de CEL (como destination.agent_registry.mcp_server.name) para controlar el acceso a herramientas individuales dentro de las reglas de la política.

Se excedió el límite de condiciones

Mensaje de error:

  • IU de la consola: "Esta política alcanzó la cantidad máxima de condiciones de atributos. Quita algunas condiciones para guardar los cambios".
  • API / gcloud: TOO_MANY_CONDITIONS / Se excedió el límite de condiciones para la regla en la política.

Causa: Una sola regla de permiso o denegación contiene más condiciones de atributos de control de acceso detallado (FGAC) o subexpresiones complejas de las que se admiten en una sola regla.

Solución: Consolida las verificaciones de atributos con operadores lógicos de CEL (&&, ||) o establece búsquedas de inclusión (in), o bien divide tus expresiones en varias reglas dentro de la misma UAP.

Detalles de la regla desactualizados

Mensaje de error:

  • IU de la consola: "Los detalles de la regla están desactualizados. Otro usuario modificó esta regla después de que se cargó esta página. Actualiza la página para recuperar los detalles actuales antes de editar o borrar".
  • API / gcloud: HTTP 412 Precondition Failed / ABORTED debido a una falta de coincidencia de etag.

Causa: Otro administrador o proceso automatizado modificó la UAP después de que la recuperaste, lo que provocó que el etag difiera del estado activo del servidor.

Solución: Actualiza la página de la consola para recuperar los detalles de la política activa y etag antes de guardar los cambios. Cuando uses la API de REST, primero realiza una GET solicitud para recuperar el valor "etag" activo y, luego, inclúyelo en la carga útil de la solicitud PATCH.

No se puede borrar la última regla de una política

Mensaje de error:

  • IU de la consola: "No se puede borrar esta regla. La 'Política predeterminada' debe contener al menos una regla. Para quitar esta regla, borra la política". o "Esta es la última regla en <policy name>. Si la borras, también se borrará la política y se quitarán de forma permanente todas las vinculaciones asociadas, lo que puede afectar el acceso de los agentes a los recursos."

Causa: No se puede guardar una UAP de IAM con cero reglas.

Solución: Si quieres quitar la única regla de una política, borra toda la política. Recuerda que debes borrar todas las vinculaciones de políticas que hagan referencia a la política antes de que puedas borrar la política en sí.

Expresión CEL personalizada conservada en la pestaña Avanzado

Mensaje de error:

  • IU de la consola: "No se pudo convertir la expresión en CEL personalizada en selecciones de la IU estándar. Tu expresión se conserva en la pestaña Avanzado".

Causa: Ingresaste una condición o función CEL compleja en el Editor de condiciones (pestaña Avanzado) que no se puede asignar a los selectores desplegables simplificados del creador de condiciones estándar.

Solución: Este mensaje es una notificación informativa. Tu condición CEL personalizada es válida y se conserva. Sigue realizando cambios directamente en la pestaña Editor de condiciones.

¿Qué sigue?