Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 con Service Extensions.

Las políticas de autorización te permiten aplicar políticas de control de acceso y administración centralizadas al tráfico que pasa por el extremo publicado por la puerta de enlace del agente. Estas políticas te permiten administrar el tráfico controlando el acceso según las identidades de mTLS, los atributos de solicitud y respuesta, y hasta personalizarlo según los atributos específicos del protocolo que se usan (por ejemplo, los 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 el 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 el Resumen 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 las 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 hacia su destino.

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

Antes de comenzar

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

Se implementó la puerta de enlace del agente. 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 las decisiones de autorización y seguridad del contenido en 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 las decisiones de acceso de las políticas de autorización en IAP.

En los siguientes pasos, se muestra cómo configurar una extensión de autorización con una política de autorización para una instancia de Agent Gateway.

Crea las políticas de salida de IAM requeridas para tus agentes y herramientas. Para obtener más información, consulta Crea políticas de agentes de IAM.
Consulta Configura Agent Gateway en el modo Agent-to-Anywhere (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 Agent Registry vinculado a la puerta de enlace.
Configura una 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
timeout: 1s
EOF
```
  Si deseas implementar la extensión en un modo de ejecución de prueba de solo 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
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
EOF
```
  Quita el campo de metadatos DRY_RUN cuando tengas todo listo para comenzar a aplicar las políticas.
2. Importa la extensión de autorización. Usa el comando gcloud beta service-extensions authz-extensions import 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
  
```

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

Define una política de autorización que asocie la extensión my-iap-request-authz-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.

Importa la política de autorización al proyecto. Usa el comando gcloud beta network-security authz-policies import 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 las decisiones de seguridad del contenido de las 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 consola Google Cloud y habilitar Model Armor para Agent Gateway, sigue estos pasos:

Crea las plantillas de Model Armor necesarias.
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 se admiten en los modos Client-to-Agent y Agent-to-Anywhere.
Si tus plantillas de Model Armor se encuentran en un proyecto diferente del de la puerta de enlace, debes otorgar de forma manual los roles requeridos a la cuenta de servicio de Agent Gateway. La cuenta de servicio tiene el siguiente 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 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 Cómo enrutar el tráfico de Agent Runtime a través de Agent Gateway.

gcloud

Crea las plantillas de Model Armor necesarias.
Si tus plantillas de Model Armor se encuentran en un proyecto diferente del de la puerta de enlace, debes otorgar de forma manual los roles requeridos 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.

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

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

Importa la extensión de autorización. Usa el comando gcloud beta service-extensions authz-extensions import 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

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 una puerta de enlace del agente.
  Del agente a cualquier lugar
  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" httpRules: - to: operations: [ { "paths": [ { "prefix": "/" } ] } ] when: > request.headers['content-type'] == 'application/json' || request.headers['content-type'].startsWith('text/') EOF
  
  Ten en cuenta lo siguiente:
  
  El valor de policyProfile se establece en CONTENT_AUTHZ. Esto indica que el proveedor de políticas personalizadas procesa el tráfico de solicitudes y respuestas, incluido el cuerpo de la solicitud.
  
  El parámetro httpRules muestra cómo usar los atributos de CEL para crear condiciones que coincidan con el tráfico específico que deseas reenviar a Model Armor para su evaluación. En este ejemplo, las reglas coinciden con todo el tráfico que tiene tipos de contenido application/json o text/. Te recomendamos que uses estas reglas para limitar la evaluación de Model Armor al tráfico pertinente. Esto te permite enrutar el tráfico compatible de la API de LLM, el MCP y el A2A a Model Armor, y excluir el tráfico interno, como las llamadas de gRPC del agente.
  De cliente a agente
  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
  
  El valor de policyProfile se establece en CONTENT_AUTHZ. Esto indica que el proveedor de políticas personalizadas procesa el tráfico de solicitudes y respuestas, incluido el cuerpo de la solicitud.
2. Importa la política de autorización al proyecto. Usa el comando gcloud beta network-security authz-policies import 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 segmentarse para nombres de dominio completamente calificados (FQDN).

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

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
timeout: 1s
wireFormat: EXT_AUTHZ_GRPC
EOF
```

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

Después de crear la extensión, configura una política de autorización CUSTOM que delegue las 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

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 usando 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. La extensión de autorización no puede ver el cuerpo de la solicitud, los encabezados de respuesta ni el cuerpo de la respuesta.

Combina la autorización de IAP con las protecciones de Model Armor

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

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

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.

Define la extensión de autorización.

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

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.

Configura la política de autorización de REQUEST_AUTHZ que delega en 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 la puerta de enlace del agente.

Crea la política de autorización.

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

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

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: ID de la plantilla de solicitud.

Crea la extensión de autorización.

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

Configura la política de autorización CONTENT_AUTHZ que delega en 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

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 de solicitud y respuesta, el cuerpo y los tráileres. 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 el 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 permite ambos tipos de autorización a través de una sola extensión y una conexión ext_proc, lo que puede mejorar la latencia en comparación con el uso de extensiones separadas para los perfiles de REQUEST_AUTHZ y CONTENT_AUTHZ.

Autorización basada en atributos del protocolo de MCP

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

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

Configura la política de autorización.

Ejemplo de política de ALLOW

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

Cuando escribas una política de ALLOW, asegúrate de especificar baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS para que las RPC de MCP no específicas del acceso, como las de 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 de DENY

En este ejemplo, se rechaza el acceso a todos los métodos o instrucciones de un servidor de MCP detrás de una puerta de enlace de agentes.

$ 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

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, estas 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:

Para conocer las limitaciones aplicables a todas las extensiones, consulta Limitaciones de las extensiones.
Para conocer las limitaciones aplicables a los textos destacados, consulta Limitaciones de los textos destacados.

¿Qué sigue?

Guía

Puerta de enlace del agente de supervisión

Obtén más información para supervisar Agent Gateway.

Delega la autorización con Service Extensions Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Extensiones de autorización

Antes de comenzar

Configura políticas de autorización con extensiones

Delega la autorización a IAP

Delega la autorización a Model Armor

Console

gcloud

Del agente a cualquier lugar

De cliente a agente

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

Combina la autorización de IAP con las protecciones de Model Armor

Autorización basada en atributos del protocolo de MCP

Limitaciones

¿Qué sigue?

Puerta de enlace del agente de supervisión

Delega la autorización con Service Extensions