View a markdown version of this page

AgentCore Gateway und Richtlinie in AgentCore IAM-Berechtigungen - Amazon Grundgestein AgentCore
-ÜbersichtDie Ausführungsrolle „Gateway“Rolle „Ressourcenverwaltung“Wann sind Rollenaktualisierungen erforderlich?FehlerbehebungBeispiel: Beide IAM-Rollen erstellenBewährte Methoden

AgentCore Gateway und Richtlinie in AgentCore IAM-Berechtigungen

Dieses Handbuch enthält die erforderlichen IAM-Berechtigungen für die Verwendung von Amazon Bedrock AgentCore Gateway mit Policy in AgentCore für eine detaillierte Autorisierungskontrolle mithilfe von Cedar-Richtlinien.

-Übersicht

Bei der Integration von Amazon Bedrock AgentCore Gateway mit Policy in AgentCore sind zwei unterschiedliche IAM-Rollen erforderlich:

  1. Gateway-Ausführungsrolle — Die IAM-Rolle, die Amazon Bedrock AgentCore Gateway zur Laufzeit übernimmt, um Ziele aufzurufen und Cedar-Richtlinien auszuwerten

  2. Ressourcenverwaltungsrolle — Die IAM-Rolle, mit der Administratoren Amazon Bedrock AgentCore Gateway und Richtlinien in Ressourcen erstellen und verwalten AgentCore

Beide Rollen dienen unterschiedlichen Zwecken und erfordern spezifische Berechtigungen. Die Gateway-Ausführungsrolle benötigt Berechtigungen, um Amazon Bedrock AgentCore Gateway-Operationen auszuführen, während die Ressourcenverwaltungsrolle Berechtigungen zur Konfiguration und Verwaltung von Amazon Bedrock AgentCore Gateway und Policy in AgentCore Ressourcen benötigt.

Die Ausführungsrolle „Gateway“

Die Gateway-Ausführungsrolle wird vom Amazon Bedrock AgentCore Gateway-Service bei der Bearbeitung von Anfragen übernommen. Für diese Rolle sind folgende Berechtigungen erforderlich:

  • Evaluieren Sie die Richtlinien von Cedar mithilfe von Policy in AgentCore

  • Rufen Sie Ziele wie Lambda-Funktionen und API-Gateway-Endpunkte auf

  • Schreiben Sie Logs und Traces in und CloudWatch X-Ray

  • Zugriffsgeheimnisse für Authentifizierungskonfigurationen

Wichtig

Die Ausführungsrolle muss diese drei Berechtigungen zur Verwendung von Amazon Bedrock AgentCore Gateway mit Richtlinie in enthalten AgentCore:. bedrock-agentcore:AuthorizeAction - Evaluiert die Richtlinien von Cedar für Autorisierungsentscheidungen. bedrock-agentcore:PartiallyAuthorizeActions - Listet Tools auf, zu deren Aufruf der Anrufer berechtigt ist. bedrock-agentcore:GetPolicyEngine - Ruft die Policy-Engine-Konfiguration ab Ohne diese Berechtigungen kann das Gateway keine Richtlinienautorisierung durchführen. Dies äußert sich auf zwei Arten: Das Anhängen einer Policy-Engine an ein vorhandenes Gateway führt zu einer InternalServerException, und alle Tool-Aufrufe werden standardmäßig verweigert, selbst wenn Sie Genehmigungsrichtlinien konfiguriert haben.

Vertrauensrichtlinie

Die Gateway-Ausführungsrolle muss dem Dienstprinzipal vertrauen. bedrock-agentcore.amazonaws.com

Wichtig

Ersetzen Sie die folgenden Platzhalter: * us-east-1 durch die AWS Region * 123456789012 durch die AWS Konto-ID

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBedrockAgentCoreAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

Berechtigungsrichtlinie

