本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 身分驗證和安全性
<a name="connecting-to-devops-agent-remote-servers-authentication-and-security"></a>

MCP 和 A2A 端點皆可使用兩種身分驗證方法：
+ **存取字符 （承載）** – 範圍為一個客服人員空間的單一字符。用於個別用途的最簡單設定。
+ **AWS SigV4** – AWS 以憑證為基礎的身分驗證。支援多個 Agent Spaces，並與現有的 AWS 身分控管整合。由 [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) 自動處理，這是使用登入 AWS 資料簽署請求的本機代理。

## 建立存取字符
<a name="create-an-access-token"></a>

### 先決條件
<a name="prerequisites"></a>
+ 必須在您的客服人員空間上啟用存取權杖功能。
+ 您必須擁有 IAM 許可才能管理存取權杖 (`aidevops:CreateAccessToken`、`aidevops:RevokeAccessToken`、`aidevops:RotateAccessToken`)。如需完整清單，請參閱[DevOps Agent IAM 許可](aws-devops-agent-security-devops-agent-iam-permissions.md)。

### 啟用存取權杖
<a name="enable-access-tokens"></a>

1. 登入 AWS 管理主控台並開啟 AWS DevOps 代理程式主控台。

1. 選擇您的客服人員空間。

1. 選擇 **Configuration** (組態) 索引標籤。

1. 在**存取字符**區段中，選擇**啟用**。

1. 確認動作。

### 建立權杖
<a name="create-a-token"></a>

1. 開啟代理程式空間的 DevOps 代理程式 Web 應用程式，然後從導覽功能表中選擇**設定**，然後選擇**存取字符**。

1. 選擇 **Generate token (產生字符)**。

1. 輸入字符的名稱。

1. 選擇範圍：
   + `read` – 檢視調查、建議、聊天和客服人員空間資源。
   + `operate` – 完整存取。包含 中的所有內容`read`，以及傳送訊息、建立聊天和管理待處理任務和建議。

1. 選擇用戶端類型：
   + `human` – 適用於 IDE 和 CLI 使用 (Kiro、Claude Code、Cursor 和其他互動式工具）。
   + `agent` – 用於自動 A2A 整合和程式設計代理程式。

1. 設定過期時間 (1 到 60 天）。

1. 複製字符值並存放在安全的位置，例如 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。您無法再次擷取它。

建立字符之後，Web 應用程式會顯示組態範例，您可以直接複製到用戶端。

## 使用 SigV4 身分驗證
<a name="use-sigv4-authentication"></a>

SigV4 身分驗證使用您的 AWS 登入資料，而非存取字符。Kiro power 和 Claude Code 外掛程式包含透過 的內建 SigV4 支援`mcp-proxy-for-aws`，這會使用本機 AWS 登入資料簽署請求。

### 使用 SigV4 時
<a name="when-sigv4-is-used"></a>
+ 當存取權杖未設定或失敗 （過期、無效） 時做為**備用**。
+ 當您有多個客服人員空間且需要`agent_space_id`每個工具呼叫路由 時，做為**主要**身分驗證。
+ 作為**使用者選擇** – 在 Claude Code 中，執行安裝技能以從 Bearer 權杖切換到 SigV4 驗證。

### 先決條件
<a name="prerequisites"></a>
+ AWS 環境中可用的登入資料 （透過 SSO、環境變數或登入資料檔案）。
+ 您的登入資料必須具有叫用 AWS DevOps 代理程式動作的許可。如要了解必要的許可，請參閱 [DevOps Agent IAM 許可](aws-devops-agent-security-devops-agent-iam-permissions.md)。
+ `uvx` 已安裝 （代理透過 執行`uvx mcp-proxy-for-aws@latest`)。

### 範例組態
<a name="example-configuration"></a>

若要將 MCP 用戶端設定為使用 SigV4 而非存取字符，請透過 執行伺服器`mcp-proxy-for-aws`。`{region}` 將 取代為 代理程式空間的區域 （例如 `us-east-1`)：

```
{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://connect.aidevops.{region}.api.aws/mcp",
        "--service", "aidevops",
        "--region", "{region}"
      ]
    }
  }
}
```

代理會使用本機 AWS 登入資料簽署每個請求，因此不需要存取字符。

### Multi-Agent-Space路由
<a name="multi-agent-space-routing"></a>

在 SigV4 模式中，`agent_space_id`傳遞每個工具呼叫，以指定要使用的客服人員空間。這可讓您從單一用戶端跨多個客服人員空間進行路由。

## 安全考量
<a name="security-considerations"></a>

### 權杖範圍
<a name="token-scoping"></a>
+ 使用最低權限：`operate`只有在用戶端需要傳送訊息或管理任務時，`read`才為唯讀整合選擇 。
+ 定期輪換權杖。字符會在設定的持續時間後過期 （最長 60 天）。
+ 將權杖儲存在環境變數或秘密管理員中。請勿在原始程式碼中硬式編碼字符。
+ 未經人工審核，請勿自動執行客服人員回應。

