Resolver problemas de políticas de acesso unificadas do IAM

Este documento ajuda você a diagnosticar e resolver problemas comuns ao configurar e aplicar as Políticas de Acesso Unificadas (PAUs) do IAM para a saída do Gateway de Agente.

Falhas de aplicação de políticas e acesso

Esta seção descreve problemas com a aplicação.

A política não está sendo aplicada

Sintoma: um agente pode acessar ferramentas, servidores MCP ou endpoints de destino mesmo que uma regra de negação ou permissão restritiva do IAM tenha sido configurada para bloquear o acesso.

Causa: a extensão de autorização do Gateway de Agente está sendo executada no modo de teste ou o escopo de vinculação da política não corresponde ao recurso de destino. No modo de teste, as decisões de acesso são avaliadas e registradas para auditoria, mas as solicitações nunca são bloqueadas.

Solução:

  1. Mude o modo de teste para o modo restrito: primeiro, verifique o arquivo de configuração da extensão de autorização (iap-request-authz-extension.yaml). Se iamEnforcementMode estiver definido como "DRY_RUN", atualize para "ENFORCE" (ou remova a configuração DRY_RUN) e importe novamente a extensão usando a CLI gcloud:

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    Substitua:

    • EXTENSION_NAME: o nome da extensão de autorização
    • EXTENSION_FILE: o nome do arquivo de configuração da extensão YAML
    • LOCATION: a Google Cloud região em que o gateway está implantado

  2. Verifique a delegação da política de autorização do gateway: verifique se a política de autorização do gateway (policyProfile: REQUEST_AUTHZ) está vinculada à instância correta do Gateway de Agente (target.resources).

  3. Verifique o escopo de vinculação da política: verifique se a UAP do IAM está vinculada ao escopo do recurso de destino em que o tráfego está chegando.

  4. Inspecione a precedência da regra: em uma política combinada, as regras de negação substituem explicitamente as regras de permissão no mesmo escopo. No entanto, verifique se um UAP com uma regra de permissão mais ampla, vinculada no nível do registro ou projeto, está concedendo acesso sem restrições condicionais.

A política de restrição bloqueia o acesso do agente

Sintoma: a solicitação de saída de um agente falha com um erro HTTP 403 Forbidden ou PERMISSION_DENIED quando a aplicação da política do Gateway de Agente está ativada.

Causas:

  • A identidade do agente não está especificada no UAP.

  • A identidade do agente não recebeu a permissão iap.resources.egressViaIAP no recurso de destino.

  • O nome do host de destino exato não está registrado no Agent Registry.

  • Os atributos da solicitação não satisfazem as condições da Common Expression Language (CEL) no UAP.

Solução:

  1. Mude para o modo de teste para depuração não destrutiva: ao diagnosticar a falha, mude temporariamente a extensão de autorização para o modo de teste (iamEnforcementMode: "DRY_RUN") para que o tráfego de agentes ativos não seja bloqueado enquanto você inspeciona os registros de auditoria.

  2. Consulte os registros de auditoria do Cloud: consulte os registros de auditoria do Cloud para inspecionar a verificação de autorização exata e a avaliação de atributos CEL:

    gcloud

    Execute o seguinte comando gcloud logging read:

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    Substitua PROJECT_ID pelo ID do projeto.

    Console

    1. No Google Cloud console do, acesse a página Análise de registros.
    2. Selecione o projeto.
    3. No Editor de consultas, insira a seguinte consulta: 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. Clique em Executar consulta.
    5. Expanda a entrada de registro e inspecione protoPayload.authorizationInfo para ver qual URI e permissão do recurso de destino falharam na avaliação.

  3. Verifique a correspondência exata do nome do host: o Gateway de Agente corresponde aos nomes de host de destino exatamente. Uma API do Google ou um serviço de terceiros pode ser resolvido por várias variações de nome de host, dependendo da versão do SDK, da configuração regional do cliente ou do uso de mTLS. Por exemplo, us-central1-aiplatform.googleapis.com em comparação com us-central1-aiplatform.mtls.googleapis.com em comparação com aiplatform.googleapis.com.

    • Se você depende de destinos registrados, verifique se todas as variações exatas de nome de host estão registradas no Agent Registry.
    • Se o agente acessar endpoints não registrados, verifique se uma política de endpoint não registrado concede iap.resources.egressViaIAP para esse host e caminho.

  4. Verifique a cobertura da vinculação de políticas em todos os escopos: verifique se uma vinculação de política existe em um dos três escopos compatíveis:

    • Em todo o registro: concede acesso a todos os agentes, servidores MCP e endpoints no registro.
    • Por recurso: concede acesso a um servidor MCP registrado específico, endpoint ou agente.
    • Endpoints não registrados: concede acesso a destinos fora do Agent Registry.
    • Observação: ao descrever vinculações de políticas para um recurso de destino, se a saída retornada contiver um campo "etag", mas nenhuma vinculação, não haverá política do IAM para esse destino.

