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

Delegar autorização com Service Extensions

Use esta página para saber como delegar a autorização do Agent Gateway ao Identity-Aware Proxy, ao Model Armor e a outros mecanismos de autorização personalizados usando Service Extensions.

As políticas de autorização permitem aplicar políticas de controle de acesso e governança centralizadas ao tráfego que passa pelo endpoint publicado pelo Agent Gateway. Essas políticas permitem gerenciar o tráfego controlando o acesso com base em identidades mTLS, atributos de solicitação e resposta e até mesmo personalizar com base nos atributos específicos do protocolo usado (por exemplo, servidores MCP).

As políticas de autorização usam perfis de política para determinar o tipo de autorização a ser realizada. É possível usar uma política de autorização baseada em solicitação (REQUEST_AUTHZ) que depende de informações nos cabeçalhos de solicitação HTTP para permitir ou negar o tráfego. Como alternativa, use uma política de autorização baseada em conteúdo (CONTENT_AUTHZ) quando precisar realizar uma inspeção mais detalhada dos payloads do aplicativo para permitir ou negar o tráfego.

Para saber mais sobre políticas de autorização, perfis de política e casos de uso, consulte Visão geral das políticas de autorização.

Extensões de autorização

Às vezes, decisões de autorização complexas não podem ser expressas facilmente usando uma política de autorização. O Agent Gateway permite configurar políticas de autorização com extensões de autorização para delegar decisões de autorização a mecanismos de autorização personalizados.

Uma extensão de autorização permite interceptar e avaliar solicitações que passam por uma implantação do Agent Gateway. Ela faz uma chamada gRPC em tempo real para um serviço externo gerenciado por você, para que seja possível inspecionar, modificar ou até mesmo bloquear o tráfego antes que ele continue para o destino.

A extensão inspeciona os dados com base na política de autorização configurada. É possível configurar extensões de autorização separadamente para políticas de autorização baseadas em solicitação e conteúdo ou usar as duas para segurança abrangente.

Antes de começar

Antes de começar, verifique se você atende aos seguintes requisitos:

O Agent Gateway está implantado. Consulte Configurar o Agent Gateway.
Você precisa ter a permissão agentGateway.use do IAM no recurso do Agent Gateway implantado para poder anexar políticas de autorização ao gateway.

Configurar políticas de autorização com extensões

Esta seção mostra como configurar políticas de autorização que delegam decisões de autorização e segurança de conteúdo ao Identity-Aware Proxy, ao Model Armor e a outros serviços personalizados.

Delegar autorização ao IAP

É possível configurar uma extensão de autorização de solicitação para delegar decisões de acesso para políticas de autorização ao IAP.

As etapas a seguir mostram como configurar uma extensão de autorização com uma política de autorização para uma instância do Agent Gateway.

Crie as políticas de saída do IAM necessárias para seus agentes e ferramentas. Para mais informações, consulte Criar políticas de agente do IAM.
Consulte Configurar o Agent Gateway no modo Agente para qualquer lugar (saída) para ativar o IAP ao criar o Agent Gateway (usando o parâmetro Autorização de acesso).

O IAP exige que seus agentes sejam registrados no recurso do Registro de agentes vinculado ao gateway.
Configure uma extensão de autorização para apontar para o IAP.
1. Defina a extensão em um arquivo YAML. Use os valores de amostra fornecidos.
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF
```
  Se você quiser implantar a extensão em um modo de simulação somente auditoria para testar a política de autorização sem aplicá-la, especifique o campo DRY_RUN. Isso permite verificar sua política e minimizar o risco de interromper o tráfego devido a erros de configuração:
```
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
```
  Remova o campo de metadados DRY_RUN quando estiver tudo pronto para começar a aplicar as políticas.
2. Importe a extensão de autorização. Use o gcloud beta service-extensions authz-extensions import comando com os seguintes valores de amostra.
```
gcloud beta service-extensions authz-extensions import my-iap-request-authz-ext \
    --source=iap-request-authz-extension.yaml \
    --location=LOCATION