### IP 允許清單
<a name="ip-allowlist"></a>

建立存取權杖時，您可以選擇指定 IP 允許清單。設定後，字符只能從指定的 IP 地址或 CIDR 範圍使用。來自其他 IPs請求會因存取遭拒錯誤而遭到拒絕。

### 權杖輪換和撤銷
<a name="token-rotation-and-revocation"></a>
+ **輪換** – 輪換權杖以產生新的權杖值，同時保留權杖的名稱、範圍和 IP 允許清單。舊字符會立即失效。使用新的字符值更新您的用戶端組態。輪換也會啟動新的聊天歷史記錄，請參閱下一節。
+ **撤銷** – 如果權杖洩露，請立即撤銷權杖。撤銷的權杖無法使用，也無法還原。

#### 聊天歷史記錄和字符輪換
<a name="chat-history-and-token-rotation"></a>

每個字符都有自己的聊天歷史記錄。當您輪換權杖時， AWS DevOps 代理程式會將新的權杖值視為新的身分。您使用上一個字符建立的聊天不會再透過遠端伺服器顯示。

#### 回應遭到入侵的字符
<a name="responding-to-a-compromised-token"></a>

如果您懷疑字符已洩露，請遵循下列步驟：

1. **封鎖所有字符存取** – 在 AWS DevOps 代理程式主控台中，開啟您的代理程式空間，選擇**組態**索引標籤，然後在存取字符區段中選擇**停用**。這會立即封鎖對 代理程式空間的所有字符型存取。

1. **撤銷洩露的字符** – 在 Web 應用程式中，前往**設定** > **存取字符**，選擇洩露的字符，然後選擇**撤銷**。即使停用存取權杖，您也可以撤銷權杖。

1. **重新啟用存取字符** – 撤銷遭到入侵的字符之後，如果您仍然需要字符型存取，請從**組態**索引標籤重新啟用存取字符。

#### 以程式設計方式撤銷權杖
<a name="revoking-tokens-programmatically"></a>

您也可以使用 以程式設計方式撤銷權杖`awscurl`。下列命令使用 SigV4 身分驗證。將區域 (`us-east-1`) 取代為建立客服人員空間的區域。

