Delega la autorización con Service Extensions

Usa esta página para aprender a delegar la autorización de Agent Gateway a Identity-Aware Proxy, Model Armor y otros motores de autorización personalizados mediante Service Extensions.

Las políticas de autorización te permiten aplicar políticas de control de acceso y administración centralizadas en el tráfico que pasa por el extremo publicado por Agent Gateway. Estas políticas te permiten administrar el tráfico mediante el control del acceso basado en identidades mTLS, atributos de solicitud y respuesta, e incluso personalizarlo según los atributos específicos del protocolo que se usen (por ejemplo, servidores de MCP).

Las políticas de autorización usan perfiles de políticas para determinar el tipo de autorización que se realizará. Puedes usar una política de autorización basada en solicitudes (REQUEST_AUTHZ) que se basa en la información de los encabezados de solicitudes HTTP para permitir o denegar el tráfico. Como alternativa, puedes usar una política de autorización basada en contenido (CONTENT_AUTHZ) cuando necesites realizar una inspección más profunda de las cargas útiles de tu aplicación para permitir o denegar el tráfico.

Para obtener más información sobre las políticas de autorización, los perfiles de políticas y sus casos de uso, consulta Descripción general de las políticas de autorización.

Extensiones de autorización

A veces, las decisiones de autorización complejas no se pueden expresar fácilmente con una política de autorización. Agent Gateway te permite configurar políticas de autorización con extensiones de autorización para delegar decisiones de autorización a motores de autorización personalizados.

Una extensión de autorización te permite interceptar y evaluar las solicitudes que pasan por una implementación de Agent Gateway. Realiza una llamada gRPC en tiempo real a un servicio externo que administras, de modo que puedas inspeccionar, modificar o incluso bloquear el tráfico antes de que continúe a su destino.

La extensión inspecciona los datos según la política de autorización configurada. Puedes configurar extensiones de autorización por separado para políticas de autorización basadas en solicitudes y basadas en contenido, o puedes usar ambas para una seguridad integral.

Antes de comenzar

Antes de comenzar, asegúrate de cumplir con los siguientes requisitos:

  • Se implementa Agent Gateway. Consulta Configura Agent Gateway.

  • Debes tener el permiso de IAM agentGateway.use en el recurso de Agent Gateway implementado para poder adjuntar políticas de autorización a la puerta de enlace.

Configura políticas de autorización con extensiones

En esta sección, se muestra cómo configurar políticas de autorización que delegan decisiones de autorización y seguridad del contenido a Identity-Aware Proxy, Model Armor y otros servicios personalizados.

Delega la autorización a IAP

Puedes configurar una extensión de autorización de solicitudes para delegar decisiones de acceso para políticas de autorización a IAP.

En el siguiente ejemplo, se muestra cómo configurar una extensión de autorización con una política de autorización para una instancia de Agent Gateway.

Console

Para usar la Google Cloud consola y habilitar IAP para Agent Gateway, sigue los siguientes pasos:

  1. Crea las políticas de salida de IAM necesarias para tus agentes y herramientas. Para obtener más información, consulta Crea políticas de agentes de IAM.

  2. Consulta Configura Agent Gateway en el modo de agente a cualquier lugar (salida) para habilitar IAP mientras creas Agent Gateway (con el parámetro Autorización de acceso).

    IAP requiere que tus agentes estén registrados en el recurso de Agent Registry vinculado a la puerta de enlace.

gcloud

  1. Configura la extensión de autorización para que apunte a IAP.

    1. Define la extensión en un archivo YAML. Usa los valores de muestra proporcionados.

      cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
EOF

      Si deseas implementar la extensión en un modo de ejecución de prueba solo de auditoría para probar la política de autorización sin aplicarla, puedes especificar el campo DRY_RUN. Esto te permite verificar tu política y minimizar el riesgo de interrumpir el tráfico debido a errores de configuración:

      cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
metadata: '
  iamEnforcementMode: DRY_RUN
'
EOF

    2. Importa la extensión de autorización. Usa el gcloud beta service-extensions authz-extensions import comando con los siguientes valores de muestra.

      gcloud beta service-extensions authz-extensions import my-iap-request-authz-ext \
   --source=iap-request-authz-extension.yaml \
   --location=LOCATION

  2. En el mismo proyecto, configura una política de autorización que delegue la decisión a la extensión.

    1. Define una política de autorización que asocie la extensión my-iap-authz-request-ext con tu puerta de enlace. Usa los valores de muestra proporcionados.

      cat >iap-request-authz-policy.yaml <<EOF
