개요 게이트웨이 실행 역할 리소스 관리 역할 역할 업데이트는 언제 필요합니까?문제 해결 예: 두 IAM 역할 모두 생성 모범 사례

AgentCore IAM 권한의 AgentCore 게이트웨이 및 정책

이 가이드에서는 Cedar 정책을 사용한 세분화된 권한 부여 제어를 위해 AgentCore에서 정책이 있는 Amazon Bedrock AgentCore Gateway를 사용하는 데 필요한 IAM 권한을 제공합니다.

개요

Amazon Bedrock AgentCore Gateway를 AgentCore의 정책과 통합할 때 두 가지 고유한 IAM 역할이 필요합니다.

게이트웨이 실행 역할 - Amazon Bedrock AgentCore Gateway가 런타임에 대상을 호출하고 Cedar 정책을 평가하기 위해 수임하는 IAM 역할입니다.
리소스 관리 역할 - 관리자가 AgentCore 리소스에서 Amazon Bedrock AgentCore 게이트웨이 및 정책을 생성하고 관리하는 데 사용하는 IAM 역할입니다.

두 역할 모두 용도가 다르며 특정 권한이 필요합니다. 게이트웨이 실행 역할에는 Amazon Bedrock AgentCore Gateway 작업을 실행할 수 있는 권한이 필요한 반면, 리소스 관리 역할에는 AgentCore 리소스에서 Amazon Bedrock AgentCore Gateway 및 정책을 구성하고 관리할 수 AgentCore 권한이 필요합니다.

게이트웨이 실행 역할

게이트웨이 실행 역할은 요청을 처리할 때 Amazon Bedrock AgentCore Gateway 서비스에서 수임합니다. 이 역할에는 다음에 대한 권한이 필요합니다.

AgentCore의 정책을 통해 Cedar 정책 평가
Lambda 함수 및 API Gateway 엔드포인트와 같은 대상 간접 호출
CloudWatch 및 X-Ray에 로그 및 추적 쓰기
인증 구성을 위한 액세스 보안 암호

중요

실행 역할에는 AgentCoreGateway를 사용하려면 다음 세 가지 권한이 포함되어야 합니다. bedrock-agentcore:AuthorizeAction - Cedar 정책에서 권한 부여 결정을 평가합니다. bedrock-agentcore:PartiallyAuthorizeActions - 호출자에게 호출 권한이 부여된 도구를 나열합니다. bedrock-agentcore:GetPolicyEngine - 정책 엔진 구성을 검색합니다. 이러한 권한이 없으면 게이트웨이가 정책 인증을 수행할 수 없습니다. 이 매니페스트는 두 가지 방식으로 표시됩니다. 즉, 정책 엔진을 기존 게이트웨이에 연결하면 InternalServerException이 생성되고, 모든 도구 호출은 권한 정책이 구성된 경우에도 기본적으로 거부됩니다.

신뢰 정책

게이트웨이 실행 역할은 bedrock-agentcore.amazonaws.com 서비스 보안 주체를 신뢰해야 합니다.

중요

다음 자리 표시자를 바꿉니다. * us-east-1을 AWS 리전으로 바꿉니다. * 123456789012을 AWS 계정 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:*"
        }
      }
    }
  ]
}

권한 정책

이 정책은 AgentCore의 정책을 통해 Cedar 정책을 평가하는 데 필요한 권한을 Amazon Bedrock AgentCore Gateway에 부여합니다. 권한은 최소 권한 원칙에 따라 두 개의 문으로 분할됩니다.

중요

다음 자리 표시자를 바꿉니다. * us-east-1을 AWS 리전으로 바꿉니다. * 123456789012을 AWS 계정 ID로 바꿉니다. * <gateway-id>를 게이트웨이 ID로 바꿉니다(또는 모든 게이트웨이에 * 사용). * <policy-engine-id>를 정책 엔진 ID로 바꿉니다(또는 모든 정책 엔진에 * 사용).


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

참고

* Amazon Bedrock AgentCore Gateway 통합 유형(예: Lambda 함수, API Gateway 엔드포인트)에 따라 추가 권한이 필요할 수 있습니다. 이러한 권한은 특정 통합에 따라 달라지므로 여기에 포함되지 않습니다. * 프로덕션의 경우: 최소 권한 원칙을 따르려면 자리 표시자를 특정 리소스 IDs(예: policy-engine/my-policy-engine-id 대신policy-engine/<policy-engine-id>)로 바꾸고, 해당 유형의 모든 리소스에 대한 액세스를 허용하려면 와일드카드( * )를 사용합니다.

리소스 관리 역할

리소스 관리 역할은 관리자가 AgentCore 리소스에서 Amazon Bedrock AgentCore 게이트웨이 및 정책을 생성하고 관리하는 데 사용됩니다. AgentCore 이 역할에는 다음에 대한 권한이 필요합니다.

