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 governança e controle de acesso centralizadas ao tráfego que passa pelo endpoint publicado pelo gateway do agente. 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 gateway do agente 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 gateway do agente. 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 gateway do agente está implantado. Consulte Configurar o gateway do agente.

  • Você precisa ter a permissão agentGateway.use do IAM no recurso do gateway do agente 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 a 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.

O exemplo a seguir mostra como configurar uma extensão de autorização com uma política de autorização para uma instância do gateway do agente.

Console

Para usar o Google Cloud console para ativar o IAP para o gateway do agente, siga estas etapas:

  1. 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.

  2. Consulte Configurar o gateway do agente no modo "Agente para qualquer lugar" (saída) para ativar o IAP ao criar o gateway do agente (usando o parâmetro Autorização de acesso).

    O IAP exige que seus agentes sejam registrados no recurso do registro do agente vinculado ao gateway.

gcloud

  1. Configure a 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
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
metadata: '
  iamEnforcementMode: DRY_RUN
'
EOF

    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

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

    1. Defina uma política de autorização que associa a extensão my-iap-authz-request-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.

    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-iap-request-authz-policy \
   --source=iap-request-authz-policy.yaml \
   --location=LOCATION

Delegar a 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 gateway do agente.

Console

Para usar o Google Cloud console para ativar o Model Armor para o gateway do agente, siga estas etapas:

  1. Crie os modelos do Model Armor necessários.

  2. Consulte Configurar o gateway do agente para ativar o Model Armor ao criar o gateway do 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".

  3. 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 gateway do agente. 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 ambiente de execução do agente, 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 ambiente de execução do agente pelo gateway do agente.

gcloud

  1. Crie os modelos do Model Armor necessários.

  2. 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 gateway do agente. 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.

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

    1. 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

    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-ma-content-authz-ext \
   --source=ma-content-authz-extension.yaml \
   --location=LOCATION

  4. 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 do 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

      Para políticas de autorização de conteúdo, o valor de policyProfile é definido como CONTENT_AUTHZ. Esse valor indica que o provedor de políticas personalizadas processa o tráfego de solicitação e resposta, incluindo o processamento do corpo.

    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 a 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).

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 gateway do agente e a rede VPC.

  1. 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
wireFormat: EXT_AUTHZ_GRPC
EOF

  2. 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

  3. 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

  4. 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 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. Conforme mostrado nos exemplos anteriores, é possível trocar cada um deles por extensões de serviço para usar suas próprias soluções personalizadas.

  1. 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.

    1. Defina a extensão de autorização.

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

    2. 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.

    3. 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.

    4. Crie a política de autorização.

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

  2. 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.

    1. 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.

    2. Crie a extensão de autorização.

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

    3. 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

    4. 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 gateway do agente 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.

  1. 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 gravar 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 atrás de um gateway do 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

  2. 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 gateway do agente, 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:

A seguir

Guia

Saiba como monitorar o gateway do agente.