name: my-iap-request-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-iap-request-authz-ext"
EOF

      Reemplaza PROJECT_ID por el ID del proyecto.

    2. Importa la política de autorización al proyecto. Usa el gcloud beta network-security authz-policies import comando con los siguientes valores de muestra.

      gcloud beta network-security authz-policies import my-iap-request-authz-policy \
   --source=iap-request-authz-policy.yaml \
   --location=LOCATION

Delega la autorización a Model Armor

Puedes configurar una extensión de autorización para delegar decisiones de seguridad del contenido para políticas de autorización a Model Armor.

En el siguiente ejemplo, se muestra cómo configurar una extensión de autorización de este tipo con una política de autorización para Agent Gateway.

Console

Para usar la Google Cloud consola y habilitar Model Armor para Agent Gateway, sigue los siguientes pasos:

  1. Crea las plantillas de Model Armor necesarias.

  2. Consulta Configura Agent Gateway para habilitar Model Armor mientras creas Agent Gateway (con la casilla de verificación Habilitar Model Armor). Las plantillas de Model Armor son compatibles con los modos de cliente a agente y de agente a cualquier lugar.

  3. Si tus plantillas de Model Armor están en un proyecto diferente de la puerta de enlace, debes otorgar manualmente los roles necesarios a la cuenta de servicio de Agent Gateway. La cuenta de servicio tiene el formato: service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, en el que PROJECT_NUMBER es el número del proyecto en el que creaste la puerta de enlace.

    Otorga los siguientes roles:

    • Los roles roles/modelarmor.calloutUser y roles/serviceusage.serviceUsageConsumer en el proyecto que contiene la puerta de enlace.
    • El rol roles/modelarmor.user en el proyecto que contiene las plantillas de Model Armor.

    Deberás usar la gcloud CLI para completar este paso.

    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.user

    Reemplaza lo siguiente:

    • GATEWAY_PROJECT_ID: Es el ID del proyecto en el que creaste la puerta de enlace.
    • GATEWAY_PROJECT_NUMBER: Es el número del proyecto en el que creaste la puerta de enlace.
    • MODEL_ARMOR_PROJECT_ID: Es el ID del proyecto que contiene la plantilla de Model Armor.

    Si usas la puerta de enlace para Agent Runtime, el agente de servicio de Reasoning Engine también requiere estos permisos, como se documenta en Enruta el tráfico de Agent Runtime a través de Agent Gateway.

gcloud

  1. Crea las plantillas de Model Armor necesarias.

  2. Si tus plantillas de Model Armor están en un proyecto diferente de la puerta de enlace, debes otorgar manualmente los roles necesarios a la cuenta de servicio de Agent Gateway. La cuenta de servicio tiene el formato: service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, en el que PROJECT_NUMBER es el número del proyecto en el que creaste la puerta de enlace.

    Otorga los siguientes roles:

    • Los roles roles/modelarmor.calloutUser y roles/serviceusage.serviceUsageConsumer en el proyecto que contiene la puerta de enlace.
    • El rol roles/modelarmor.user en el proyecto que contiene la plantilla de Model Armor.
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.user

    Reemplaza lo siguiente:

    • GATEWAY_PROJECT_ID: Es el ID del proyecto en el que creaste la puerta de enlace.
    • GATEWAY_PROJECT_NUMBER: Es el número del proyecto en el que creaste la puerta de enlace.
    • MODEL_ARMOR_PROJECT_ID: Es el ID del proyecto que contiene la plantilla de Model Armor.

  3. Configura la extensión de autorización para que apunte a Model Armor.

    1. Define la extensión en un archivo YAML. Usa los valores de muestra proporcionados.

      cat >ma-content-authz-extension.yaml <<EOF
name: my-ma-content-authz-ext
service: modelarmor.LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
    "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
    "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
    }
  ]'
failOpen: true
timeout: 1s
EOF

    2. Importa la extensión de autorización. Usa el gcloud beta service-extensions authz-extensions import comando con los siguientes valores de muestra.

      gcloud beta service-extensions authz-extensions import my-ma-content-authz-ext \
   --source=ma-content-authz-extension.yaml \
   --location=LOCATION

  4. Configura una política de autorización con la extensión.

    1. Define una política de autorización que asocie la extensión my-ma-content-authz-ext con un Agent Gateway.

      cat >ma-content-authz-policy.yaml <<EOF
name: my-ma-content-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/gateways/AGENT_GATEWAY_NAME"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext"
EOF

      Para las políticas de autorización de contenido, el valor de policyProfile se establece como CONTENT_AUTHZ. Este valor indica que el proveedor de políticas personalizadas procesa el tráfico de solicitudes y respuestas, incluido el procesamiento del cuerpo.

    2. Importa la política de autorización al proyecto. Usa el gcloud beta network-security authz-policies import comando con los siguientes valores de muestra.

      gcloud beta network-security authz-policies import my-ma-content-authz-policy \
  --source=ma-content-authz-policy.yaml \
  --location=LOCATION