Diese Richtlinie gewährt Amazon Bedrock AgentCore Gateway die erforderlichen Berechtigungen, um die Richtlinien von Cedar über Policy in AgentCore zu bewerten. Die Berechtigungen sind nach dem Prinzip der geringsten Rechte in zwei Anweisungen aufgeteilt.

Wichtig

Ersetzen Sie diese Platzhalter: * us-east-1 durch die AWS Region * durch die AWS Konto-ID * 123456789012 <gateway-id> durch die Gateway-ID (oder verwenden Sie * für alle Gateways) * durch die Policy-Engine-ID (oder verwenden Sie * <policy-engine-id> für alle Policy-Engines)

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
      ]
    }
  ]
}
Anmerkung

* Je nach Amazon Bedrock AgentCore Gateway-Integrationstyp (z. B. Lambda-Funktionen, API Gateway Gateway-Endpunkte) können zusätzliche Berechtigungen erforderlich sein. Diese Berechtigungen sind hier nicht enthalten, da sie je nach spezifischer Integration variieren. * Für die Produktion: Ersetzen Sie die Platzhalter durch spezifische Ressourcen-IDs (z. B. policy-engine/my-policy-engine-id anstelle vonpolicy-engine/<policy-engine-id>), um den Prinzipien der geringsten Rechte zu folgen, oder verwenden Sie Platzhalter (*), um den Zugriff auf alle Ressourcen dieses Typs zu ermöglichen.

Rolle „Ressourcenverwaltung“

Die Ressourcenverwaltungsrolle wird von Administratoren verwendet, um Amazon Bedrock AgentCore Gateway und Richtlinien in AgentCore Ressourcen zu erstellen und zu verwalten. Für diese Rolle sind folgende Berechtigungen erforderlich:

  • Gateways und Gateway-Ziele erstellen, aktualisieren und löschen

  • Policy Engines und Cedar-Richtlinien erstellen, aktualisieren und löschen

  • Rufen Sie das Gateway während der Richtlinienerstellung auf (InvokeGateway), damit Policy in die Aktionen in einer Cedar-Anweisung anhand der Funktionen des Ziel-Gateways validieren AgentCore kann

  • Übergeben Sie die Gateway-Ausführungsrolle bei der Erstellung an Amazon Bedrock AgentCore Gateway-Ressourcen

  • Kennzeichnen Sie Ressourcen für Organisation und Management

  • Lesen Sie die IAM-Rolleninformationen, um die Konfigurationen der Ausführungsrollen zu überprüfen

Diese Rolle ist unabhängig von der Gateway-Ausführungsrolle und wird nur benötigt, wenn Amazon Bedrock AgentCore Gateway und Policy in AgentCore Konfigurationen eingerichtet oder geändert werden.

Berechtigungsrichtlinie

Wichtig

