Présentation de Rôle d'exécution de la passerelle Rôle de gestion des ressources Quand les mises à jour des rôles sont-elles requises ?Résolution des problèmes Exemple : création des deux rôles IAM Bonnes pratiques

AgentCore Passerelle et politique dans les AgentCore autorisations IAM

Ce guide fournit les autorisations IAM requises pour utiliser Amazon Bedrock AgentCore Gateway avec Policy in AgentCore pour un contrôle précis des autorisations à l'aide des politiques Cedar.

Présentation de

Lors de l'intégration d'Amazon Bedrock AgentCore Gateway à Policy in AgentCore, deux rôles IAM distincts sont requis :

Rôle d'exécution de passerelle : rôle IAM assumé par Amazon Bedrock AgentCore Gateway lors de l'exécution pour appeler des cibles et évaluer les politiques Cedar
Rôle de gestion des ressources : rôle IAM utilisé par les administrateurs pour créer et gérer Amazon Bedrock AgentCore Gateway et Policy dans les ressources AgentCore

Les deux rôles ont des objectifs différents et nécessitent des autorisations spécifiques. Le rôle d'exécution de passerelle a besoin d'autorisations pour exécuter les opérations d'Amazon Bedrock AgentCore Gateway, tandis que le rôle de gestion des ressources a besoin d'autorisations pour configurer et gérer Amazon Bedrock AgentCore Gateway et la politique relatives aux AgentCore ressources.

Rôle d'exécution de la passerelle

Le rôle d'exécution de la passerelle est assumé par le service Amazon Bedrock AgentCore Gateway lors du traitement des demandes. Ce rôle nécessite des autorisations pour :

Évaluez les politiques de Cedar via Policy in AgentCore
Appelez des cibles telles que les fonctions Lambda et les points de terminaison API Gateway
Rédiger des journaux et des traces dans CloudWatch et X-Ray
Secrets d'accès pour les configurations d'authentification

Important

Le rôle d'exécution doit inclure ces trois autorisations pour utiliser Amazon Bedrock AgentCore Gateway with Policy dans AgentCore :. bedrock-agentcore:AuthorizeAction - Évalue les politiques de Cedar pour les décisions d'autorisation. bedrock-agentcore:PartiallyAuthorizeActions - Répertorie les outils que l'appelant est autorisé à invoquer. bedrock-agentcore:GetPolicyEngine - Récupère la configuration du moteur de politiques Sans ces autorisations, la passerelle ne peut pas effectuer d'autorisation de politique. Cela se manifeste de deux manières : associer un moteur de politiques à une passerelle existante entraînera un InternalServerException, et tous les appels d'outils seront refusés par défaut, même si vous avez configuré des politiques d'autorisation.

Stratégie d’approbation

Le rôle d'exécution de la passerelle doit faire confiance au principal du bedrock-agentcore.amazonaws.com service.

Important

Remplacez les espaces réservés suivants :* us-east-1 par la AWS région * 123456789012 par l'identifiant du AWS compte


{
"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:*"
        }
      }
    }
  ]
}

Stratégie d'autorisation

Cette politique accorde à Amazon Bedrock AgentCore Gateway les autorisations nécessaires pour évaluer les politiques de Cedar via Policy in AgentCore. Les autorisations sont divisées en deux déclarations suivant le principe du moindre privilège.

Important

Remplacez ces espaces réservés :* us-east-1 par la AWS région * 123456789012 par l'ID du AWS compte * <gateway-id> par l'ID de passerelle (ou utilisez* pour toutes les passerelles) * <policy-engine-id> par l'ID du moteur de politiques (ou utilisez* pour tous les moteurs de politiques)


{
"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>"
      ]
    }
  ]
}

Note

* Des autorisations supplémentaires peuvent être requises en fonction du type d'intégration Amazon Bedrock AgentCore Gateway (par exemple, fonctions Lambda, points de terminaison API Gateway). Ces autorisations ne sont pas incluses ici car elles varient en fonction de l'intégration spécifique. * Pour la production : remplacez les espaces réservés par des identifiants de ressource spécifiques (par exemple, policy-engine/my-policy-engine-id au lieu depolicy-engine/<policy-engine-id>) afin de respecter le principe du moindre privilège, ou utilisez des caractères génériques (*) pour autoriser l'accès à toutes les ressources de ce type.

Rôle de gestion des ressources

Le rôle de gestion des ressources est utilisé par les administrateurs pour créer et gérer Amazon Bedrock AgentCore Gateway et Policy dans les AgentCore ressources. Ce rôle nécessite des autorisations pour :