Mensagens de erro comuns da API REST, da gcloud e da interface

Esta seção descreve as mensagens de erro e como resolvê-las.

Política não encontrada

Mensagem de erro:

  • Interface do console: "A política solicitada não existe. Verifique se a política existe para o recurso selecionado."
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Causa: O ID UAP especificado em sua solicitação de atualização ou política binding não existe no projeto ou local, ou foi excluído.

Solução: liste todas as PAUs disponíveis no projeto usando gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global para confirmar o ID e o local exatos da política antes de vinculá-la ou atualizá-la.

Limite de vinculação de destino excedido

Mensagem de erro:

  • Interface do console: "O destino selecionado atingiu o limite de vinculações de políticas de acesso. Exclua uma vinculação antes de adicionar uma nova."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Causa: você tentou anexar mais vinculações de políticas a um recurso de destino (como um servidor MCP ou registro) do que o limite máximo permitido por destino.

Solução: Em vez de criar um UAP e um binding separados para cada regra individual, consolide várias regras de permissão ou negação em um único UAP. Remova as vinculações não utilizadas usando gcloud iam policy-bindings delete.

Limite de vinculação de políticas excedido

Mensagem de erro:

  • Interface do console: "A política selecionada atingiu o limite de vinculações. Exclua uma vinculação antes de adicionar uma nova."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Causa: Um único UAP está associado a muitos recursos de destino distintos em todo o seu projeto.

Solução: vincule a política em um escopo mais amplo, como o escopo de todo o registro (AgentRegistry) ou o escopo do projeto, e use condições de atributo CEL (como destination.agent_registry.mcp_server.name) para controlar o acesso a ferramentas individuais nas regras de política.

Limite de condição excedido

Mensagem de erro:

  • Interface do console: "Esta política atingiu o número máximo de condições de atributo Remova algumas condições para salvar as mudanças."
  • API / gcloud: TOO_MANY_CONDITIONS / Limite de condição excedido para regra na política.

Causa: uma única regra de permissão ou negação contém mais condições de atributo de controle de acesso refinado (FGAC, na sigla em inglês) ou subexpressões complexas do que o permitido em uma única regra.

Solução: Consolide as verificações de atributos usando operadores lógicos CEL (&&, ||) ou pesquisas de inclusão de conjunto (in), ou divida suas expressões em várias regras dentro do mesmo UAP.

Detalhes da regra desatualizados

Mensagem de erro:

  • Interface do console: "Os detalhes da regra estão desatualizados. Esta regra foi modificada por outro usuário depois que esta página foi carregada. Atualize a página para buscar os detalhes atuais antes de editar ou excluir."
  • API / gcloud: HTTP 412 Precondition Failed / ABORTED devido a etag incompatibilidade.

Causa: Outro administrador ou processo automatizado modificou o UAP depois que você o recuperou, fazendo com que sua solicitaçãoetag difera do estado ativo do servidor.

Solução: atualize a página do console para recuperar os detalhes da política ativa e etag antes de salvar as edições. Ao usar a API REST, faça uma GET solicitação primeiro para recuperar o valor "etag" ativo e inclua-o no seu PATCH payload de solicitação.

Não é possível excluir a última regra em uma política

Mensagem de erro:

  • Interface do console: "Não é possível excluir esta regra. A política padrão precisa conter pelo menos uma regra. Para remover essa regra, exclua a política." ou "Esta é a última regra em <policy name>. A exclusão dela também vai excluir a política e remover permanentemente todas as vinculações associadas, o que pode afetar o acesso do agente aos recursos."

Causa: Um UAP do IAM não pode ser salvo com zero regras.

Solução: se você quiser remover a única regra em uma política, exclua a política inteira. Lembre-se de que é necessário excluir todas as vinculações de políticas que fazem referência à política antes de excluir a política em si.

Expressão CEL personalizada preservada na guia "Avançado"

Mensagem de erro:

  • Interface do console: "Não foi possível converter a expressão CEL personalizada em seleções de UI padrão. Sua expressão é preservada na guia "Avançado"."

Causa: você inseriu uma condição ou função CEL complexa no Editor de condições (guia "Avançado") que não pode ser mapeada para os seletores suspensos simplificados do criador de condições padrão.

Solução: essa mensagem é uma notificação informativa. Sua condição CEL personalizada é válida e preservada. Continue fazendo edições diretamente na guia Editor de condições.

A seguir