Delega la autorización a extensiones de autorización personalizadas

Puedes configurar extensiones de autorización personalizadas para delegar decisiones a servicios personalizados. Estas extensiones personalizadas solo pueden orientarse a nombres de dominio completamente calificados (FQDN).

Cuando usas destinos FQDN, la extensión usa el protocolo HTTP2 con encriptación TLS para comunicarse con extremos en el puerto 443. Sin embargo, la extensión no valida el certificado del servidor. Por lo tanto, para una mayor seguridad, debes asegurarte de que los extremos resueltos estén dentro de la red de VPC. También asegúrate de tener configurado el intercambio de tráfico de DNS entre el proyecto de Agent Gateway y tu red de VPC.

  1. Para configurar una extensión de autorización con una política de autorización para un FQDN específico, como mycustomauthz.internal.net, especifícalo como el valor de service en el archivo YAML de la extensión, como se muestra en el siguiente ejemplo. En este ejemplo, se supone que implementaste un servidor en tu red de VPC que implementa el protocolo ext_authz.

    cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: true
wireFormat: EXT_AUTHZ_GRPC
EOF

  2. Crea la extensión de autorización para que apunte al servicio personalizado.

      gcloud beta service-extensions authz-extensions import custom-authz-extension 
    
    --source=custom-authz-extension.yaml 
    
    --location=LOCATION

  3. Después de crear la extensión, configura una política de autorización CUSTOM que delega decisiones a la extensión de autorización.

      $ cat >authz-policy.yaml <<EOF
  name: authz-with-extension
  target:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
  policyProfile: REQUEST_AUTHZ
  action: CUSTOM
  customProvider:
  authzExtension:
    resources:
    - projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension
  EOF

  4. Crea la política de autorización.

    gcloud beta network-security authz-policies import authz-policy-with-extension \
--source=authz-policy.yaml \
--location=LOCATION

Ten en cuenta que, cuando una extensión de autorización se asocia con una política de autorización mediante el perfil REQUEST_AUTHZ, como se muestra en este ejemplo, la puerta de enlace invoca la extensión solo cuando llegan los encabezados de solicitud. El cuerpo de la solicitud, los encabezados de respuesta y el cuerpo de respuesta no son visibles para la extensión de autorización.

Combina la autorización de IAP con las barreras de protección de Model Armor

Para una seguridad integral, te recomendamos que configures una política de autorización CUSTOM con un perfil de política REQUEST_AUTHZ y otra política de autorización CUSTOM con un perfil de política CONTENT_AUTHZ.

En el siguiente ejemplo, se usa IAP como un sistema de autorización de solicitudes centralizado y Model Armor para las barreras de protección de IA. Como se muestra en los ejemplos anteriores, puedes intercambiar cada uno de ellos con extensiones de servicio para usar tus propias soluciones personalizadas.

  1. Configura una extensión de autorización REQUEST_AUTHZ que delega a IAP y una política de autorización que apunta a la extensión.

    1. Define la extensión de autorización.

      $ cat >iap-extension.yaml <<EOF
name: iap-extension
service: iap.googleapis.com
failOpen: true
EOF

    2. Crea la extensión de autorización.

      gcloud beta service-extensions authz-extensions import iap-extension \
--source=iap-extension.yaml \
--location=LOCATION

      Reemplaza LOCATION por la región de la extensión.

    3. Configura la política de autorización REQUEST_AUTHZ que delega a la extensión.

      $ cat >authz-policy-request-authz.yaml <<EOF
name: authz-iap
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/iap-extension"
EOF

      Reemplaza lo siguiente:

      • PROJECT_ID: ID del proyecto
      • LOCATION: Es la ubicación de los recursos.
      • AGENT_GATEWAY_NAME: Es el nombre de Agent Gateway.

    4. Crea la política de autorización.

      gcloud beta network-security authz-policies import authz-iap \
--source=authz-policy-request-authz.yaml \
--location=LOCATION

  2. Configura una extensión de autorización CONTENT_AUTHZ que delega a Model Armor y una política de autorización que apunta a la extensión.

    1. Define la extensión.

      $ cat >ma-extension-file.yaml <<EOF
name: ma-extension
service: modelarmor.LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
    "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID",
    "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID"
    }
  ]'
