# Amazon Bedrock AgentCore 的資源型政策
<a name="resource-based-policies"></a>

Amazon Bedrock AgentCore 中的資源型政策可讓您控制哪些主體 (AWS 帳戶、IAM 使用者或 IAM 角色） 可以叫用和管理 Amazon Bedrock AgentCore 資源 （目前支援執行期、閘道和記憶體）。您可以直接將 IAM 樣式政策連接到資源，以定義有關誰可以開始執行時間工作階段、叫用閘道、存取記憶體或執行其他管理和叫用動作的規則。

以資源為基礎的政策可與以身分為基礎的 IAM 政策搭配使用，為您的 Amazon Bedrock AgentCore 資源提供存取控制。雖然以身分為基礎的政策會連接到 IAM 身分，並指定他們可以執行的動作，但以資源為基礎的政策會直接連接到資源，並指定誰可以存取它們。

**Topics**
+ [支援的資源](#resource-based-policies-supported-resources)
+ [資源型政策的運作方式](#resource-based-policies-how-they-work)
+ [政策結構](#resource-based-policies-structure)
+ [支援的動作](#resource-based-policies-supported-actions)
+ [條件索引鍵](#resource-based-policies-condition-keys)
+ [常見使用案例和範例](#resource-based-policies-examples)
+ [管理資源政策](#resource-based-policies-managing)
+ [安全最佳實務](#resource-based-policies-best-practices)
+ [疑難排解](#resource-based-policies-troubleshooting)

## 支援的資源
<a name="resource-based-policies-supported-resources"></a>

Amazon Bedrock AgentCore 支援下列資源的資源型政策：
+  **代理程式執行期和代理程式端點** - 控制對代理程式呼叫和管理操作的存取
+  **Gateway** - 控制對閘道調用操作的存取
+  **記憶體** - 控制記憶體操作的存取

## 資源型政策的運作方式
<a name="resource-based-policies-how-they-work"></a>

### 以身分為基礎和以資源為基礎的政策之比較
<a name="resource-based-policies-vs-identity-based"></a>


| 面向 | 身分型政策 | 以資源為基礎政策 | 
| --- | --- | --- | 
| 連接 | 連接至 IAM 使用者、角色或群組 | 直接連接到 Amazon Bedrock AgentCore 資源 | 
| 管理 | 透過 IAM AWS 管理 | 透過 Amazon Bedrock AgentCore APIs進行管理 | 
| 指定 | 動作和資源 （主體是隱含的） | 主體、動作和條件 （資源為隱含） | 
| 使用案例 | 定義身分可以執行的動作 | 定義誰可以存取資源 | 

### 政策評估
<a name="resource-based-policies-evaluation"></a>

向 Amazon Bedrock AgentCore 資源提出請求時， 會 AWS 評估身分型和資源型政策。下表顯示不同的政策組合如何影響存取：


| IAM 政策 | 資源政策 | 結果 | 
| --- | --- | --- | 
| 授予存取權 | 靜音 | 允許 | 
| 授予存取權 | 授予存取權 | 允許 | 
| 授予存取權 | 拒絕存取 | 已拒絕 | 
| 靜音 | 靜音 | 已拒絕 | 
| 靜音 | 授予存取權 | 允許 | 
| 靜音 | 拒絕存取 | 已拒絕 | 
| 拒絕存取 | 靜音 | 已拒絕 | 
| 拒絕存取 | 允許存取 | 已拒絕 | 
| 拒絕存取 | 拒絕存取 | 已拒絕 | 

主要原則：
+  **明確拒絕永遠成功** ：如果任何政策明確拒絕動作，無論其他政策為何，都會拒絕存取
+  **政策可以允許** ：如果身分型或資源型政策允許 動作 （且沒有政策拒絕），則會授予存取權
+  **預設拒絕** ：如果沒有政策明確允許 動作，則會拒絕存取

### 代理程式執行期和端點的階層授權
<a name="resource-based-policies-hierarchical-authorization"></a>

代理程式端點是代理程式執行時間特定版本的可定址存取點。每個端點指向特定版本的執行時間組態，DEFAULT 端點會自動路由至最新版本。授權 `InvokeAgentRuntime`和 等執行時間 API `InvokeAgentRuntimeCommand` 操作時， 會針對要叫用的代理程式執行期和代理程式端點 AWS ，評估身分型和資源型政策。

若要授權請求，必須符合下列條件：
+ 連接到呼叫主體的身分型政策必須允許對代理程式執行期和代理程式端點資源執行 動作
+ 代理程式執行時間上的資源型政策必須允許 動作 （如果政策存在）
+ 代理程式端點上的資源型政策必須允許 動作 （如果政策存在）

**重要**  
若要提供委託人的跨帳戶存取權，您必須建立資源型政策****，同時授予代理程式執行期和代理程式端點的存取權。如果任一資源拒絕存取或缺少明確的允許陳述式，則會拒絕請求。

範例：授予跨帳戶存取需要兩個資源的政策：

```
// Policy for Agent Runtime (attached to
// arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID)
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/CrossAccountRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID"
        }
    ]
}

// Policy for Agent Endpoint (attached to
// arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID/endpoint/ENDPOINTID)
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/CrossAccountRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID/endpoint/ENDPOINTID"
        }
    ]
}
```

### 身分驗證類型考量事項
<a name="resource-based-policies-authentication-types"></a>

撰寫資源型政策的方式取決於為 Agent Runtime 或 Gateway 設定的身分驗證類型：

SigV4 身分驗證  
在 `Principal`元素中使用特定 AWS 委託人 (IAM 使用者、角色或帳戶）。例如：`"Principal": {"AWS": "arn:aws:iam::123456789012:role/MyRole"}`。政策會與發起人的 IAM 許可一起評估。如需限制執行時間只能由 AgentCore Gateway 叫用的範例，請參閱[限制 IAM (SigV4) 對閘道的傳入叫](runtime-oauth.md#runtime-restrict-iam-gateway)用。

OAuth 身分驗證  
必須在政策陳述式中使用萬用字元主體 ( "Principal"： "\*" )。OAuth 權杖會在政策評估之前由 AWS Identity Service 驗證。只有具有來自已註冊身分提供者 (IdP) 之有效 JWT 字符的已驗證 OAuth 使用者才能叫用資源。在政策評估之前，匿名或未驗證的請求會遭到拒絕。使用條件金鑰來限制存取 `aws:SourceVpc` （例如 、`aws:SourceVpce`)。

**重要**  
代理程式執行期或閘道只能在建立時以 SigV4 或 OAuth 身分驗證設定，不能同時設定兩者。這表示單一資源型政策僅適用於一種身分驗證類型。

## 政策結構
<a name="resource-based-policies-structure"></a>

以資源為基礎的政策是具有下列結構的 JSON 文件：

```
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "StatementId",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::account-id:role/role-name"
            },
            "Action": "bedrock-agentcore:ActionName",
            "Resource": "arn:aws:bedrock-agentcore:region:account-id:resource-type/resource-id",
            "Condition": {
                "ConditionOperator": {
                    "ConditionKey": "ConditionValue"
                }
            }
        }
    ]
}
```

**重要**  
政策文件中`Resource`的欄位必須包含政策所連接之資源的確切 ARN。不支援使用「資源」：「\*」，這會導致驗證錯誤。

## 支援的動作
<a name="resource-based-policies-supported-actions"></a>

### 代理程式執行時間動作
<a name="resource-based-policies-runtime-actions"></a>
+  `bedrock-agentcore:InvokeAgentRuntime` - 叫用代理程式執行時間
+  `bedrock-agentcore:InvokeAgentRuntimeForUser` - 使用 X-Amzn-Bedrock-AgentCore-Runtime-User-Id 標頭調用代理程式執行期端點
+  `bedrock-agentcore:InvokeAgentRuntimeCommand` - 在作用中執行階段工作階段中執行 shell 命令
+  `bedrock-agentcore:InvokeAgentRuntimeCommandShell` - 在作用中執行階段工作階段中開啟互動式 WebSocket shell 工作階段
+  `bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream` - 使用 WebSocket 串流調用代理程式執行時間
+  `bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStreamForUser` - 使用 X-Amzn-Bedrock-AgentCore-Runtime-User-Id 標頭搭配 WebSocket 串流調用代理程式執行期 X-Amzn-Bedrock-AgentCore-Runtime-User-Id 
+  `bedrock-agentcore:StopRuntimeSession` - 停止作用中的執行階段工作階段
+  `bedrock-agentcore:GetAgentCard` - 擷取客服人員卡資訊

### 閘道動作
<a name="resource-based-policies-gateway-actions"></a>
+  `bedrock-agentcore:InvokeGateway` - 叫用閘道

### 記憶體動作
<a name="resource-based-policies-memory-actions"></a>
+  `bedrock-agentcore:GetMemory` - 擷取記憶體資源
+  `bedrock-agentcore:UpdateMemory` - 更新記憶體資源
+  `bedrock-agentcore:DeleteMemory` - 刪除記憶體資源
+  `bedrock-agentcore:CreateEvent` - 在記憶體資源中建立事件
+  `bedrock-agentcore:GetEvent` - 從記憶體資源擷取事件
+  `bedrock-agentcore:DeleteEvent` - 從記憶體資源刪除事件
+  `bedrock-agentcore:ListEvents` - 列出來自記憶體資源的事件
+  `bedrock-agentcore:ListActors` - 列出來自記憶體資源的演員
+  `bedrock-agentcore:ListSessions` - 從記憶體資源列出工作階段
+  `bedrock-agentcore:GetMemoryRecord` - 從記憶體資源取得記憶體記錄
+  `bedrock-agentcore:ListMemoryRecords` - 列出來自記憶體資源的記憶體記錄
+  `bedrock-agentcore:RetrieveMemoryRecords` - 從記憶體資源搜尋記憶體記錄
+  `bedrock-agentcore:DeleteMemoryRecord` - 從記憶體資源刪除記憶體記錄
+  `bedrock-agentcore:BatchCreateMemoryRecords` - 在記憶體資源中批次建立記憶體記錄
+  `bedrock-agentcore:BatchUpdateMemoryRecords` - 批次更新記憶體資源中的記憶體記錄
+  `bedrock-agentcore:BatchDeleteMemoryRecords` - 批次刪除記憶體資源中的記憶體記錄
+  `bedrock-agentcore:StartMemoryExtractionJob` - 在記憶體資源中啟動擷取任務
+  `bedrock-agentcore:ListMemoryExtractionJobs` - 列出記憶體資源中的擷取任務

## 條件索引鍵
<a name="resource-based-policies-condition-keys"></a>

您可以使用條件索引鍵進一步精簡政策中的存取控制。如需可用條件金鑰的完整清單，請參閱 [Bedrock AgentCore 條件金鑰](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html)和[AWS 全域條件內容金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html)。

## 常見使用案例和範例
<a name="resource-based-policies-examples"></a>

本節提供常見案例的資源型政策實際範例。每個範例中`Resource`的欄位必須包含政策所連接之資源的確切 ARN。將範例 ARNs 取代為您的實際資源 ARNs。

### 允許另一個 AWS 帳戶中的角色
<a name="resource-based-policies-cross-account-example"></a>

將 API 存取權授予不同 AWS 帳戶中的特定角色：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::123456789012:role/DeveloperRole",
                    "arn:aws:iam::123456789012:role/AdminRole"
                ]
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID"
        }
    ]
}
```

### 根據來源 IP 地址拒絕流量
<a name="resource-based-policies-ip-restriction-example"></a>

封鎖來自特定 IP 地址範圍的傳入流量：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ApplicationRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID"
        },
        {
            "Effect": "Deny",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ApplicationRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID",
            "Condition": {
                "IpAddress": {
                    "aws:SourceIp": [
                        "192.0.2.0/24",
                        "198.51.100.0/24"
                    ]
                }
            }
        }
    ]
}
```

### 僅允許來自特定 VPC 的流量
<a name="resource-based-policies-vpc-restriction-example"></a>

限制存取來自特定 VPC 的請求：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ApplicationRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID"
        },
        {
            "Effect": "Deny",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ApplicationRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID",
            "Condition": {
                "StringNotEquals": {
                    "aws:SourceVpc": "vpc-1a2b3c4d"
                }
            }
        }
    ]
}
```

### 具有 VPC 限制的 OAuth 身分驗證
<a name="resource-based-policies-oauth-example"></a>

使用 OAuth 身分驗證設定 Agent Runtime 或 Gateway 時，您必須使用萬用字元主體。此範例會將 OAuth 驗證的請求限制為特定 VPC：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowOAuthFromVPC",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID",
            "Condition": {
                "StringEquals": {
                    "aws:SourceVpc": "vpc-1a2b3c4d"
                }
            }
        }
    ]
}
```

**重要**  
OAuth 身分驗證**需要**萬用字元主體 (「委託人」：「\*」)。OAuth 權杖會在政策評估之前由 AWS Identity Service 驗證。只有擁有您註冊身分提供者之有效 JWT 字符的使用者才能存取資源。在達到政策評估之前，匿名或未驗證的請求會遭到拒絕。使用條件金鑰 （例如 `aws:SourceVpc` 、) `aws:SourceVpce` 進一步限制存取

## 管理資源政策
<a name="resource-based-policies-managing"></a>

選取下列其中一種方法：

**Example**  

1. ====== 建立或更新資源政策

   使用 `put-resource-policy` 命令：

   ```
   aws bedrock-agentcore-control put-resource-policy \
       --resource-arn arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID \
       --policy file://policy.json
   ```

    **取得資源政策** 

   使用 `get-resource-policy` 命令：

   ```
   aws bedrock-agentcore-control get-resource-policy \
       --resource-arn arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
   ```

    **刪除資源政策** 

   使用 `delete-resource-policy` 命令：

   ```
   aws bedrock-agentcore-control delete-resource-policy \
       --resource-arn arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
   ```

1. 下列範例示範如何使用 AWS Python SDK (Boto3) 管理資源政策：

   ```
   import boto3
   import json
   
   client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
   
   # Define the resource ARN
   resource_arn = 'arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID'
   
   # Put resource policy
   # Note: The Resource field must match the resource ARN to which the policy is attached
   policy = {
   "Version": "2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {"AWS": "arn:aws:iam::123456789012:role/MyRole"},
               "Action": "bedrock-agentcore:InvokeAgentRuntime",
               "Resource": resource_arn
           }
       ]
   }
   
   response = client.put_resource_policy(
       resourceArn=resource_arn,
       policy=json.dumps(policy)
   )
   
   # Get resource policy
   response = client.get_resource_policy(
       resourceArn='arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID'
   )
   print(response['policy'])
   
   # Delete resource policy
   response = client.delete_resource_policy(
       resourceArn='arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID'
   )
   ```

## 安全最佳實務
<a name="resource-based-policies-best-practices"></a>

### 授予最低權限
<a name="resource-based-policies-least-privilege"></a>

僅授予使用案例所需的最低許可：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/ApplicationRole"
            },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID"
        }
    ]
}
```

### 防止混淆代理人
<a name="resource-based-policies-confused-deputy"></a>

授予 AWS 服務的存取權時，請務必使用條件金鑰：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/GATEWAYID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "bedrock-agentcore:InvokeGateway",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/GATEWAYID",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333"
                },
                "ArnEquals": {
                    "aws:SourceArn": "arn:aws:lambda:us-west-2:111122223333:function/SpecificFunction"
                }
            }
        }
    ]
}
```

