As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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

Este guia fornece as permissões de IAM necessárias para usar o Amazon Bedrock AgentCore Gateway with Policy in AgentCore para um controle de autorização detalhado usando 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:

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 exige permissões para:

Política de confiança

A função de execução do gateway deve confiar no principal do bedrock-agentcore.amazonaws.com serviço.

{
"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 do Cedar por meio da Política em. AgentCore As permissões são divididas em duas declarações seguindo os princípios de menor privilégio.

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

Permissões do IAM para políticas temporais

As políticas temporais exigem que o Gateway propague a identidade da sessão do chamador em toda a solicitação, criando um Token de Acesso à Carga de Trabalho (WAT). No fluxo de entrada AWS do IAM, esse mint chamaGetWorkloadAccessToken. Conceda a Função de Execução do Gatewaybedrock-agentcore:GetWorkloadAccessToken, com escopo no diretório de identidade da carga de trabalho do Gateway. Adicione essa permissão além das três permissões de política (AuthorizeAction,PartiallyAuthorizeActions,GetPolicyEngine) já documentadas nesta página. Essa permissão só é necessária quando a política temporal está ativa (um ID de sessão de política é fornecido e um mecanismo de política é anexado); não é necessária quando a política temporal está desativada.

Adicione a seguinte declaração à política de permissão do Gateway Execution Role:

{
  "Sid": "PolicySessionWorkloadIdentity",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetWorkloadAccessToken"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/<gatewayId>*"
  ]
}

Sem essa permissão, as invocações de ferramentas falham na etapa token-mint (ativadaGetWorkloadAccessToken) quando a política temporal é AccessDenied ativada. Para produção, <gatewayId> substitua pelo ID de gateway específico para seguir os princípios de menor privilégio.

Para obter uma visão geral desse requisito no contexto das considerações de política temporal, consulte Permissões de IAM necessárias.

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 exige permissões para:

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

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

Quando as atualizações de função 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.

Solução de problemas

Esta seção aborda problemas comuns ao configurar as permissões do IAM para o Amazon Bedrock AgentCore Gateway com a política em. AgentCore

InternalServerException Durante a avaliação da política

Sintoma: o gateway retorna InternalServerException - Policy evaluation failed ao conectar um mecanismo de políticas a um gateway existente, e todas as invocações de ferramentas são negadas por padrão, mesmo com as 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 estas 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/*"
  ]
}

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

Sintoma: CreatePolicy retorna umpolicyId, mas a política então faz a transição 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 definido no 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 Policy Engine 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 do Gateway Execution Role usa padrões de ARN incorretos ou não tem o recurso do mecanismo de política.

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

Dicas de depuração

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

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

Etapa 1: Criar a 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

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