```

No mesmo projeto, configure uma política de autorização que delega a decisão à extensão.

Defina uma política de autorização que associa a extensão my-iap-request-authz-ext ao seu gateway. Use os valores de amostra fornecidos.

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

Substitua PROJECT_ID pelo seu ID do projeto.

Importe a política de autorização para o projeto. Use o gcloud beta network-security authz-policies import comando com os seguintes valores de amostra.

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

Delegar autorização ao Model Armor

É possível configurar uma extensão de autorização para delegar decisões de segurança de conteúdo para políticas de autorização ao Model Armor.

O exemplo a seguir mostra como configurar uma extensão de autorização com uma política de autorização para o Agent Gateway.

Console

Para usar o Google Cloud console para ativar o Model Armor para o Agent Gateway, siga estas etapas:

Crie os modelos do Model Armor necessários.
Consulte Configurar o Agent Gateway para ativar o Model Armor ao criar o Agent Gateway (usando a caixa de seleção Ativar o Model Armor). Os modelos do Model Armor são compatíveis com os modos Cliente para agente e Agente para qualquer lugar.
Se os modelos do Model Armor estiverem em um projeto diferente do gateway, conceda manualmente os papéis necessários à conta de serviço do Agent Gateway. A conta de serviço tem o formato: service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, em que PROJECT_NUMBER é o número do projeto em que você criou o gateway.

Conceda os seguintes papéis:
- Os papéis roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer no projeto que contém o gateway.
- O papel roles/modelarmor.user no projeto que contém os modelos do Model Armor.
Você precisará usar a CLI gcloud para concluir esta etapa.
```
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
```
Substitua:
- GATEWAY_PROJECT_ID: o ID do projeto em que você criou o gateway.
- GATEWAY_PROJECT_NUMBER: o número do projeto em que você criou o gateway.
- MODEL_ARMOR_PROJECT_ID: o ID do projeto que contém o modelo do Model Armor.
Se você estiver usando o gateway para o Agent Runtime, o Agente de serviço do mecanismo de raciocínio também vai exigir essas permissões, conforme documentado em Direcionar o tráfego do Agent Runtime pelo Agent Gateway.

gcloud

Crie os modelos do Model Armor necessários.
Se os modelos do Model Armor estiverem em um projeto diferente do gateway, conceda manualmente os papéis necessários à conta de serviço do Agent Gateway. A conta de serviço tem o formato: service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, em que PROJECT_NUMBER é o número do projeto em que você criou o gateway.

Conceda os seguintes papéis:
- Os papéis roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer no projeto que contém o gateway.
- O papel roles/modelarmor.user no projeto que contém o modelo do 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
```
Substitua:
- GATEWAY_PROJECT_ID: o ID do projeto em que você criou o gateway.
- GATEWAY_PROJECT_NUMBER: o número do projeto em que você criou o gateway.
- MODEL_ARMOR_PROJECT_ID: o ID do projeto que contém o modelo do Model Armor.

Configure a extensão de autorização para apontar para o Model Armor.

Defina a extensão em um arquivo YAML. Use os valores de amostra fornecidos.

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

Importe a extensão de autorização. Use o gcloud beta service-extensions authz-extensions import comando com os seguintes valores de amostra.

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

Configure uma política de autorização com a extensão.
1. Defina uma política de autorização que associa a extensão my-ma-content-authz-ext a um Agent Gateway.
  Agente para qualquer 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
  
  Observe o seguinte:
  
  O valor de policyProfile está definido como CONTENT_AUTHZ. Isso indica que o provedor de políticas personalizadas processa o tráfego de solicitação e resposta, incluindo o corpo da solicitação.
  
  O parâmetro httpRules demonstra como usar CEL atributos para criar condições que correspondam ao tráfego específico que você quer encaminhar ao Model Armor para avaliação. Neste exemplo, as regras correspondem a todo o tráfego com tipos de conteúdo application/json ou text/. Recomendamos o uso dessas regras para limitar a avaliação do Model Armor ao tráfego relevante. Isso permite rotear o tráfego compatível da API LLM, do MCP e do A2A para o Model Armor, excluindo o tráfego interno, como chamadas gRPC de agentes.
  Cliente para 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
  
  O valor de policyProfile está definido como CONTENT_AUTHZ. Isso indica que o provedor de políticas personalizadas processa o tráfego de solicitação e resposta, incluindo o corpo da solicitação.
2. Importe a política de autorização para o projeto. Use o gcloud beta network-security authz-policies import comando com os seguintes valores de amostra.
```
gcloud beta network-security authz-policies import my-ma-content-authz-policy \
  --source=ma-content-authz-policy.yaml \
  --location=LOCATION
```

Delegar autorização a extensões de autorização personalizadas

É possível configurar extensões de autorização personalizadas para delegar decisões a serviços personalizados. Essas extensões personalizadas só podem segmentar nomes de domínio totalmente qualificados (FQDNs).

Ao usar destinos de FQDN, a extensão usa o protocolo HTTP2 com criptografia TLS para se comunicar com endpoints na porta 443. No entanto, a extensão não valida o certificado do servidor. Portanto, para maior segurança, verifique se os endpoints resolvidos estão na rede VPC. Verifique também se o peering de DNS está configurado entre o projeto do Agent Gateway e a rede VPC.

