概觀閘道執行角色資源管理角色何時需要角色更新？疑難排解範例：建立兩個 IAM 角色最佳實務

AgentCore IAM 許可中的 AgentCore Gateway 和政策

本指南提供將 Amazon Bedrock AgentCore Gateway 與 AgentCore 中的政策搭配使用的必要 IAM 許可，以便使用 Cedar 政策進行精細的授權控制。

概觀

在 AgentCore 中整合 Amazon Bedrock AgentCore Gateway 與政策時，需要兩個不同的 IAM 角色：

閘道執行角色 - Amazon Bedrock AgentCore Gateway 在執行階段擔任的 IAM 角色，用於叫用目標並評估 Cedar 政策
資源管理角色 - 管理員用來在 AgentCore 資源中建立和管理 Amazon Bedrock AgentCore Gateway 和政策的 IAM 角色

這兩個角色都有不同的用途，需要特定的許可。閘道執行角色需要執行 Amazon Bedrock AgentCore Gateway 操作的許可，而資源管理角色則需要在 AgentCore 資源中設定和管理 Amazon Bedrock AgentCore Gateway 和政策的許可。

閘道執行角色

處理請求時，Amazon Bedrock AgentCore Gateway 服務會擔任閘道執行角色。此角色需要下列許可：

透過 AgentCore 中的政策評估 Cedar 政策
叫用 Lambda 函數和 API Gateway 端點等目標
將日誌和追蹤寫入 CloudWatch 和 X-Ray
身分驗證組態的存取秘密

重要

執行角色必須包含這三個許可，才能在 AgentCore 中使用 Amazon Bedrock AgentCore Gateway 搭配政策：。 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:*"
        }
      }
    }
  ]
}

許可政策

此政策授予 Amazon Bedrock AgentCore Gateway 透過 AgentCore 中的政策評估 Cedar 政策的必要許可。許可會依照最低權限原則分成兩個陳述式。

重要

將這些預留位置取代為：* 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 Gateway 和政策。此角色需要下列許可：

建立、更新和刪除閘道和閘道目標
建立、更新和刪除政策引擎和 Cedar 政策
在政策建立期間呼叫閘道 (InvokeGateway)，以便 AgentCore 中的政策可以根據目標閘道的功能驗證 Cedar 陳述式中的動作
在建立期間將閘道執行角色傳遞至 Amazon Bedrock AgentCore Gateway 資源
標記組織和管理的資源
讀取 IAM 角色資訊以驗證執行角色組態

此角色與閘道執行角色不同，只有在設定或修改 AgentCore 組態中的 Amazon Bedrock AgentCore Gateway 和政策時才需要。

許可政策

重要

以 AWS 帳戶 ID 取代這些預留位置：* us-east-1 為 AWS 區域 * 123456789012


{
"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 上授權為的操作 Gateway，驗證 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 建立之 Cedar 政策範圍的授權檢查。

注意

雖然包含資源欄位是為了一致性，但這些僅限許可的動作主要是在動作層級而非資源層級切換功能。

何時需要角色更新？

根據 Amazon Bedrock AgentCore Gateway 的建立方式，判斷是否需要將 AgentCore 許可中的政策新增至 Amazon Bedrock AgentCore Gateway 執行角色。

案例 1：使用 AgentCore CLI 建立的閘道

狀態：需要動作

AgentCore CLI 會建立閘道執行角色，其具有目標調用和傳出身分驗證的範圍許可，但不在 AgentCore 許可中包含政策。您必須手動將本指南中記錄的 AuthorizeAction 、 PartiallyAuthorizeActions 和 GetPolicyEngine許可新增至閘道執行角色。

案例 2：自訂執行角色

狀態：需要動作

自訂 IAM 角色需要手動新增本指南中記載的 AgentCore 許可中的政策。請遵循上述章節中的許可政策。

案例 3：生產最低權限組態

狀態：需要動作

對於生產環境，請將 AgentCore 許可中的政策範圍限定為特定資源 ARNs而不是使用萬用字元。將 policy-engine/* 和 gateway/* 取代為許可政策中的特定政策引擎和閘道 IDs。

疑難排解

本節涵蓋使用 AgentCore 中的政策設定 Amazon Bedrock AgentCore Gateway 的 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，但政策接著CREATE_FAILED會使用轉換為 Insufficient permissions to call gateway with ID <gateway-id>，即使閘道執行角色具有 AuthorizeAction、 PartiallyAuthorizeActions和 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 模式，或缺少政策引擎資源。

解決方案：確保政策引擎和閘道 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 模式開始 - 一開始使用 LOG_ONLY 模式來測試 Cedar 政策，而不會封鎖請求
驗證所有四個許可 - 確定 AuthorizeAction 、 PartiallyAuthorizeActions 和 GetPolicyEngine 都存在
切換到 ENFORCED 模式 - 只有在驗證所有許可在 LOG_ONLY 模式中運作之後，才能切換到 ENFORCED 模式

範例：建立兩個 IAM 角色

下列範例示範如何使用 CLI 建立兩個必要的 IAM AWS 角色。

步驟 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 Gateway 和政策
定期安全稽核 - 定期檢閱 IAM 政策，以確保其遵循最低權限原則

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

核心概念

建立政策引擎