Création, mise à jour et suppression de passerelles et de cibles de passerelle
Création, mise à jour et suppression de Policy Engines et de politiques Cedar
Appelez la passerelle lors de la création de la politique (InvokeGateway) afin que Policy in AgentCore puisse valider les actions d'une déclaration Cedar par rapport aux capacités de la passerelle cible
Transmettez le rôle d'exécution de la passerelle aux ressources Amazon Bedrock AgentCore Gateway lors de la création
Étiquetez les ressources pour l'organisation et la gestion
Lisez les informations sur les rôles IAM pour valider les configurations des rôles d'exécution

Ce rôle est distinct du rôle d'exécution de passerelle et n'est nécessaire que pour configurer ou modifier Amazon Bedrock AgentCore Gateway et Policy dans les AgentCore configurations.

Stratégie d'autorisation

Important

Remplacez ces espaces réservés :* us-east-1 par la AWS région * 123456789012 par l'identifiant du AWS compte


{
"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/*"
      ]
    }
  ]
}

Important

bedrock-agentcore:InvokeGatewayest nécessaire pour créer ou mettre à jour les politiques de Cedar, et pas seulement pour invoquer la passerelle lors de l'exécution. CreatePolicyet UpdatePolicy validez les actions de votre relevé Cedar par rapport à la passerelle, opération autorisée comme InvokeGateway sur l'ARN de la passerelle. Sans cela, la politique passe à CREATE_FAILED withInsufficient permissions to call gateway with ID <gateway-id>.

Important