### 對關鍵控制項使用明確拒絕
<a name="resource-based-policies-explicit-deny"></a>

針對安全關鍵限制使用明確拒絕陳述式：

```
// Policy attached to arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID
{
"Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "DenyAllExceptVPC",
            "Effect": "Deny",
            "Principal": "*",
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/AGENTID",
            "Condition": {
                "StringNotEquals": {
                    "aws:SourceVpc": "vpc-12345678"
                },
                "Bool": {
                    "aws:ViaAWSService": "false"
                }
            }
        }
    ]
}
```

## 疑難排解
<a name="resource-based-policies-troubleshooting"></a>

### 存取遭拒錯誤
<a name="resource-based-policies-access-denied"></a>

如果您收到「拒絕存取」錯誤：
+  **檢查兩個政策** ：驗證身分型和資源型政策
+  **尋找明確拒絕** ：任何政策中的明確拒絕會覆寫所有允許
+  **驗證委託人 ARN** ：確保政策中的委託人 ARN 符合發起人
+  **檢查條件** ：確認所有條件索引鍵評估為 true
+  **檢閱 SCPs**：組織服務控制政策可以覆寫資源政策

### 政策驗證錯誤
<a name="resource-based-policies-validation-errors"></a>

常見的政策驗證錯誤：
+  **無效的 JSON**：確保您的政策是有效的 JSON
+  **無效的 ARN 格式**：驗證所有 ARNs都遵循正確的格式
+  **不支援的動作** ：檢查資源類型是否支援所有動作
+  **缺少必要元素**：確保版本、陳述式、效果、主體和動作存在