# AgentCore IAM 許可中的 AgentCore Gateway 和政策
<a name="policy-permissions"></a>

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

## 概觀
<a name="policy-permissions-overview"></a>

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

1.  **閘道執行角色** - Amazon Bedrock AgentCore Gateway 在執行階段擔任的 IAM 角色，用於叫用目標並評估 Cedar 政策

1.  **資源管理角色** - 管理員用來在 AgentCore 資源中建立和管理 Amazon Bedrock AgentCore Gateway 和政策的 IAM 角色

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

## 閘道執行角色
<a name="policy-permissions-execution-role"></a>

處理請求時，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，而且即使您已設定允許政策，所有工具叫用都將預設為拒絕。

### 信任政策
<a name="policy-permissions-execution-trust"></a>

閘道執行角色必須信任`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:*"
        }
      }
    }
  ]
}
```

### 許可政策
<a name="policy-permissions-execution-permissions"></a>

此政策授予 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>` )，以遵循最低權限原則，或使用萬用字元 ( \* ) 來允許存取該類型的所有資源。

## 資源管理角色
<a name="policy-permissions-management-role"></a>

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

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

### 許可政策
<a name="policy-permissions-management-permissions"></a>

**重要**  
以 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 政策範圍的授權檢查。

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

## 何時需要角色更新？
<a name="policy-permissions-when-required"></a>

根據 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。

## 疑難排解
<a name="policy-permissions-troubleshooting"></a>

本節涵蓋使用 AgentCore 中的政策設定 Amazon Bedrock AgentCore Gateway 的 IAM 許可時的常見問題。

### 政策評估期間的 InternalServerException
<a name="policy-permissions-error-403"></a>

 **徵狀：**閘道在將政策引擎連接至現有閘道`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 上的「呼叫閘道的許可不足」
<a name="policy-permissions-error-create-policy-invoke"></a>

 **徵狀：** `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 模式下的靜音失敗
<a name="policy-permissions-error-silent"></a>

 **徵狀：**政策引擎似乎在 LOG\_ONLY 模式下運作，但在無適當錯誤訊息的情況下無提示地失敗。

 **根本原因：**缺少`bedrock-agentcore:GetPolicyEngine`許可會導致靜音失敗，只有在切換到 ENFORCED 模式時才會顯示。

 **解決方案：**一律在閘道執行角色`bedrock-agentcore:GetPolicyEngine`中包含 ，即使使用 LOG\_ONLY 模式進行測試也一樣。

### 找不到政策引擎錯誤
<a name="policy-permissions-error-not-found"></a>

 **徵狀：**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`存取政策引擎和閘道資源。

### 偵錯秘訣
<a name="policy-permissions-debugging-tips"></a>

1.  **啟用 CloudWatch Logs** - 設定 Amazon Bedrock AgentCore Gateway 的詳細記錄，以擷取政策評估詳細資訊

1.  **檢閱 X-Ray 追蹤** - 檢查 AWS X-Ray 追蹤以識別授權檢查失敗的位置

1.  從 **LOG\_ONLY 模式開始** - 一開始使用 LOG\_ONLY 模式來測試 Cedar 政策，而不會封鎖請求

1.  **驗證所有四個許可** - 確定 `AuthorizeAction` 、 `PartiallyAuthorizeActions` 和 `GetPolicyEngine` 都存在

1.  **切換到 ENFORCED 模式** - 只有在驗證所有許可在 LOG\_ONLY 模式中運作之後，才能切換到 ENFORCED 模式

## 範例：建立兩個 IAM 角色
<a name="policy-permissions-example"></a>

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

### 步驟 1：建立閘道執行角色
<a name="policy-permissions-example-execution"></a>

```
# 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：將許可連接至閘道執行角色
<a name="policy-permissions-example-attach"></a>

```
# 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：後續步驟
<a name="policy-permissions-example-next"></a>

在 AgentCore 許可中使用所需的政策設定執行角色之後，請繼續建立和設定政策資源。如需詳細指引，請參閱：
+ 建立政策引擎 - 請參閱[建立政策引擎](policy-create-engine.md) 
+ 撰寫 Cedar 政策 - 請參閱 [Cedar 政策語言參考](https://docs.cedarpolicy.com) 

## 最佳實務
<a name="policy-permissions-best-practices"></a>

1.  **使用個別角色** - 維護 Amazon Bedrock AgentCore Gateway 執行和資源管理的不同角色

1.  **套用最低權限** - 從生產環境中的特定資源 ARNs 開始，而不是萬用字元

1.  **使用 LOG\_ONLY 模式進行測試** - 在強制執行政策之前，一律在 LOG\_ONLY 模式中測試政策引擎整合

1.  **啟用監控** - 設定 CloudWatch Logs 和 X-Ray 追蹤以進行故障診斷和可觀測性

1.  **版本控制政策** - 將 Cedar 政策與基礎設施程式碼一起存放在版本控制中

1.  **使用資源標籤** - 在 AgentCore 資源中套用標籤來組織和管理 Amazon Bedrock AgentCore Gateway 和政策

1.  **定期安全稽核** - 定期檢閱 IAM 政策，以確保其遵循最低權限原則