View a markdown version of this page

AgentCore Gateway e política nas permissões AgentCore do IAM - Amazon Bedrock AgentCore
Visão geral doFunção de execução do gatewayFunção de gerenciamento de recursosQuando as atualizações de funções são necessárias?Solução de problemasExemplo: criação de ambas as funções do IAMPráticas recomendadas

AgentCore Gateway e política nas permissões AgentCore do IAM

Este guia fornece as permissões necessárias do IAM para usar o Amazon Bedrock AgentCore Gateway com o Policy in AgentCore para um controle de autorização refinado usando as políticas do Cedar.

Visão geral do

Ao integrar o Amazon Bedrock AgentCore Gateway com o Policy in AgentCore, duas funções distintas do IAM são necessárias:

  1. Função de execução do gateway - A função do IAM que o Amazon Bedrock AgentCore Gateway assume em tempo de execução para invocar alvos e avaliar as políticas do Cedar

  2. Função de gerenciamento de recursos - A função do IAM que os administradores usam para criar e gerenciar o Amazon Bedrock AgentCore Gateway e a política em recursos AgentCore

Ambas as funções têm propósitos diferentes e exigem permissões específicas. A função de execução do gateway precisa de permissões para executar as operações do Amazon Bedrock AgentCore Gateway, enquanto a função de gerenciamento de recursos precisa de permissões para configurar e gerenciar o Amazon Bedrock AgentCore Gateway e a política em AgentCore recursos.

Função de execução do gateway

A função de execução do gateway é assumida pelo serviço Amazon Bedrock AgentCore Gateway ao processar solicitações. Essa função requer permissões para:

  • Avalie as políticas da Cedar por meio da Política em AgentCore

  • Invoque destinos como funções Lambda e endpoints do API Gateway

  • Grave registros e rastreamentos em CloudWatch e X-Ray

  • Segredos de acesso para configurações de autenticação

Importante

A função de execução deve incluir essas três permissões para usar o Amazon Bedrock AgentCore Gateway com a política em AgentCore:. bedrock-agentcore:AuthorizeAction - Avalia as políticas da Cedar para decisões de autorização. bedrock-agentcore:PartiallyAuthorizeActions - Lista as ferramentas que o chamador está autorizado a invocar. bedrock-agentcore:GetPolicyEngine - Recupera a configuração do mecanismo de políticas Sem essas permissões, o Gateway não pode realizar a autorização da política. Isso se manifesta de duas maneiras: anexar um mecanismo de política a um gateway existente resultará em um InternalServerException, e todas as invocações de ferramentas serão negadas por padrão, mesmo se você tiver políticas de permissão configuradas.

Política de confiança

A função de execução do gateway deve confiar no responsável pelo bedrock-agentcore.amazonaws.com serviço.

Importante

Substitua os seguintes espaços reservados: * us-east-1 pela AWS região * pelo 123456789012 ID da AWS conta

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

Política de permissão

Essa política concede ao Amazon Bedrock AgentCore Gateway as permissões necessárias para avaliar as políticas da Cedar por meio do Policy in. AgentCore As permissões são divididas em duas declarações seguindo os princípios de privilégios mínimos.

Importante

Substitua esses espaços reservados: * us-east-1 pela AWS região * 123456789012 pelo ID da AWS conta * <gateway-id> pelo ID do gateway (ou use* para todos os gateways) * <policy-engine-id> pelo ID do mecanismo de políticas (ou use* para todos os mecanismos de política)

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

* Permissões adicionais podem ser necessárias dependendo do tipo de integração do Amazon Bedrock AgentCore Gateway (por exemplo, funções Lambda, endpoints do API Gateway). Essas permissões não estão incluídas aqui, pois variam de acordo com a integração específica. * Para produção: substitua os espaços reservados por IDs de recursos específicos (por exemplo, policy-engine/my-policy-engine-id em vez depolicy-engine/<policy-engine-id>) para seguir os princípios de privilégios mínimos ou use curingas (*) para permitir o acesso a todos os recursos desse tipo.

Função de gerenciamento de recursos

