Fehlerbehebung bei IAM Unified Access Policies

Dieses Dokument hilft Ihnen bei der Diagnose und Behebung häufiger Probleme bei der Konfiguration und Erzwingung von IAM Unified Access Policies (UAPs) für ausgehenden Traffic über Agent Gateway.

Richtlinienerzwingung und Zugriffsfehler

In diesem Abschnitt werden Probleme bei der Erzwingung beschrieben.

Richtlinie wird nicht erzwungen

Symptom: Ein Agent kann auf Zieltools, MCP-Server oder Endpunkte zugreifen , obwohl eine IAM-Ablehnungsregel oder eine restriktive Zulassungsregel konfiguriert wurde , um den Zugriff zu blockieren.

Ursache: Die Autorisierungserweiterung von Agent Gateway wird im Probelaufmodus ausgeführt oder der Bereich der Richtlinienbindung stimmt nicht mit der Ziel ressource überein. Im Probelaufmodus werden Zugriffsentscheidungen ausgewertet und für Audits protokolliert, Anfragen werden jedoch nie blockiert.

Lösung:

  1. Probelaufmodus in erzwungenen Modus umstellen: Prüfen Sie zuerst die Konfigurationsdatei der Autorisierungserweiterung (iap-request-authz-extension.yaml). Wenn iamEnforcementMode auf "DRY_RUN" gesetzt ist, ändern Sie es in "ENFORCE" oder entfernen Sie die Einstellung DRY_RUN und importieren Sie die Autorisierungserweiterung mit der gcloud CLI neu:

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

    Ersetzen Sie Folgendes:

    • EXTENSION_NAME: der Name Ihrer Autorisierungserweiterung
    • EXTENSION_FILE: der Dateiname Ihrer YAML-Erweiterungskonfiguration
    • LOCATION: die Cloud de Confiance Region, in der Ihr Gateway bereitgestellt wird

  2. Delegierung der Gateway-Autorisierungsrichtlinie prüfen: Prüfen Sie, ob Ihre Gateway-Autorisierungsrichtlinie (policyProfile: REQUEST_AUTHZ) an die richtige Agent Gateway-Instanz (target.resources) gebunden ist.

  3. Bereich der Richtlinienbindung prüfen: Prüfen Sie, ob die IAM UAP an den Bereich der Zielressource gebunden ist, in dem der Traffic eingeht.

  4. Vorrang von Regeln prüfen: In einer kombinierten Richtlinie überschreiben Ablehnungsregeln Zulassungsregeln im selben Bereich explizit. Prüfen Sie jedoch, ob eine UAP mit einer umfassenderen Zulassungsregel, die auf Registry- oder Projektebene gebunden ist, Zugriff ohne Bedingungseinschränkungen gewährt.

Richtlinie zur Durchsetzung blockiert den Zugriff des Agenten

Symptom: Die Anfrage für ausgehenden Traffic eines Agenten schlägt mit einem HTTP-Fehler 403 Forbidden oder PERMISSION_DENIED fehl, wenn die Richtlinienerzwingung von Agent Gateway aktiviert ist.

Ursachen:

  • Die Identität des Agenten ist in der UAP nicht angegeben.

  • Der Identität des Agenten wurde nicht die Berechtigung iap.resources.egressViaIAP für die Zielressource gewährt.

  • Der genaue Hostname des Ziels ist nicht in der Agent Registry registriert.

  • Die Anfrageattribute erfüllen nicht die CEL-Bedingungen (Common Expression Language) in der UAP.