**注意：**步驟 1 使用 AWS CLI。步驟 2 和 3 使用 [awscurl](https://github.com/okigan/awscurl)，這是使用 SigV4 簽署 HTTP 請求的命令列工具，因為存取字符操作尚未有專用的 AWS CLI 命令。

**步驟 1：列出您的客服人員空間**

```
aws aidevops list-agent-spaces --region us-east-1
```

**步驟 2：列出客服人員空間的存取權杖**

```
awscurl --service aidevops --region us-east-1 \
  -H "Accept: application/json" \
  "https://cp.aidevops.us-east-1.api.aws/v1/agentspaces/{agentSpaceId}/access-tokens"
```

**步驟 3：撤銷權杖**

```
awscurl --service aidevops --region us-east-1 -X POST \
  -H "Accept: application/json" \
  "https://cp.aidevops.us-east-1.api.aws/v1/agentspaces/{agentSpaceId}/access-tokens/{accessTokenId}/revoke"
```

將 `{agentSpaceId}`和 取代`{accessTokenId}`為先前回應中的值。

### 可追蹤性
<a name="traceability"></a>

AWS DevOps Agent 會在 AWS CloudTrail 中記錄遠端伺服器活動。使用這些記錄來追蹤誰叫用遠端伺服器，以及代理程式執行的動作。 AWS DevOps 代理程式會將 CloudTrail 事件交付至託管代理程式空間 AWS 的帳戶。

#### 存取字符身分驗證事件
<a name="access-token-authentication-events"></a>

每次 AWS DevOps 代理程式驗證 MCP 或 A2A 端點的存取字符時，都會向 CloudTrail 發出`AuthenticateAccessToken`事件。 AWS DevOps 代理程式會記錄成功和失敗的身分驗證。使用這些記錄來稽核合法使用，並偵測遭到拒絕的嘗試。範例包括過期或撤銷的權杖，以及 IP 允許清單封鎖的請求。

事件具有下列特性：
+ **事件來源** – `aidevops.amazonaws.com`
+ **事件名稱** – `AuthenticateAccessToken`
+ **管理事件** – 事件是管理事件，而且不是唯讀，因此在您篩選掉唯讀事件時仍然可見。

事件包含下列金鑰欄位：


| 欄位 | 說明 | 
| --- | --- | 
| userIdentity.principalId | 呈現的存取權杖 ID。 | 
| userName | 存取字符的名稱。 | 
| requestParameters.agentSpaceId | 字符驗證的代理程式空間。 | 
| requestParameters.accessTokenId | 存取權杖 ID。 | 
| requestParameters.tokenName | 存取字符名稱。 | 
| requestParameters.protocol | 使用的通訊協定 -MCP 或 A2A。 | 
| responseElements.AuthenticateAccessToken | 結果 -Success 或 Failure。 | 
| resources | 權杖驗證的 Agent Space 資源 (AWS::AIDevOps::AgentSpace)，由其 ARN 識別。 | 
| additionalEventData.roleSessionName | 對於成功的身分驗證，下游角色工作階段名稱的格式為 token\_{spaceId}\_{timestamp}\_{tokenName}。使用它將身分驗證與代理程式執行的動作建立關聯。 | 
| sourceIPAddress | 用戶端的 IP 地址。 | 
| userAgent | 用戶端 User-Agent 字串，可用時。 | 
| errorCode, errorMessage | 對於失敗的身分驗證，拒絕身分驗證的原因。 | 

**注意**  
** AWS DevOps 代理程式絕不會記錄原始承載字符值。只有不透明的存取權杖 ID 會出現在事件中。

#### 下游動作事件
<a name="downstream-action-events"></a>

當您使用存取字符時， AWS DevOps 代理程式會代表您擔任角色以執行動作。 AWS DevOps 代理程式會在 CloudTrail 中記錄此`AssumeRole`呼叫，其中包含可識別字符和呼叫者的工作階段標籤：
+ `AgentSpaceId` – 客服人員空間的識別符。
+ `UserId` – 權杖建立者的身分。
+ `AccessTokenId` – 字符的唯一識別符。
+ `TokenName` – 使用的存取字符名稱。
+ `ClientType` – 使用的通訊協定 (MCP、A2A)。
+ `SourceIp` – 用戶端的 IP 地址。
+ `UserAgent` – 用戶端使用者代理程式字串 （可用時）。

代理程式代表您採取的每個動作都有 CloudTrail 記錄的對應下游 AWS API 呼叫。角色工作階段名稱使用 格式 `token_{spaceId}_{timestamp}_{tokenName}`。此工作階段名稱符合 `AuthenticateAccessToken` 事件`roleSessionName`中的 。使用它從身分驗證追蹤到之後的特定動作。

#### SigV4 調用
<a name="sigv4-invocations"></a>

使用 AWS SigV4 身分驗證而非存取字符的調用不會產生`AuthenticateAccessToken`事件。 AWS DevOps 代理程式會將 SigV4 請求歸因於您的身分 AWS 與存取管理 (IAM) 身分。您可以追蹤代理程式透過其觸發的下游 AWS API 呼叫執行的動作。

### VPC 端點政策限制
<a name="vpc-endpoint-policy-limitation"></a>

遠端伺服器端點不支援 VPC 端點政策。VPC 端點政策無法限制使用存取字符或 SigV4 身分驗證的呼叫。

### 停用存取權杖
<a name="disabling-access-tokens"></a>

存取字符功能預設為關閉。若要在啟用後停用它：

1. 開啟 代理程式空間的**組態**索引標籤。

1. 在**存取字符**區段中，選擇**停用**。

停用會立即封鎖所有字符型存取。現有的字符不會刪除，但在重新啟用功能之前無法使用。

為了防止組織中的使用者啟用存取權杖，請建立拒絕存取權杖 API 動作和 `UpdateAgentSpace` 動作 （控制存取權杖切換） 的服務控制政策 (SCP)：

**注意：**拒絕`aidevops:UpdateAgentSpace`也會防止其他客服人員空間更新 （名稱、描述、地區設定）。如果太廣泛，請將其從 SCP 中省略 — 剩餘的拒絕仍然會阻止權杖建立和使用，即使有人啟用此功能。

```
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Sid": "DenyAccessTokenOperations",
      "Effect": "Deny",
      "Action": [
        "aidevops:UpdateAgentSpace",
        "aidevops:CreateAccessToken",
        "aidevops:GetAccessToken",
        "aidevops:ListAccessTokens",
        "aidevops:RotateAccessToken",
        "aidevops:RevokeAccessToken"
      ],
      "Resource": "*"
    }
  ]
}
```

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


| 徵狀 | 原因 | Resolution | 
| --- | --- | --- | 
| HTTP 401 未授權 | 字符無效或過期。 | 在 Web 應用程式中建立新的字符或輪換現有的字符。 | 
| HTTP 400 "需要 A2A-Version 標頭" | 缺少通訊協定版本標頭。僅支援 A2A v1.0。 | 將A2A-Version: 1.0標頭新增至 A2A 請求。 | 
| HTTP 400「客服人員空間未從登入資料解析」 | A2A \+ SigV4 請求不包含 X-Agent-Space-Id標頭。 | 將 X-Agent-Space-Id: <agentSpaceId>新增至請求。 | 
| 請求逾時 | 初始回應需要 5-30 秒。調查需要 5-8 分鐘。 | 將用戶端逾時設定為至少 120 秒。 | 
| 連線遭拒 | 不正確的端點 URL 或區域。 | 驗證 URL 格式： https://connect.aidevops.{region}.api.aws |