Ersetzen Sie diese Platzhalter: * us-east-1 durch die AWS Region * 123456789012 durch die AWS Konto-ID

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GatewayManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:DeleteGateway",
        "bedrock-agentcore:ListGateways",
        "bedrock-agentcore:InvokeGateway",
        "bedrock-agentcore:CreateGatewayTarget",
        "bedrock-agentcore:UpdateGatewayTarget",
        "bedrock-agentcore:GetGatewayTarget",
        "bedrock-agentcore:DeleteGatewayTarget",
        "bedrock-agentcore:ListGatewayTargets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    },
    {
      "Sid": "PolicyEngineManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:UpdatePolicyEngine",
        "bedrock-agentcore:GetPolicyEngine",
        "bedrock-agentcore:DeletePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:DeletePolicy",
        "bedrock-agentcore:ListPolicies"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy/*"
      ]
    },
    {
      "Sid": "PolicyGeneration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartPolicyGeneration",
        "bedrock-agentcore:GetPolicyGeneration",
        "bedrock-agentcore:ListPolicyGenerations",
        "bedrock-agentcore:ListPolicyGenerationAssets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy-generation/*"
      ]
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*BedrockAgentCore*"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
        }
      }
    },
    {
      "Sid": "IAMReadAccess",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*"
      ]
    },
    {
      "Sid": "PolicyScopeManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:ManageResourceScopedPolicy",
        "bedrock-agentcore:ManageAdminPolicy"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
Wichtig

bedrock-agentcore:InvokeGatewayist erforderlich, um Cedar-Richtlinien zu erstellen oder zu aktualisieren, nicht nur, um das Gateway zur Laufzeit aufzurufen. CreatePolicyund UpdatePolicy validieren Sie die Aktionen in Ihrer Cedar-Erklärung anhand des Gateways, einer Operation, die wie InvokeGateway auf dem Gateway-ARN autorisiert ist. Ohne sie geht die Richtlinie zu CREATE_FAILED mit überInsufficient permissions to call gateway with ID <gateway-id>.

Wichtig

Bei den ManageAdminPolicy Aktionen ManageResourceScopedPolicy und handelt es sich ausschließlich um Zugangsberechtigungen, über die gesteuert wird, welche Arten von Cedar-Richtlinien Administratoren erstellen können: * ManageResourceScopedPolicy — Erteilt die Erlaubnis, Cedar-Richtlinien zu erstellen, die auf bestimmte Gateway-ARNs abzielen (z. B. Richtlinien, die für geltengateway/my-gateway-123) * ManageAdminPolicy — Erteilt die Erlaubnis, Cedar-Richtlinien mit Platzhaltern zu erstellen (z. B. Richtlinien, die sich auf Gateway/* beziehen). Beide Berechtigungen sind für die vollständige Richtlinienverwaltung erforderlich. Dabei handelt es sich nicht um API-Operationen, sondern um Autorisierungsprüfungen, die den Umfang der Cedar-Richtlinien bestimmen, die über die Policy Management APIs erstellt werden können.

Anmerkung

Das Feld Ressource ist zwar aus Konsistenzgründen enthalten, aber diese Aktionen, für die nur eine Genehmigung erforderlich ist, beschränken die Fähigkeiten primär auf Aktionsebene und nicht auf Ressourcenebene.

Wann sind Rollenaktualisierungen erforderlich?

Ermitteln Sie, ob AgentCore Policy-In-Berechtigungen zur Amazon Bedrock AgentCore Gateway-Ausführungsrolle hinzugefügt werden müssen, je nachdem, wie das Amazon Bedrock AgentCore Gateway erstellt wurde.

Szenario 1: Mit AgentCore CLI erstelltes Gateway

Status: Aktion erforderlich

Die AgentCore CLI erstellt eine Gateway-Ausführungsrolle mit bereichsspezifischen Berechtigungen für Zielaufruf und ausgehende Authentifizierung, schließt jedoch keine Richtlinie in den Berechtigungen ein. AgentCore Sie müssen die in diesem Handbuch dokumentierten GetPolicyEngine Berechtigungen AuthorizeActionPartiallyAuthorizeActions, und manuell zur Gateway-Ausführungsrolle hinzufügen.

Szenario 2: Benutzerdefinierte Ausführungsrolle

Status: Aktion erforderlich

Für benutzerdefinierte IAM-Rollen müssen die in diesem Handbuch dokumentierten AgentCore Policy-In-Berechtigungen manuell hinzugefügt werden. Folgen Sie den Berechtigungsrichtlinien in den obigen Abschnitten.

Szenario 3: Least-Privilege Produktionskonfiguration

Status: Maßnahme erforderlich

In Produktionsumgebungen sollten Sie die Richtlinie auf AgentCore Berechtigungen für bestimmte Ressourcen-ARNs beschränken, anstatt Platzhalter zu verwenden. Ersetzen Sie policy-engine/* und gateway/* durch die spezifischen Policy-Engine- und Gateway-IDs in Ihren Berechtigungsrichtlinien.

Fehlerbehebung

In diesem Abschnitt werden häufig auftretende Probleme bei der Konfiguration von IAM-Berechtigungen für Amazon Bedrock AgentCore Gateway mit Policy in behandelt. AgentCore

InternalServerException Während der Bewertung der Richtlinie

Symptom: Gateway kehrt zurückInternalServerException - Policy evaluation failed, wenn eine Policy Engine an ein vorhandenes Gateway angehängt wird, und alle Tool-Aufrufe werden standardmäßig verweigert, auch wenn Genehmigungsrichtlinien konfiguriert sind.

Hauptursache: In der Gateway-Ausführungsrolle fehlen die erforderlichen Policy-Berechtigungen. AgentCore Ohne diese Berechtigungen kann das Gateway keine Richtlinienautorisierung durchführen.

Lösung: Stellen Sie sicher, dass die Gateway-Ausführungsrolle die folgenden drei Berechtigungen umfasst:

{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:PartiallyAuthorizeActions",
    "bedrock-agentcore:AuthorizeAction",
    "bedrock-agentcore:GetPolicyEngine"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:policy-engine/*",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:gateway/*"
  ]
}
Anmerkung

Wenn Sie über die Policy Engine-Konsole eine Policy Engine an ein vorhandenes Gateway anhängen, werden die IAM-Berechtigungen möglicherweise nicht automatisch aktualisiert. Sie müssen diese Berechtigungen manuell zur Service-Linked Rolle des Gateways hinzufügen.

„Unzureichende Berechtigungen zum Aufrufen des Gateways“ aktiviert CreatePolicy

Symptom: CreatePolicy gibt a zurückpolicyId, aber die Richtlinie wechselt dann zu CREATE_FAILED mit Insufficient permissions to call gateway with ID <gateway-id> — auch wenn die Gateway-Ausführungsrolle über AuthorizeActionPartiallyAuthorizeActions, und verfügtGetPolicyEngine.

Hauptursache: Die Lücke besteht in der Rolle Resource Management, die aufruftCreatePolicy, und nicht in der Gateway-Ausführungsrolle. Bei der Richtlinienüberprüfung wird das Gateway aufgerufen (autorisiert alsbedrock-agentcore:InvokeGateway). Der Fehler benennt das Gateway, aber das Update bezieht sich auf die Rolle bei der Richtlinienerstellung.

Lösung: Fügen Sie der Ressourcenverwaltungsrolle Folgendes hinzu bedrock-agentcore:InvokeGateway (auf den Gateway-ARN beschränkt):

{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:InvokeGateway"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
  ]
}

Stille Ausfälle im LOG_ONLY-Modus

Symptom: Die Policy-Engine scheint im LOG_ONLY-Modus zu funktionieren, schlägt aber unbemerkt ohne korrekte Fehlermeldungen fehl.

Hauptursache: Fehlende bedrock-agentcore:GetPolicyEngine Berechtigungen führen zu unbemerkten Fehlern, die nur auftreten, wenn in den ENFORCED-Modus gewechselt wird.

Lösung: Immer bedrock-agentcore:GetPolicyEngine in die Gateway-Ausführungsrolle aufnehmen, auch wenn der LOG_ONLY-Modus zum Testen verwendet wird.

Fehler „Policy Engine nicht gefunden“

Symptom: Amazon Bedrock AgentCore Gateway gibt Fehler zurück, die darauf hinweisen, dass es die Policy-Engine nicht finden oder darauf zugreifen kann.

Hauptursache: Die Richtlinie der Gateway-Ausführungsrolle verwendet falsche ARN-Muster oder es fehlt die Policy-Engine-Ressource.

Lösung: Stellen Sie sicher, dass sowohl die Policy-Engine als auch die Gateway-ARNs im Resource-Array enthalten sind:

"Resource": [
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
]
Anmerkung

Beides PartiallyAuthorizeActions erfordert Zugriff AuthorizeAction sowohl auf die Policy-Engine- als auch auf die Gateway-Ressourcen.

Tipps zum Debuggen

  1. CloudWatch Protokolle aktivieren — Konfigurieren Sie die detaillierte Protokollierung für das Amazon Bedrock AgentCore Gateway, um Details zur Richtlinienbewertung zu erfassen

  2. X-Ray Ablaufverfolgungen überprüfen — Überprüfen Sie die AWS X-Ray Ablaufverfolgungen, um festzustellen, wo Autorisierungsprüfungen fehlschlagen

  3. Beginnen Sie mit dem LOG_ONLY-Modus — Verwenden Sie zunächst den LOG_ONLY-Modus, um die Richtlinien von Cedar zu testen, ohne Anfragen zu blockieren

  4. Überprüfen Sie alle vier Berechtigungen — stellen Sie sicherAuthorizeAction, dassPartiallyAuthorizeActions, UND alle vorhanden sind GetPolicyEngine

  5. In den ENFORCED-Modus wechseln — Wechseln Sie erst in den ENFORCED-Modus, nachdem Sie überprüft haben, ob alle Berechtigungen im LOG_ONLY-Modus funktionieren

Beispiel: Beide IAM-Rollen erstellen

Das folgende Beispiel zeigt, wie Sie beide erforderlichen IAM-Rollen mithilfe der AWS CLI erstellen.

Schritt 1: Gateway-Ausführungsrolle erstellen

# Create the trust policy file
cat > gateway-trust-policy.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}
EOF

# Create the IAM role
aws iam create-role \
  --role-name MyGatewayExecutionRole \
  --assume-role-policy-document file://gateway-trust-policy.json

Schritt 2: Weisen Sie der Gateway-Ausführungsrolle Berechtigungen zu

# Create the permission policy file
cat > gateway-permissions.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
EOF

# Attach the policy to the role
aws iam put-role-policy \
  --role-name MyGatewayExecutionRole \
  --policy-name GatewayPolicyEnginePermissions \
  --policy-document file://gateway-permissions.json
Anmerkung

In diesem Beispiel wird nur die Richtlinie in den AgentCore Berechtigungen angezeigt. Zusätzliche Berechtigungen für Amazon Bedrock AgentCore Gateway-Ziele (Lambda, API Gateway usw.) sollten auf der Grundlage Ihrer spezifischen Integrationsanforderungen hinzugefügt werden.

Schritt 3: Die nächsten Schritte

Nachdem Sie die Ausführungsrolle mit den erforderlichen AgentCore Policy-In-Berechtigungen konfiguriert haben, fahren Sie mit der Erstellung und Konfiguration der Richtlinienressourcen fort. Eine ausführliche Anleitung finden Sie unter:

Bewährte Methoden

  1. Separate Rollen verwenden — Behalten Sie unterschiedliche Rollen für die Ausführung und das Ressourcenmanagement von Amazon Bedrock AgentCore Gateway bei

  2. Least Privilege anwenden — Beginnen Sie in der Produktion mit spezifischen Ressourcen-ARNs und nicht mit Platzhaltern

  3. Testen Sie im LOG_ONLY-Modus — Testen Sie die Policy-Engine-Integration immer im LOG_ONLY-Modus, bevor Sie Richtlinien durchsetzen

  4. Überwachung aktivieren — Konfigurieren Sie CloudWatch Protokolle und Ablaufverfolgung für Problembehandlung und X-Ray Beobachtbarkeit

  5. Richtlinien zur Versionskontrolle — Speichern Sie die Cedar-Richtlinien zusammen mit dem Infrastrukturcode in der Versionskontrolle

  6. Verwenden Sie Resource Tags — Wenden Sie Tags an, um Amazon Bedrock AgentCore Gateway und Richtlinien in AgentCore Ressourcen zu organisieren und zu verwalten

  7. Regelmäßige Sicherheitsaudits — Überprüfen Sie regelmäßig die IAM-Richtlinien, um sicherzustellen, dass sie den Grundsätzen der geringsten Rechte entsprechen