A função de gerenciamento de recursos é usada pelos administradores para criar e gerenciar o Amazon Bedrock AgentCore Gateway e a política em AgentCore recursos. Essa função requer permissões para:

  • Crie, atualize e exclua gateways e destinos de gateway

  • Crie, atualize e exclua políticas de Policy Engines e Cedar

  • Chame o Gateway durante a criação da política (InvokeGateway) para que o Policy in AgentCore possa validar as ações em uma declaração do Cedar em relação aos recursos do Gateway de destino

  • Passe a função de execução do gateway para os recursos do Amazon Bedrock AgentCore Gateway durante a criação

  • Marque recursos para organização e gerenciamento

  • Leia as informações da função do IAM para validar as configurações da função de execução

Essa função é separada da função de execução do gateway e só é necessária ao configurar ou modificar o Amazon Bedrock AgentCore Gateway e a política nas AgentCore configurações.

Política de permissão

Importante

Substitua esses espaços reservados: * us-east-1 pela AWS região * pelo 123456789012 ID da AWS conta

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

bedrock-agentcore:InvokeGatewayé necessário para criar ou atualizar as políticas do Cedar, não apenas para invocar o Gateway em tempo de execução. CreatePolicye UpdatePolicy valide as ações em sua declaração do Cedar em relação ao Gateway, uma operação autorizada como InvokeGateway no ARN do Gateway. Sem isso, a política passa para CREATE_FAILED comInsufficient permissions to call gateway with ID <gateway-id>.

Importante