게이트웨이 및 게이트웨이 대상 생성, 업데이트 및 삭제
정책 엔진 및 Cedar 정책 생성, 업데이트 및 삭제
정책 생성 중에 게이트웨이를 호출(InvokeGateway)하여 AgentCore의 정책이 대상 게이트웨이의 기능에 대해 Cedar 문에서 작업을 검증할 수 있도록 합니다.
생성 중에 게이트웨이 실행 역할을 Amazon Bedrock AgentCore Gateway 리소스에 전달
조직 및 관리를 위한 리소스 태그 지정
IAM 역할 정보를 읽고 실행 역할 구성 검증

이 역할은 게이트웨이 실행 역할과 별개이며 AgentCore 구성에서 Amazon Bedrock AgentCore 게이트웨이 및 정책을 설정하거나 수정할 때만 필요합니다.

권한 정책

중요

다음 자리 표시자를 바꿉니다. * us-east-1을 AWS 리전으로 바꿉니다. * 123456789012을 AWS 계정 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/*"
      ]
    }
  ]
}

중요

bedrock-agentcore:InvokeGateway는 런타임 시 게이트웨이를 호출하는 것뿐만 아니라 Cedar 정책을 생성하거나 업데이트하는 데 필요합니다. CreatePolicy는 게이트웨이 ARN에서 로 승인된 작업인 게이트웨이InvokeGateway에 대해 Cedar 문의 작업을 UpdatePolicy 검증합니다. 그렇지 않으면 정책이를 사용하여 CREATE_FAILED로 전환됩니다Insufficient permissions to call gateway with ID <gateway-id>.

중요

ManageResourceScopedPolicy 및 ManageAdminPolicy 작업은 관리자가 생성할 수 있는 Cedar 정책 유형을 제어하는 권한 전용 게이트입니다. * ManageResourceScopedPolicy - 특정 게이트웨이 ARNs을 대상으로 하는 Cedar 정책을 생성할 수 있는 권한을 부여합니다(예: gateway/my-gateway-123에 적용되는 정책). * ManageAdminPolicy - 와일드카드로 Cedar 정책을 생성할 수 있는 권한을 부여합니다(예: 게이트웨이에 적용되는 정책/* ). 두 권한 모두 전체 정책 관리 기능에 필요합니다. 이는 API 작업이 아니라 정책 관리 APIs.

참고

리소스 필드는 일관성을 위해 포함되지만 이러한 권한 전용 작업은 주로 리소스 수준이 아닌 작업 수준에서 기능을 게이트합니다.

역할 업데이트는 언제 필요합니까?

Amazon Bedrock AgentCore 게이트웨이가 생성된 방식에 따라 AgentCore 권한의 정책을 Amazon Bedrock AgentCore Gateway 실행 역할에 추가해야 하는지 여부를 결정합니다.

시나리오 1: AgentCore CLI를 사용하여 생성된 게이트웨이

상태: 필요한 작업

AgentCore CLI는 대상 호출 및 아웃바운드 인증에 대한 범위가 지정된 권한이 있는 게이트웨이 실행 역할을 생성하지만 AgentCore 권한에는 정책을 포함하지 않습니다. 이 가이드에 설명된 AuthorizeAction PartiallyAuthorizeActions, 및 GetPolicyEngine 권한을 게이트웨이 실행 역할에 수동으로 추가해야 합니다.

시나리오 2: 사용자 지정 실행 역할

상태: 필요한 작업

사용자 지정 IAM 역할을 사용하려면이 가이드에 설명된 AgentCore 권한의 정책을 수동으로 추가해야 합니다. 위 섹션의 권한 정책을 따릅니다.

시나리오 3: 프로덕션 최소 권한 구성

상태: 필요한 작업

프로덕션 환경의 경우 와일드카드를 사용하는 대신 AgentCore 권한의 정책 범위를 특정 리소스 ARNs으로 지정합니다. policy-engine/* 및 gateway/*를 권한 정책의 특정 정책 엔진 및 게이트웨이 IDs로 바꿉니다.

문제 해결

이 섹션에서는 AgentCoreGateway에 대한 IAM 권한을 구성할 때 발생하는 일반적인 문제를 다룹니다.

정책 평가 중 InternalServerException

증상: 정책 엔진을 기존 게이트웨이에 연결할 InternalServerException - Policy evaluation failed 때 게이트웨이가를 반환하며, 허용 정책이 구성된 경우에도 모든 도구 호출이 기본적으로 거부됩니다.

근본 원인: 게이트웨이 실행 역할에 AgentCore 권한에 필요한 정책이 없습니다. 이러한 권한이 없으면 게이트웨이는 정책 권한 부여를 수행할 수 없습니다.

해결 방법: 게이트웨이 실행 역할에 다음 세 가지 권한이 포함되어 있는지 확인합니다.


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

참고

정책 엔진 콘솔을 사용하여 기존 게이트웨이에 정책 엔진을 연결하면 IAM 권한이 자동으로 업데이트되지 않을 수 있습니다. 이러한 권한을 게이트웨이의 서비스 연결 역할에 수동으로 추가해야 합니다.

CreatePolicy의 "게이트웨이 호출 권한 부족"

증상:가를 CreatePolicy 반환하지만 게이트웨이 실행 역할에 policyId, AuthorizeAction PartiallyAuthorizeActions및가 Insufficient permissions to call gateway with ID <gateway-id> 있는 경우에도 정책은 CREATE_FAILED를 사용하여 로 전환됩니다GetPolicyEngine.

근본 원인: 게이트웨이 실행 역할이 CreatePolicy아닌를 호출하는 리소스 관리 역할에 격차가 있습니다. 정책 검증은 게이트웨이(로 권한 부여됨bedrock-agentcore:InvokeGateway)를 호출합니다. 오류는 게이트웨이의 이름을 지정하지만 수정은 정책 생성 역할에 있습니다.

해결 방법: 리소스 관리 역할에 bedrock-agentcore:InvokeGateway (게이트웨이 ARN 범위)를 추가합니다.


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

LOG_ONLY 모드의 자동 실패

증상: 정책 엔진이 LOG_ONLY 모드에서 작동하는 것처럼 보이지만 적절한 오류 메시지 없이 자동으로 실패합니다.

근본 원인: bedrock-agentcore:GetPolicyEngine 권한이 누락되면 ENFORCED 모드로 전환할 때만 표시되는 자동 실패가 발생합니다.

해결 방법: 테스트bedrock-agentcore:GetPolicyEngine에 LOG_ONLY 모드를 사용하는 경우에도 게이트웨이 실행 역할에를 항상 포함합니다.

정책 엔진을 찾을 수 없음 오류

증상: Amazon Bedrock AgentCore Gateway는 정책 엔진을 찾거나 액세스할 수 없음을 나타내는 오류를 반환합니다.

근본 원인: 게이트웨이 실행 역할의 정책이 잘못된 ARN 패턴을 사용하거나 정책 엔진 리소스가 누락되었습니다.

해결 방법: 정책 엔진 ARN과 게이트웨이 ARNs 모두 리소스 배열에 포함되어 있는지 확인합니다.


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

참고

AuthorizeAction 및 모두 정책 엔진 및 게이트웨이 리소스 모두에 액세스PartiallyAuthorizeActions해야 합니다.

디버깅 팁

CloudWatch Logs 활성화 - 정책 평가 세부 정보를 캡처하도록 Amazon Bedrock AgentCore Gateway에 대한 세부 로깅 구성
X-Ray 트레이스 검토 - AWS X-Ray 트레이스를 확인하여 권한 부여 검사에 실패한 위치를 식별합니다.
LOG_ONLY 모드로 시작 - 요청을 차단하지 않고 Cedar 정책을 테스트하려면 처음에 LOG_ONLY 모드를 사용합니다.
네 가지 권한 모두 확인 - AuthorizeAction , PartiallyAuthorizeActions , ANDGetPolicyEngine가 모두 존재하는지 확인
ENFORCED 모드로 전환 - 모든 권한이 LOG_ONLY 모드에서 작동하는지 확인한 후에만 ENFORCED 모드로 전환합니다.

예: 두 IAM 역할 모두 생성

다음 예제에서는 AWS CLI를 사용하여 필요한 두 IAM 역할을 모두 생성하는 방법을 보여줍니다.

1단계: 게이트웨이 실행 역할 생성


# 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

2단계: 게이트웨이 실행 역할에 권한 연결


# 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

참고

이 예제는 AgentCore 권한의 정책만 보여줍니다. 특정 통합 요구 사항에 따라 Amazon Bedrock AgentCore Gateway 대상(Lambda, API Gateway 등)에 대한 추가 권한을 추가해야 합니다.

3단계: 다음 단계

AgentCore 권한에서 필요한 정책으로 실행 역할을 구성한 후 정책 리소스를 생성하고 구성합니다. 자세한 지침은 다음을 참조하세요.

정책 엔진 생성 - 정책 엔진 생성 참조
Cedar 정책 작성 - Cedar 정책 언어 참조 참조

모범 사례

별도의 역할 사용 - Amazon Bedrock AgentCore Gateway 실행 및 리소스 관리를 위한 고유한 역할 유지
최소 권한 적용 - 프로덕션 환경에서 와일드카드가 아닌 특정 리소스 ARNs으로 시작
LOG_ONLY 모드로 테스트 - 정책을 적용하기 전에 항상 LOG_ONLY 모드에서 정책 엔진 통합 테스트
모니터링 활성화 - 문제 해결 및 관찰성을 위해 CloudWatch Logs 및 X-Ray 추적 구성
버전 제어 정책 - 인프라 코드와 함께 버전 제어에 Cedar 정책 저장
리소스 태그 사용 - 태그를 적용하여 AgentCore 리소스에서 Amazon Bedrock AgentCore 게이트웨이 및 정책 구성 및 관리
정기 보안 감사 - IAM 정책을 정기적으로 검토하여 최소 권한 원칙을 준수하는지 확인합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

핵심 개념

정책 엔진 생성