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.

Com as políticas de autorização, é possível aplicar políticas centralizadas de controle de acesso e governança ao tráfego que passa pelo endpoint publicado pelo Agent Gateway. Com elas, é possível 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 usados (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ções (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 fazer uma inspeção mais detalhada dos payloads de aplicativos para permitir ou negar o tráfego.

Para saber mais sobre políticas de autorização, perfis de políticas e casos de uso, consulte a 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 facilmente expressas 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 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 até 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 com base em solicitações e conteúdo ou usar as duas para uma segurança abrangente.

Antes de começar

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

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

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

Nesta seção, mostramos como configurar políticas de autorização que delegam decisões de autorização e segurança de conteúdo ao Identity-Aware Proxy, Model Armor e 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 gateway de agente no modo Agente para qualquer lugar (saída) para ativar o IAP ao criar o gateway de agente (usando o parâmetro Autorização de acesso).

O IAP exige que seus agentes sejam registrados com o recurso Agent Registry 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 interrupção do 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 comando gcloud beta service-extensions authz-extensions import com os seguintes valores de exemplo.
```
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 delegue a decisão à extensão.

Defina uma política de autorização que associe 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 ID do projeto.

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

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 e ativar o Model Armor para o Agent Gateway, siga estas etapas:

Crie os modelos do Model Armor necessários.
Consulte Configurar o gateway de agente para ativar o Model Armor ao criar o gateway de agente (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.
- A função 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 tempo de execução do agente, o agente de serviço do Reasoning Engine também vai precisar dessas permissões, conforme documentado em Encaminhar o tráfego do tempo de execução do agente pelo gateway do agente.

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.
- A função 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 comando gcloud beta service-extensions authz-extensions import 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 gateway de agente.
  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 é definido como CONTENT_AUTHZ. Isso indica que o provedor de política personalizada processa o tráfego de solicitação e resposta, incluindo o corpo da solicitação.
  
  O parâmetro httpRules demonstra como usar atributos da CEL para criar condições que correspondam ao tráfego específico que você quer encaminhar para o 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 usar essas 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 do agente.
  Do cliente para o 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 é definido como CONTENT_AUTHZ. Isso indica que o provedor de política personalizada 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 comando gcloud beta network-security authz-policies import com os seguintes valores de exemplo.
```
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 podem segmentar apenas nomes de domínio totalmente qualificados (FQDNs).

Quando você usa destinos 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 aumentar a 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 gateway do agente e sua 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 sua rede VPC implementando 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

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 da IAP com as barreiras de proteção do Model Armor

Para uma segurança abrangente, recomendamos que você configure 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 a 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 gateway do agente.

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 do 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 seus modelos do Model Armor estão localizados.
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 no momento da 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 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étodos do MCP, como os nomes de ferramentas específicas. Esta seção mostra dois exemplos, um para uma política do ALLOW e outro para o DENY.

Configure a política de autorização.

Exemplo de política de ALLOW

Este exemplo permite o acesso a um conjunto específico de ferramentas no servidor MCP e aos recursos do protocolo básico, mas não permite o acesso a solicitações e recursos.

Ao escrever uma política ALLOW, especifique baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS para que RPCs do MCP não específicos de acesso, como inicialização, geração de registros, 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 de DENY

Este exemplo não permite que todos os comandos/ acessos de método a um servidor MCP por trás de um gateway de agente.

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 seguintes limitações se aplicam ao usar políticas de autorização:

É possível configurar até quatro políticas de autorização personalizadas por gateway do agente, independente do perfil de política.
Se você usar extensões de autorização personalizadas com o perfil CONTENT_AUTHZ, elas precisam 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 das extensões.
Para limitações aplicáveis aos callouts, consulte Limitações dos callouts.

A seguir

Guia

Gateway do agente de monitoramento

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

Do cliente para o agente

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

Combinar a autorização da IAP com as barreiras de proteção do Model Armor

Autorização com base em atributos do protocolo MCP

Limitações

A seguir

Gateway do agente de monitoramento

Delegar autorização com Service Extensions