failOpen: true
timeout: 1s
EOF

      Reemplaza lo siguiente:

      • LOCATION: Es la región en la que residen tus plantillas de Model Armor.
      • MODEL_ARMOR_PROJECT_ID: Es el ID del proyecto que contiene las plantillas de Model Armor.
      • RESPONSE_TEMPLATE_ID: Es el ID de la plantilla de respuesta.
      • REQUEST_TEMPLATE_ID: Es el ID de la plantilla de solicitud.

    2. Crea la extensión de autorización.

      gcloud beta service-extensions authz-extensions import ma-extension \
--source=ma-extension-file.yaml \
--location=LOCATION

    3. Configura la política de autorización CONTENT_AUTHZ que delega a la extensión.

      $ cat >authz-policy-content-authz.yaml <<EOF
name: authz-ma
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/ma-extension"
EOF

    4. Crea la política de autorización.

      gcloud beta network-security authz-policies import ma-authz-policy \
--source=authz-policy-content-authz.yaml \
--location=LOCATION

Cuando una extensión de autorización se asocia con un perfil CONTENT_AUTHZ, recibe todos los eventos ext_proc, incluidos los encabezados, el cuerpo y los trailers de solicitud y respuesta. Si tu extensión de autorización basada en ext_proc puede controlar la autorización en el momento de la solicitud y la autorización basada en contenido, te recomendamos que configures una sola política de autorización CUSTOM con el perfil de política CONTENT_AUTHZ. Esta política debe apuntar a tu extensión de autorización versátil. Este enfoque habilita ambos tipos de autorización a través de una sola extensión y conexión ext_proc, lo que puede mejorar la latencia en comparación con el uso de extensiones separadas para los perfiles REQUEST_AUTHZ y CONTENT_AUTHZ.

Autorización basada en atributos del protocolo MCP

Agent Gateway analiza la carga útil del protocolo MCP en una solicitud y pone los atributos extraídos a disposición de las políticas de autorización.

Puedes restringir el acceso en función de los parámetros del método MCP, como los nombres de herramientas específicas. En esta sección, se muestran dos ejemplos, uno para una política ALLOW y otro para DENY.

  1. Configura la política de autorización.

    Ejemplo de política ALLOW

    En este ejemplo, se permite el acceso a un conjunto específico de herramientas en el servidor de MCP y las funciones del protocolo base, pero no se permite el acceso a instrucciones y recursos.

    Cuando escribas una política ALLOW, asegúrate de especificar baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS para que las RPC de MCP no específicas de acceso, como inicialización, registro, finalización, notificaciones y ping, sigan funcionando. De lo contrario, no se podrá establecer una sesión de MCP.

    $ cat >authz-policy-restrict-tools.yaml <<EOF
name: my-authz-policy-restrict-tools
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
httpRules:
- to:
    operations:
    - mcp:
        baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS
        methods:
        - name: "tools/list"
        - name: "tools/call"
          params:
          - exact: "get_weather"
          - exact: "get_location"
action: ALLOW
EOF

    Ejemplo de política DENY

    En este ejemplo, no se permiten todas las instrucciones o el acceso a métodos a un servidor de MCP detrás de un Agent Gateway.

    $ cat >authz-policy-disallow-prompts.yaml <<EOF
name: my-authz-policy-disallow-prompts
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
httpRules:
- to:
    operations:
    - mcp:
        methods:
        - name: "prompts"
action: DENY
EOF

  2. Crea la política de autorización.

    gcloud beta network-security authz-policies import AUTHZ_POLICY_NAME \
--source=AUTH_POLICY_YAML_FILE_PATH \
--location=LOCATION

    Reemplaza lo siguiente:

    • AUTHZ_POLICY_NAME: Es el nombre de la política de autorización.
    • AUTH_POLICY_YAML_FILE_PATH: Es la ruta de acceso al archivo YAML de la política de autorización.
    • LOCATION: Es la ubicación de los recursos.

Limitaciones

Se aplican las siguientes limitaciones cuando usas políticas de autorización:

  • Puedes configurar un máximo de cuatro políticas de autorización personalizadas por Agent Gateway, independientemente del perfil de política.
  • Si usas extensiones de autorización personalizadas con el perfil CONTENT_AUTHZ, deben admitir el protocolo ext_proc y el modo FULL_DUPLEX_STREAMED para los eventos del cuerpo.
  • Si configuras varias políticas de autorización personalizadas que usan el mismo perfil, no se garantiza su orden de ejecución.

Además, consulta las siguientes secciones para obtener más información sobre las limitaciones de las extensiones de autorización:

¿Qué sigue?

Guía

Obtén información para supervisar Agent Gateway.