Para configurar uma extensão de autorização com uma política de autorização para um FQDN específico, como mycustomauthz.internal.net, especifique-o como o valor de service no arquivo YAML da extensão, conforme mostrado no exemplo a seguir. Este exemplo pressupõe que você tenha implantado um servidor na rede VPC que implementa o 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
```

Crie a extensão de autorização para apontar para o serviço personalizado.

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

Depois de criar a extensão, configure uma política de autorização CUSTOM que delega decisões à extensão de autorização.

  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

Crie a política de autorização.

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

Observe que, quando uma extensão de autorização é associada a uma política de autorização usando o perfil REQUEST_AUTHZ, conforme demonstrado neste exemplo, o gateway invoca a extensão somente quando os cabeçalhos de solicitação chegam. O corpo da solicitação, os cabeçalhos de resposta e o corpo da resposta não ficam visíveis para a extensão de autorização.

Combinar a autorização do IAP com as proteções do Model Armor

Para segurança abrangente, recomendamos configurar uma política de autorização PERSONALIZADA com um perfil de política REQUEST_AUTHZ e outra política de autorização PERSONALIZADA com um perfil de política CONTENT_AUTHZ.

O exemplo a seguir usa o IAP como um sistema de autorização de solicitação centralizado e o Model Armor para proteções de IA. Como mostrado nos exemplos anteriores, é possível trocar cada um deles por extensões de serviço para usar suas próprias soluções personalizadas.

Configure uma extensão de autorização REQUEST_AUTHZ que delega ao IAP e uma política de autorização que aponta para a extensão.

Defina a extensão de autorização.

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

Crie a extensão de autorização.

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

Substitua LOCATION pela região da extensão.

Configure a política de autorização REQUEST_AUTHZ que delega à extensão.

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

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: o local dos recursos.
AGENT_GATEWAY_NAME: o nome do Agent Gateway.

Crie a política de autorização.

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

Configure uma extensão de autorização CONTENT_AUTHZ que delega ao Model Armor e uma política de autorização que aponta para a extensão.

Defina a extensão.

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

Substitua:

LOCATION: a região em que os modelos do Model Armor residem.
MODEL_ARMOR_PROJECT_ID: o ID do projeto que contém os modelos do Model Armor.
RESPONSE_TEMPLATE_ID: o ID do modelo de resposta.
REQUEST_TEMPLATE_ID: o ID do modelo de solicitação.

Crie a extensão de autorização.

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

Configure a política de autorização CONTENT_AUTHZ que delega à extensão.

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

Crie a política de autorização.

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

Quando uma extensão de autorização é associada a um perfil CONTENT_AUTHZ, ela recebe todos os eventos ext_proc, incluindo cabeçalhos de solicitação e resposta, corpo e trailers. Se a extensão de autorização baseada em ext_proc for capaz de processar a autorização de tempo de solicitação e a autorização baseada em conteúdo, recomendamos configurar uma única política de autorização CUSTOM com o perfil de política CONTENT_AUTHZ. Essa política precisa apontar para sua extensão de autorização versátil. Essa abordagem permite os dois tipos de autorização por meio de uma única extensão e conexão ext_proc, o que pode melhorar a latência em comparação com o uso de extensões separadas para perfis REQUEST_AUTHZ e CONTENT_AUTHZ.

Autorização com base em atributos do protocolo MCP

O Agent Gateway analisa o payload do protocolo MCP em uma solicitação e disponibiliza os atributos extraídos para políticas de autorização.

É possível restringir o acesso com base em parâmetros de método MCP, como os nomes de ferramentas específicas. Esta seção mostra dois exemplos, um para uma política ALLOW e outro para DENY.

Configure a política de autorização.

Exemplo de política ALLOW

Este exemplo permite o acesso a um conjunto específico de ferramentas no servidor MCP e aos recursos do protocolo de base, mas não permite o acesso a prompts e recursos.

Ao escrever uma política ALLOW, especifique baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS para que RPCs MCP não específicos de acesso, como inicialização, registro, conclusão, notificações e ping, continuem funcionando. Caso contrário, não será possível estabelecer uma sessão do 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

Exemplo de política DENY

Este exemplo não permite que todos os prompts/ métodos acessem um servidor MCP por trás de um 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

Crie a política de autorização.
```
gcloud beta network-security authz-policies import AUTHZ_POLICY_NAME \
--source=AUTH_POLICY_YAML_FILE_PATH \
--location=LOCATION
```
Substitua:
- AUTHZ_POLICY_NAME: o nome da política de autorização.
- AUTH_POLICY_YAML_FILE_PATH: o caminho para o arquivo YAML da política de autorização.
- LOCATION: o local dos recursos.

Limitações

As limitações a seguir se aplicam quando você usa políticas de autorização:

É possível configurar no máximo quatro políticas de autorização personalizadas por Agent Gateway, independentemente do perfil da política.
Se você usar extensões de autorização personalizadas com o perfil CONTENT_AUTHZ, elas precisarão oferecer suporte ao protocolo ext_proc e ao modo FULL_DUPLEX_STREAMED para eventos de corpo.
Se você configurar várias políticas de autorização personalizadas que usam o mesmo perfil, a ordem de execução delas não será garantida.

Além disso, consulte as seções a seguir para mais informações sobre as limitações das extensões de autorização:

Para limitações aplicáveis a todas as extensões, consulte Limitações de extensões.
Para limitações aplicáveis a chamadas, consulte Limitações de chamadas.

A seguir

Guia

Monitorar o Agent Gateway

Saiba como monitorar o Agent Gateway.

Delegar autorização com Service Extensions Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Extensões de autorização

Antes de começar

Configurar políticas de autorização com extensões

Delegar autorização ao IAP

Delegar autorização ao Model Armor

Console

gcloud

Agente para qualquer lugar

Cliente para agente

Delegar autorização a extensões de autorização personalizadas

Combinar a autorização do IAP com as proteções do Model Armor

Autorização com base em atributos do protocolo MCP

Limitações

A seguir

Monitorar o Agent Gateway

Delegar autorização com Service Extensions