As ManageAdminPolicy ações ManageResourceScopedPolicy e são portas somente de permissão que controlam quais tipos de políticas do Cedar os administradores podem criar: * ManageResourceScopedPolicy - Concede permissão para criar políticas do Cedar que tenham como alvo ARNs de gateway específicos (por exemplo, políticas que se aplicam agateway/my-gateway-123) * ManageAdminPolicy - Concede permissão para criar políticas do Cedar com curingas (por exemplo, políticas que se aplicam ao gateway/*) Ambas as permissões são necessárias para a capacidade total de gerenciamento de políticas. Essas não são operações de API, mas sim verificações de autorização que determinam o escopo das políticas do Cedar que podem ser criadas por meio das APIs de gerenciamento de políticas.

nota

Embora o campo Recurso seja incluído para fins de consistência, essas ações somente de permissão limitam principalmente a capacidade no nível da ação e não no nível do recurso.

Quando as atualizações de funções são necessárias?

Determine se a política de AgentCore permissões precisa ser adicionada à função de execução do Amazon Bedrock AgentCore Gateway com base em como o Amazon Bedrock AgentCore Gateway foi criado.

Cenário 1: Gateway criado com AgentCore CLI

Status: Ação necessária

A AgentCore CLI cria uma função de execução de gateway com permissões definidas para invocação de destino e autenticação de saída, mas não inclui a Política nas permissões. AgentCore Você deve adicionar manualmente as GetPolicyEngine permissões AuthorizeActionPartiallyAuthorizeActions,, e documentadas neste guia à função de execução do gateway.

Cenário 2: Função de execução personalizada

Status: Ação necessária

As funções personalizadas do IAM exigem que a Política nas AgentCore permissões documentadas neste guia seja adicionada manualmente. Siga as políticas de permissão nas seções acima.

Cenário 3: Least-Privilege Configuração de produção

Status: Ação necessária

Para ambientes de produção, defina o escopo da Política em AgentCore permissões para ARNs de recursos específicos, em vez de usar curingas. Substitua policy-engine/* e gateway/* pelo mecanismo de política específico e pelos IDs de gateway em suas políticas de permissão.

Solução de problemas

Esta seção aborda problemas comuns ao configurar permissões do IAM para o Amazon Bedrock AgentCore Gateway com o Policy in. AgentCore

InternalServerException Durante a avaliação da política

Sintoma: o Gateway retorna InternalServerException - Policy evaluation failed ao conectar um Policy Engine a um Gateway existente, e todas as invocações de ferramentas são negadas por padrão, mesmo com políticas de permissão configuradas.

Causa raiz: a função de execução do Gateway não tem a política necessária nas AgentCore permissões. Sem essas permissões, o Gateway não pode realizar a autorização da política.

Solução: Certifique-se de que a função de execução do gateway inclua essas três permissões:

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

Se você anexar um Policy Engine a um gateway existente usando o console do Policy Engine, as permissões do IAM podem não ser atualizadas automaticamente. Você deve adicionar manualmente essas permissões à Service-Linked função do Gateway.

“Permissões insuficientes para chamar o gateway” em CreatePolicy

Sintoma: CreatePolicy retorna umpolicyId, mas a política então passa para CREATE_FAILED com Insufficient permissions to call gateway with ID <gateway-id> — mesmo quando a função de execução do gateway tem AuthorizeActionPartiallyAuthorizeActions, e. GetPolicyEngine

Causa raiz: a lacuna está na função de gerenciamento de recursos que chamaCreatePolicy, não na função de execução do gateway. A validação da política chama o Gateway (autorizado comobedrock-agentcore:InvokeGateway); o erro nomeia o Gateway, mas a correção está na função de criação da política.

Solução: adicione bedrock-agentcore:InvokeGateway (com escopo ao ARN do gateway) à função de gerenciamento de recursos:

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

Falhas silenciosas no modo LOG_ONLY

Sintoma: o mecanismo de políticas parece funcionar no modo LOG_ONLY, mas falha silenciosamente sem as mensagens de erro adequadas.

Causa raiz: a falta de bedrock-agentcore:GetPolicyEngine permissão causa falhas silenciosas que só aparecem ao alternar para o modo ENFORCED.

Solução: sempre inclua bedrock-agentcore:GetPolicyEngine na função de execução do gateway, mesmo ao usar o modo LOG_ONLY para testes.

Erro do mecanismo de política não encontrado

Sintoma: O Amazon Bedrock AgentCore Gateway retorna erros indicando que não consegue encontrar ou acessar o mecanismo de políticas.

Causa raiz: a política da função de execução do gateway usa padrões de ARN incorretos ou não tem o recurso do mecanismo de políticas.

Solução: Certifique-se de que os ARNs do mecanismo de políticas e do gateway estejam incluídos na matriz de recursos:

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

Ambos AuthorizeAction PartiallyAuthorizeActions exigem acesso aos recursos do mecanismo de políticas e do gateway.

Dicas de depuração

  1. Habilitar CloudWatch registros - Configure registros detalhados para o Amazon Bedrock AgentCore Gateway para capturar detalhes da avaliação de políticas

  2. Revise X-Ray os rastreamentos - verifique AWS X-Ray os rastreamentos para identificar onde as verificações de autorização estão falhando

  3. Comece com o modo LOG_ONLY - Use o modo LOG_ONLY inicialmente para testar as políticas do Cedar sem bloquear solicitações

  4. Verifique todas as quatro permissões - Certifique-se de que AuthorizeActionPartiallyAuthorizeActions, E e GetPolicyEngine estejam todas presentes

  5. Alterne para o modo ENFORCED - Somente depois de verificar se todas as permissões funcionam no modo LOG_ONLY, mude para o modo ENFORCED

Exemplo: criação de ambas as funções do IAM

O exemplo a seguir demonstra como criar as duas funções necessárias do IAM usando a AWS CLI.

Etapa 1: Criar função de execução do gateway

# 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

Etapa 2: Anexar permissões à função de execução do gateway

# 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
nota

Este exemplo mostra somente a Política em AgentCore permissões. Permissões adicionais para destinos do Amazon Bedrock AgentCore Gateway (Lambda, API Gateway etc.) devem ser adicionadas com base em seus requisitos específicos de integração.

Etapa 3: próximas etapas

Depois de configurar a função de execução com a Política necessária nas AgentCore permissões, continue criando e configurando os recursos da Política. Para obter orientação detalhada, consulte:

Práticas recomendadas

  1. Use funções separadas - Mantenha funções distintas para execução e gerenciamento de recursos do Amazon Bedrock AgentCore Gateway

  2. Aplique o mínimo de privilégios - comece com ARNs de recursos específicos em vez de curingas na produção

  3. Teste com o modo LOG_ONLY - Sempre teste a integração do mecanismo de políticas no modo LOG_ONLY antes de aplicar as políticas

  4. Ativar monitoramento - configure CloudWatch registros e X-Ray rastreamento para solução de problemas e observabilidade

  5. Políticas de controle de versão - Armazene as políticas do Cedar no controle de versão junto com o código de infraestrutura

  6. Use tags de recursos - aplique tags para organizar e gerenciar o Amazon Bedrock AgentCore Gateway e a política em AgentCore recursos

  7. Auditorias de segurança regulares - revise periodicamente as políticas do IAM para garantir que elas sigam os princípios de menor privilégio