Risolvi i problemi relativi alle policy di accesso unificato IAM

Questo documento ti aiuta a diagnosticare e risolvere i problemi comuni durante la configurazione e l'applicazione delle Unified Access Policies (UAP) IAM per l'uscita di Agent Gateway.

Applicazione delle policy ed errori di accesso

Questa sezione descrive i problemi relativi all'applicazione.

La policy non viene applicata

Sintomo: un agente può accedere a strumenti di destinazione, server MCP o endpoint anche se è stata configurata una regola di negazione IAM o una regola di autorizzazione restrittiva per bloccare l'accesso.

Causa: l'estensione dell'autorizzazione di Agent Gateway è in esecuzione in modalità dry run oppure l'ambito dell'associazione della policy non corrisponde alla risorsa di destinazione. In modalità dry run, le decisioni di accesso vengono valutate e registrate per l'audit, ma le richieste non vengono mai bloccate.

Soluzione:

  1. Passa dalla modalità dry run alla modalità di applicazione forzata: innanzitutto, controlla il file di configurazione dell'estensione di autorizzazione (iap-request-authz-extension.yaml). Se iamEnforcementMode è impostato su "DRY_RUN", aggiornalo a "ENFORCE" (o rimuovi l'impostazione DRY_RUN) e reimporta l'estensione utilizzando gcloud CLI:

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

    Sostituisci quanto segue:

    • EXTENSION_NAME: il nome dell'estensione di autorizzazione
    • EXTENSION_FILE: il nome file della configurazione dell'estensione YAML
    • LOCATION: la Google Cloud regione in cui viene eseguito il deployment del gateway

  2. Verifica la delega della policy di autorizzazione del gateway: verifica che la policy di autorizzazione del gateway (policyProfile: REQUEST_AUTHZ) sia associata all' istanza di Agent Gateway corretta (target.resources).

  3. Controlla l'ambito dell'associazione della policy: verifica che la UAP IAM sia associata all'ambito della risorsa di destinazione in cui arriva il traffico.

  4. Esamina la precedenza delle regole: in una policy combinata, le regole di negazione sostituiscono esplicitamente le regole di autorizzazione nello stesso ambito. Tuttavia, verifica se una UAP con una regola di autorizzazione più ampia associata a livello di registry o progetto concede l'accesso senza restrizioni di condizione.

La policy applicata blocca l'accesso dell'agente

Sintomo: la richiesta in uscita di un agente non riesce con un errore HTTP 403 Forbidden o PERMISSION_DENIED quando l'applicazione della policy di Agent Gateway è abilitata.

Cause:

  • L'identità dell'agente non è specificata nella UAP.

  • All'identità dell'agente non è stata concessa l'autorizzazione iap.resources.egressViaIAP sulla risorsa di destinazione.

  • Il nome host di destinazione esatto non è registrato in Agent Registry

  • Gli attributi della richiesta non soddisfano le condizioni CEL (Common Expression Language) nella UAP.

Soluzione:

  1. Passa alla modalità dry run per il debug non distruttivo: durante la diagnosi dell'errore, passa temporaneamente l'estensione dell'autorizzazione alla modalità dry run (iamEnforcementMode: "DRY_RUN") in modo che il traffico degli agenti attivi non venga bloccato mentre esamini gli audit log.

  2. Esegui query su Cloud Audit Logs: esegui query su Cloud Audit Logs per esaminare il controllo di autorizzazione esatto e la valutazione degli attributi CEL:

    gcloud

    Esegui il seguente 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

    Sostituisci PROJECT_ID con l'ID progetto.

    Console

    1. Nella Google Cloud console, vai alla pagina Esplora log.
    2. Seleziona il progetto.
    3. Nell'editor di query, inserisci la seguente query: 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. Fai clic su Esegui query.
    5. Espandi la voce di log ed esamina protoPayload.authorizationInfo per vedere quale URI della risorsa di destinazione e autorizzazione non è stata valutata.

  3. Verifica la corrispondenza esatta del nome host: Agent Gateway fa corrispondere i nomi host di destinazione esattamente. Un'API di Google o un servizio di terze parti potrebbe essere risolto tramite più varianti di nomi host a seconda della versione dell'SDK , della configurazione del client regionale o dell'utilizzo di mTLS, ad esempio us-central1-aiplatform.googleapis.com rispetto a us-central1-aiplatform.mtls.googleapis.com rispetto a aiplatform.googleapis.com.

    • Se utilizzi target registrati, assicurati che ogni variante esatta del nome host sia registrata in Agent Registry.
    • Se l'agente accede a endpoint non registrati, verifica che un policy di endpoint non registrati conceda iap.resources.egressViaIAP per l'host e il percorso.

  4. Verifica la copertura dell'associazione della policy negli ambiti: verifica se esiste un'associazione della policy in uno dei tre ambiti supportati:

    • A livello di registry: concede l'accesso a tutti gli agenti, i server MCP e gli endpoint nel registry.
    • Per risorsa: concede l'accesso a un server MCP registrato specifico, un endpoint o un agente.
    • Endpoint non registrati: concede l'accesso alle destinazioni esterne ad Agent Registry.
    • Nota: quando descrivi le associazioni delle policy per una risorsa di destinazione, se l' output restituito contiene un campo "etag" ma nessuna associazione, non esiste alcuna policy IAM per la destinazione.