Lösung:

  1. Für nicht störende Fehlerbehebung in den Probelaufmodus wechseln: Wechseln Sie während der Diagnose des Fehlers vorübergehend die Autorisierungserweiterung in den Probelaufmodus (iamEnforcementMode: "DRY_RUN"), damit der aktive Agententraffic nicht blockiert wird, während Sie die Audit-Logs prüfen.

  2. Cloud-Audit-Logs abfragen: Fragen Sie Cloud-Audit-Logs ab, um die genaue Autorisierungsprüfung und CEL-Attributauswertung zu prüfen:

    gcloud

    Führen Sie den folgenden Befehl gcloud logging read aus:

    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

    Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

    Console

    1. Rufen Sie in der Cloud de Confiance Console die Seite Log-Explorer auf.
    2. Wählen Sie Ihr Projekt aus.
    3. Geben Sie im Abfrageeditor die folgende Abfrage ein: 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. Klicken Sie auf Abfrage ausführen.
    5. Maximieren Sie den Logeintrag und prüfen Sie protoPayload.authorizationInfo, um zu sehen, für welche Zielressourcen-URI und Berechtigung die Auswertung fehlgeschlagen ist.

  3. Genaue Hostnamenübereinstimmung prüfen: Agent Gateway gleicht Zielhostnamen genau ab. Eine Google API oder ein Drittanbieterdienst kann je nach SDK Version, regionaler Clientkonfiguration oder mTLS-Nutzung über mehrere Hostnamenvarianten aufgelöst werden, z. B. us-central1-aiplatform.googleapis.com im Vergleich zu us-central1-aiplatform.mtls.googleapis.com im Vergleich zu aiplatform.googleapis.com.

    • Wenn Sie sich auf registrierte Ziele verlassen, muss jede genaue Hostnamenvariante in der Agent Registry registriert sein.
    • Wenn der Agent auf nicht registrierte Endpunkte zugreift, prüfen Sie, ob eine Richtlinie für nicht registrierte Endpunkte die Berechtigung iap.resources.egressViaIAP für diesen Host und Pfad gewährt.

  4. Richtlinienbindungsabdeckung in allen Bereichen prüfen: Prüfen Sie, ob eine Richtlinien bindung in einem der drei unterstützten Bereiche vorhanden ist:

    • Registry-weit: Gewährt Zugriff auf alle Agenten, MCP-Server und Endpunkte in der Registry.
    • Pro Ressource: Gewährt Zugriff auf einen bestimmten registrierten MCP-Server, Endpunkt oder Agenten.
    • Nicht registrierte Endpunkte: Gewährt Zugriff auf Ziele außerhalb der Agent Registry.
    • Hinweis: Wenn Sie Richtlinienbindungen für eine Zielressource beschreiben und die zurückgegebene Ausgabe ein Feld "etag", aber keine Bindungen enthält, ist keine IAM-Richtlinie für dieses Ziel vorhanden.

Häufige Fehlermeldungen in der UI, gcloud und der REST API

In diesem Abschnitt werden Fehlermeldungen und deren Behebung beschrieben.

Richtlinie nicht gefunden

Fehlermeldung:

  • Console-UI: "Die angeforderte Richtlinie ist nicht vorhanden. Prüfen Sie, ob die Richtlinie für die ausgewählte Ressource vorhanden ist."
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Ursache: Die in Ihrer Aktualisierungsanfrage oder Richtlinien bindung angegebene UAP-ID ist im Projekt oder Standort nicht vorhanden oder wurde gelöscht.

Lösung: Listen Sie alle verfügbaren UAPs in Ihrem Projekt mit gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global auf, um die genaue Richtlinien-ID und den Standort zu bestätigen, bevor Sie sie binden oder aktualisieren.

Limit für Zielbindungen überschritten

Fehlermeldung:

  • Console-UI: "Das ausgewählte Ziel hat das Limit für Zugriffs richtlinienbindungen erreicht. Löschen Sie eine vorhandene Bindung, bevor Sie eine neue hinzufügen."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Ursache: Sie haben versucht, mehr Richtlinienbindungen an eine Zielressource (z. B. einen MCP-Server oder eine Registry) anzuhängen, als das maximal zulässige Limit pro Ziel.

Lösung: Anstatt für jede einzelne Regel eine separate UAP und Bindung zu erstellen, fassen Sie mehrere Zulassungs- oder Ablehnungsregeln in einer einzigen UAP zusammen. Entfernen Sie nicht verwendete Bindungen mit gcloud iam policy-bindings delete.

Limit für Richtlinienbindungen überschritten

Fehlermeldung:

  • Console-UI: "Die ausgewählte Richtlinie hat das Limit für Bindungen erreicht. Löschen Sie eine vorhandene Bindung, bevor Sie eine neue hinzufügen."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Ursache: Eine einzelne UAP ist an zu viele verschiedene Zielressourcen in Ihrem Projekt angehängt.