Les ManageAdminPolicy actions ManageResourceScopedPolicy et sont des portes d'autorisation uniquement qui contrôlent les types de politiques Cedar que les administrateurs peuvent créer :* ManageResourceScopedPolicy - Accorde l'autorisation de créer des politiques Cedar ciblant des ARN de passerelle spécifiques (par exemple, les politiques s'appliquant àgateway/my-gateway-123) * ManageAdminPolicy - Accorde l'autorisation de créer des politiques Cedar avec des caractères génériques (par exemple, des politiques s'appliquant à la passerelle/*) Les deux autorisations sont requises pour une capacité complète de gestion des politiques. Il ne s'agit pas d'opérations d'API, mais de contrôles d'autorisation qui déterminent la portée des politiques Cedar qui peuvent être créées via les API de gestion des politiques.

Note

Bien que le champ Ressource soit inclus pour des raisons de cohérence, ces actions basées uniquement sur des autorisations limitent principalement les capacités au niveau de l'action plutôt qu'au niveau des ressources.

Quand les mises à jour des rôles sont-elles requises ?

Déterminez si une politique d' AgentCore autorisations doit être ajoutée au rôle d'exécution d'Amazon Bedrock AgentCore Gateway en fonction de la façon dont Amazon Bedrock AgentCore Gateway a été créée.

Scénario 1 : passerelle créée avec la AgentCore CLI

État : Action requise

La AgentCore CLI crée un rôle d'exécution de passerelle avec des autorisations limitées pour l'appel cible et l'authentification sortante, mais n'inclut pas de politique dans les autorisations. AgentCore Vous devez ajouter manuellement les GetPolicyEngine autorisations AuthorizeActionPartiallyAuthorizeActions, et documentées dans ce guide au rôle d'exécution de la passerelle.

Scénario 2 : rôle d'exécution personnalisé

État : Action requise

Les rôles IAM personnalisés nécessitent que la politique en matière AgentCore d'autorisations décrite dans ce guide soit ajoutée manuellement. Suivez les politiques d'autorisation décrites dans les sections ci-dessus.

Scénario 3 : Least-Privilege Configuration de production

État : Action requise

Pour les environnements de production, définissez la politique en termes d' AgentCore autorisations pour des ARN de ressources spécifiques plutôt que d'utiliser des caractères génériques. Remplacez policy-engine/* et gateway/* par le moteur de politique et les identifiants de passerelle spécifiques dans vos politiques d'autorisation.

Résolution des problèmes

Cette section traite des problèmes courants liés à la configuration des autorisations IAM pour Amazon Bedrock AgentCore Gateway avec Policy in. AgentCore

InternalServerException Au cours de l'évaluation des politiques

Symptôme : Gateway revient InternalServerException - Policy evaluation failed lorsque vous attachez un moteur de politiques à une passerelle existante, et tous les appels d'outils sont refusés par défaut, même lorsque les politiques d'autorisation sont configurées.

Cause première : le rôle d'exécution de la passerelle ne contient pas la politique requise dans AgentCore les autorisations. Sans ces autorisations, la passerelle ne peut pas effectuer d'autorisation politique.

Solution : assurez-vous que le rôle d'exécution de la passerelle inclut les trois autorisations suivantes :


{
  "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/*"
  ]
}

Note

Si vous attachez un moteur de politique à une passerelle existante à l'aide de la console Policy Engine, les autorisations IAM risquent de ne pas être automatiquement mises à jour. Vous devez ajouter manuellement ces autorisations au Service-Linked rôle de la passerelle.

« Autorisations insuffisantes pour appeler la passerelle » sur CreatePolicy

Symptôme : CreatePolicy renvoie unpolicyId, mais la politique passe ensuite à CREATE_FAILED withInsufficient permissions to call gateway with ID <gateway-id>, même si le rôle d'exécution de la passerelle possède AuthorizeActionPartiallyAuthorizeActions, etGetPolicyEngine.

Cause première : L'écart réside dans le rôle de gestion des ressources qui appelleCreatePolicy, et non dans le rôle d'exécution de la passerelle. La validation des politiques appelle la passerelle (autorisée en tant quebedrock-agentcore:InvokeGateway) ; l'erreur nomme la passerelle mais le correctif concerne le rôle de création des politiques.

Solution : ajoutez bedrock-agentcore:InvokeGateway (limité à l'ARN de la passerelle) au rôle de gestion des ressources :


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

Défaillances silencieuses en mode LOG_ONLY

Symptôme : le moteur de politiques semble fonctionner en mode LOG_ONLY mais échoue silencieusement sans messages d'erreur appropriés.

Cause première : bedrock-agentcore:GetPolicyEngine L'absence d'autorisation entraîne des défaillances silencieuses qui n'apparaissent que lors du passage en mode ENFORCED.

Solution : incluez-le toujours bedrock-agentcore:GetPolicyEngine dans le rôle d'exécution de la passerelle, même lorsque vous utilisez le mode LOG_ONLY pour les tests.

Erreur introuvable dans le moteur de politique

Symptôme : Amazon Bedrock AgentCore Gateway renvoie des erreurs indiquant qu'il ne peut pas trouver le moteur de politiques ou y accéder.

Cause première : La politique du rôle d'exécution de la passerelle utilise des modèles d'ARN incorrects ou ne contient pas la ressource du moteur de politiques.

Solution : assurez-vous que les ARN du moteur de politiques ET de la passerelle sont inclus dans le tableau de ressources :


"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>"
]

Note

Les deux AuthorizeAction PartiallyAuthorizeActions nécessitent un accès à la fois au moteur de politiques et aux ressources de passerelle.

Conseils de débogage

Activer CloudWatch les journaux : configurez la journalisation détaillée pour Amazon Bedrock AgentCore Gateway afin de recueillir les détails de l'évaluation des politiques
Consulter X-Ray les traces - Vérifiez les AWS X-Ray traces pour identifier les endroits où les contrôles d'autorisation échouent
Commencez par le mode LOG_ONLY : utilisez d'abord le mode LOG_ONLY pour tester les politiques de Cedar sans bloquer les requêtes
Vérifiez les quatre autorisations : assurez-vous que AuthorizeAction « ET » GetPolicyEngine sont toutes présentes PartiallyAuthorizeActions
Passez en mode ENFORCED : après avoir vérifié que toutes les autorisations fonctionnent en mode LOG_ONLY, passez en mode ENFORCED

Exemple : création des deux rôles IAM

L'exemple suivant montre comment créer les deux rôles IAM requis à l'aide de la AWS CLI.

Étape 1 : créer un rôle d'exécution de passerelle


# 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

Étape 2 : associer des autorisations au rôle d'exécution de la passerelle


# 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

Note

Cet exemple montre uniquement la politique dans AgentCore les autorisations. Des autorisations supplémentaires pour les cibles Amazon Bedrock AgentCore Gateway (Lambda, API Gateway, etc.) doivent être ajoutées en fonction de vos exigences d'intégration spécifiques.

Étape 3 : Prochaines étapes

Après avoir configuré le rôle d'exécution avec la politique requise dans AgentCore les autorisations, passez à la création et à la configuration des ressources de stratégie. Pour obtenir des conseils détaillés, reportez-vous à :

Création d'un moteur de politiques - Voir la section Création d'un moteur de politiques
Rédaction des politiques de Cedar - Voir la référence linguistique des politiques de Cedar

Bonnes pratiques

Utiliser des rôles distincts - Conservez des rôles distincts pour l'exécution d'Amazon Bedrock AgentCore Gateway et la gestion des ressources
Appliquer le moindre privilège : commencez avec des ARN de ressources spécifiques plutôt que des caractères génériques en production
Test avec le mode LOG_ONLY : testez toujours l'intégration du moteur de politiques en mode LOG_ONLY avant d'appliquer les politiques
Activer la surveillance : configurez CloudWatch les journaux et le X-Ray suivi pour le dépannage et l'observabilité
Politiques de contrôle de version - Stockez les politiques Cedar dans le contrôle de version en même temps que le code d'infrastructure
Utiliser des balises de ressources : appliquez des balises pour organiser et gérer Amazon Bedrock AgentCore Gateway et Policy dans les AgentCore ressources
Audits de sécurité réguliers : passez régulièrement en revue les politiques IAM pour vous assurer qu'elles respectent les principes du moindre privilège

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Concepts de base

Création d'un moteur de politiques