Messaggi di errore comuni dell'interfaccia utente, di gcloud e dell'API REST

Questa sezione descrive i messaggi di errore e come risolverli.

Policy non trovata

Messaggio di errore:

  • Interfaccia utente della console: "La policy richiesta non esiste. Verifica che la policy esista per la risorsa selezionata."
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Causa: l'ID UAP specificato nella richiesta di aggiornamento o nell'associazione della policy non esiste nel progetto o nella località oppure è stato eliminato.

Soluzione: elenca tutte le UAP disponibili nel tuo progetto utilizzando gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global per confermare l'ID e la località esatti della policy prima di associarla o aggiornarla.

Limite di associazione target superato

Messaggio di errore:

  • Interfaccia utente della console: "Il target selezionato ha raggiunto il limite per le associazioni delle policy di accesso. Elimina un'associazione esistente prima di aggiungerne una nuova."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Causa: hai tentato di collegare più associazioni di policy a una risorsa di destinazione (ad esempio un server MCP o un registry) rispetto al limite massimo consentito per target.

Soluzione: anziché creare una UAP e un' associazione separate per ogni singola regola, consolida più regole di autorizzazione o negazione in una singola UAP. Rimuovi le associazioni inutilizzate utilizzando gcloud iam policy-bindings delete.

Limite di associazione della policy superato

Messaggio di errore:

  • Interfaccia utente della console: "La policy selezionata ha raggiunto il limite di associazioni. Elimina un'associazione esistente prima di aggiungerne una nuova."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Causa: una singola UAP è collegata a troppe risorse di destinazione distinte nel tuo progetto.

Soluzione: associa la policy a un ambito più ampio, ad esempio l'ambito a livello di registry (AgentRegistry) o l'ambito del progetto, e utilizza le condizioni degli attributi CEL (ad esempio destination.agent_registry.mcp_server.name) per controllare l'accesso ai singoli strumenti all'interno delle regole della policy.

Limite di condizioni superato

Messaggio di errore:

  • Interfaccia utente della console: "Questa policy ha raggiunto il numero massimo di condizioni degli attributi. Rimuovi alcune condizioni per salvare le modifiche."
  • API / gcloud: TOO_MANY_CONDITIONS / Condition limit exceeded for rule in policy.

Causa: una singola regola di autorizzazione o negazione contiene più condizioni degli attributi di controllo dell'accesso granulare (FGAC) o sottoespressioni complesse rispetto a quelle supportate in una singola regola.

Soluzione: consolida i controlli degli attributi utilizzando gli operatori logici CEL (&&, ||) o imposta le ricerche di inclusione (in) oppure suddividi le espressioni in più regole all'interno della stessa UAP.

Dettagli della regola obsoleti

Messaggio di errore:

  • Interfaccia utente della console: "I dettagli della regola sono obsoleti. Questa regola è stata modificata da un altro utente dopo il caricamento di questa pagina. Aggiorna la pagina per recuperare i dettagli correnti prima di eliminare o apportare modifiche."
  • API / gcloud: HTTP 412 Precondition Failed / ABORTED due to etag mismatch.

Causa: un altro amministratore o un processo automatizzato ha modificato la UAP dopo che l'hai recuperata, causando la differenza tra l' etag della tua richiesta e lo stato del server attivo.

Soluzione: aggiorna la pagina della console per recuperare i dettagli della policy attiva e etag prima di salvare le modifiche. Quando utilizzi l'API REST, esegui prima una GET richiesta per recuperare il valore attivo "etag" e includilo nel payload della tua PATCH richiesta.

Impossibile eliminare l'ultima regola in una policy

Messaggio di errore:

  • Interfaccia utente della console: "Impossibile eliminare questa regola. La "policy predefinita" deve contenere almeno una regola. Per rimuovere questa regola, elimina la policy." o "Questa è l'ultima regola in <nome policy>. Se la elimini, verrà eliminata anche la policy e verranno rimosse definitivamente tutte le associazioni associate, il che può influire sull'accesso degli agenti alle risorse."

Causa: una UAP IAM non può essere salvata senza regole.

Soluzione: se vuoi rimuovere l'unica regola in una policy, elimina l' intera policy. Ricorda che devi eliminare tutte le associazioni di policy che fanno riferimento alla policy prima di poter eliminare la policy stessa.

Espressione CEL personalizzata conservata nella scheda Avanzate

Messaggio di errore:

  • Interfaccia utente della console: "Impossibile convertire l'espressione CEL personalizzata in selezioni UI standard. L'espressione viene conservata nella scheda Avanzate."

Causa: hai inserito una condizione o una funzione CEL complessa nell'editor di condizioni (scheda Avanzate) che non può essere mappata nei selettori a discesa semplificati del generatore di condizioni standard.

Soluzione: questo messaggio è una notifica informativa. La condizione CEL personalizzata è valida e viene conservata. Continua ad apportare modifiche direttamente nella scheda Editor di condizioni.

Passaggi successivi