Lösung: Binden Sie die Richtlinie in einem umfassenderen Bereich, z. B. im Registry-weiten Bereich (AgentRegistry) oder im Projektbereich, und verwenden Sie CEL-Attributbedingungen (z. B. destination.agent_registry.mcp_server.name), um den Zugriff auf einzelne Tools in den Richtlinienregeln zu steuern.

Limit für Bedingungen überschritten

Fehlermeldung:

  • Console-UI: "Diese Richtlinie hat die maximale Anzahl von Attributbedingungen erreicht. Entfernen Sie einige Bedingungen, um die Änderungen zu speichern."
  • API / gcloud: TOO_MANY_CONDITIONS / Condition limit exceeded for rule in policy.

Ursache: Eine einzelne Zulassungs- oder Ablehnungsregel enthält mehr Attributbedingungen für die detaillierte Zugriffssteuerung (Fine-Grained Access Control, FGAC) oder komplexe Unterausdrücke als in einer einzelnen Regel unterstützt.

Lösung: Fassen Sie Attributprüfungen mit logischen CEL-Operatoren (&&, ||) zusammen oder legen Sie Inklusionssuchen (in) fest. Alternativ können Sie Ihre Ausdrücke auf mehrere Regeln innerhalb derselben UAP aufteilen.

Veraltete Regeldetails

Fehlermeldung:

  • Console-UI: "Regeldetails sind veraltet. Diese Regel wurde von einem anderen Nutzer geändert, nachdem diese Seite geladen wurde. Aktualisieren Sie die Seite, um die aktuellen Details abzurufen, bevor Sie sie bearbeiten oder löschen."
  • API / gcloud: HTTP 412 Precondition Failed / ABORTED aufgrund von etag Abweichung.

Ursache: Ein anderer Administrator oder ein automatisierter Prozess hat die UAP geändert, nachdem Sie sie abgerufen haben. Dadurch unterscheidet sich das etag vom aktiven Serverstatus.

Lösung: Aktualisieren Sie die Console-Seite, um die aktiven Richtliniendetails und etag abzurufen, bevor Sie Ihre Änderungen speichern. Wenn Sie die REST API verwenden, führen Sie zuerst eine GET Anfrage aus, um den aktiven Wert von "etag" abzurufen, und fügen Sie ihn in die Nutzlast Ihrer PATCH Anfrage ein.

Die letzte Regel in einer Richtlinie kann nicht gelöscht werden

Fehlermeldung:

  • Console-UI: "Diese Regel kann nicht gelöscht werden. Die Standardrichtlinie muss mindestens eine Regel enthalten. Wenn Sie diese Regel entfernen möchten, löschen Sie stattdessen die Richtlinie." oder "Dies ist die letzte Regel in <Richtlinienname>. Wenn Sie sie löschen, wird auch die Richtlinie gelöscht und alle zugehörigen Bindungen werden dauerhaft entfernt. Dies kann sich auf den Zugriff des Agenten auf Ressourcen auswirken."

Ursache: Eine IAM-UAP kann nicht ohne Regeln gespeichert werden.

Lösung: Wenn Sie die einzige Regel in einer Richtlinie entfernen möchten, löschen Sie die gesamte Richtlinie. Beachten Sie, dass Sie alle Richtlinienbindungen löschen müssen, die auf die Richtlinie verweisen, bevor Sie die Richtlinie selbst löschen können.

Benutzerdefinierter CEL-Ausdruck auf dem Tab „Erweitert“ beibehalten

Fehlermeldung:

  • Console-UI: "Der benutzerdefinierte CEL-Ausdruck konnte nicht in Standard-UI-Auswahlen konvertiert werden. Ihr Ausdruck wird auf dem Tab „Erweitert“ beibehalten."

Ursache: Sie haben im Bedingungs editor (Tab „Erweitert“) eine komplexe CEL-Bedingung oder ‑Funktion eingegeben, die nicht den vereinfachten Drop-down Auswahlen des Standard-Bedingungseditors zugeordnet werden kann.

Lösung: Diese Meldung ist ein Informationshinweis. Ihre benutzerdefinierte CEL-Bedingung ist gültig und wird beibehalten. Nehmen Sie alle Änderungen direkt auf dem Tab Bedingungseditor vor.

Nächste Schritte