本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 身份验证和安全
<a name="connecting-to-devops-agent-remote-servers-authentication-and-security"></a>

两种身份验证方法可用于 MCP 和 A2A 端点：
+ **访问令牌（持有者）**— 单个令牌的作用域仅限于一个代理空间。最简单的设置，适合个人使用。
+ **AWS SigV4 ** — 基于 AWS 凭据的身份验证。支持多个代理空间并与现有 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 代理 IAM 权限](aws-devops-agent-security-devops-agent-iam-permissions.md)。

### 启用访问令牌
<a name="enable-access-tokens"></a>

1. 登录 AWS 管理控制台并打开 AWS DevOps 代理控制台。

1. 选择您的代理空间。

1. 选择**配置**选项卡。

1. 在**访问令牌**部分中，选择**启用**。

1. 确认该操作。

### 创建代币
<a name="create-a-token"></a>

1. 打开 DevOps 代理空间的代理 Web 应用程序，然后从导航菜单中选择 “**设置”**，然后选择 “**访问令牌” **。

1. 选择**生成令牌**。

1. 输入令牌的名称。

1. 选择范围：
   + `read`— 查看调查、推荐、聊天和代理空间资源。
   + `operate`— 完全访问权限。包括所有内容`read`，还可以发送消息、创建聊天以及管理待办事项任务和推荐。

1. 选择客户类型：
   + `human`— 用于 IDE 和 CLI（Kiro、Claude Code、Cursor 和其他交互式工具）。
   + `agent`— 用于自主的 A2A 集成和编程代理。

1. 设置到期时间（1 到 60 天）。

1. 复制代币值并将其存储在安全可靠的位置，例如[AWS 密钥管理器](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。你无法再次检索它。

创建令牌后，Web 应用程序会显示一个配置示例，您可以将其直接复制到客户端。

## 使用 SigV4 身份验证
<a name="use-sigv4-authentication"></a>

SigV4 身份验证使用您的 AWS 凭据而不是访问令牌。Kiro 的强大功能和 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 代理 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 范围内使用。来自其他 IP 的请求因访问被拒绝错误而被拒绝。

### 代币轮换和撤销
<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. **Re-enable 访问令牌 **-撤消已泄露的令牌后，如果您仍然需要基于令牌的访问权限，请从 ** “**配置” 选项卡中重新启用访问令牌。

#### 以编程方式撤消令牌
<a name="revoking-tokens-programmatically"></a>

您也可以使用编程方式撤消令牌。`awscurl`以下命令使用 SigV4 身份验证。将区域 (`us-east-1`) 替换为创建代理空间的区域。

**注意：**步骤 1 使用 AWS CLI。第 2 步和第 3 步使用 [ awscurl](https://github.com/okigan/awscurl)，这是一种使用 SigV4 签署 HTTP 请求的命令行工具，因为访问令牌操作尚没有专用 CLI 命令。 AWS 

**第 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 代理在中记录远程服务器活动 AWS CloudTrail。使用这些记录来追踪谁调用了远程服务器以及代理因此做了什么。 AWS DevOps 代理向托管代理空间的 AWS 账户传送 CloudTrail 事件。

#### 访问令牌身份验证事件
<a name="access-token-authentication-events"></a>

每次 AWS DevOps 代理对 MCP 或 A2A 端点的访问令牌进行身份验证时，它都会向发出一个事件。`AuthenticateAccessToken` CloudTrail 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 | 令牌进行身份验证的代理空间资源 (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`— 客户端 User-Agent 字符串（如果可用）。

代理代表您执行的每项操作都有一个相应的下游 AWS API 调用，用于 CloudTrail 记录。角色会话名称使用以下格式`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>


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| HTTP 401 未授权 | 令牌无效或已过期。 | 在 Web 应用程序中创建新令牌或轮换现有令牌。 | 
| HTTP 400 “需要A2A-Version 标头” | 缺少协议版本标头。仅支持 A2A v1.0。 | 向 A2A 请求添加A2A-Version: 1.0标头。 | 
| 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 |