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

# 使用网关进行标头传播
<a name="gateway-headers"></a>

## 什么是标头和查询参数传播
<a name="gateway-headers-overview"></a>

标头传播是指系统地将来自传入请求的选择性 HTTP 标头通过您的网关转发到配置的目标，以及选择性地将响应标头转发回客户端。与标头传播类似，查询参数传播允许将 URL 查询参数从传入请求转发到配置的目标。此功能可用于需要在客户端和目标之间交换上下文、身份验证、跟踪和其他关键信息的用例。调用网关工具调用中提供的或从自定义拦截器 lambda 发送的预许可标头将转发到特定目标。

此功能作为责任共担模型运行：
+  Amazon 责任是安全地传递你为目标列入许可名单的标头和查询参数。
+ 你的责任是谨慎行事，**只允许那些对目标至关重要的头文件进行传播**，确保它们满足你的安全和功能要求。

### 标题限制
<a name="gateway-headers-restrictions"></a>

为了维护安全并防止敏感信息泄露，以下标头受到限制，无法配置为传播：


|  | 
| --- |
| 授权\* | 
| Proxy-Authorization | 
| WWW-Authenticate | 
| Accept | 
| Accept-Charset | 
| Accept-Encoding | 
| Accept-Language | 
| Content-Type | 
| Content-Length | 
| Content-Encoding | 
| Content-Language | 
| Content-Location | 
| Content-Range | 
| Cache-Control | 
| ETag | 
| 过期时间 | 
| If-Match | 
| If-Modified-Since | 
| If-None-Match | 
| If-Range | 
| If-Unmodified-Since | 
| Last-Modified | 
| Pragma | 
| 各不相同 | 
| Connection | 
| Keep-Alive | 
| Proxy-Connection | 
| 升级 | 
| 主机 | 
| User-Agent | 
| Referer | 
| 来源 | 
| Range | 
| Accept-Ranges | 
| Transfer-Encoding | 
| TE | 
| Trailer | 
| 服务器 | 
| 日期 | 
| 位置 | 
| Retry-After | 
| Set-Cookie | 
| Cookie | 
| Content-Security-Policy | 
| Content-Security-Policy-Report-Only | 
| Strict-Transport-Security | 
| X-Content-Type-Options | 
| X-Frame-Options | 
| X-XSS-Protection | 
| Referrer-Policy | 
| Permissions-Policy | 
| Cross-Origin-Embedder-Policy | 
| Cross-Origin-Opener-Policy | 
| Cross-Origin-Resource-Policy | 
| Access-Control-Allow-Origin | 
| Access-Control-Allow-Methods | 
| Access-Control-Allow-Headers | 
| Access-Control-Allow-Credentials | 
| Access-Control-Expose-Headers | 
| Access-Control-Max-Age | 
| Access-Control-Request-Method | 
| Access-Control-Request-Headers | 
| Origin | 
| Accept-CH | 
| Accept-CH-Lifetime | 
| 顿涅茨克人民共和国 | 
| 宽度 | 
| Viewport-Width | 
| 下行链路 | 
| 等等 | 
| RTT | 
| Save-Data | 
| Clear-Site-Data | 
| Feature-Policy | 
| Expect-CT | 
| Public-Key-Pins | 
| Public-Key-Pins-Report-Only | 
| X-Forwarded-For | 
| X-Forwarded-Host | 
| X-Forwarded-Proto | 
| X-Real-IP | 
| X-Requested-With | 
| X-CSRF-Token | 
| CF-Ray | 
| CF-Connecting-IP | 
| X-Amz-Cf-Id | 
| X-Cache | 
| X-Served-By | 
| :方法 | 
| :path | 
| :scheme | 
| :权威 | 
| :状态 | 
| Link | 
| Sec-WebSocket-Key | 
| Sec-WebSocket-Accept | 
| Sec-WebSocket-Version | 
| Sec-WebSocket-Protocol | 
| Sec-WebSocket-Extensions | 
+ 在创建目标期间，不能将授权标头列入许可名单。但是，当拦截器 lambda 提供时，它将被转发到目标。有关详细信息，请参阅拦截器 lambda [ 的](#gateway-headers-interceptor-propagation)标头传播。

**重要**  
除了上面提到的受限标头外，无法为标头传播配置 API 密钥和 REST API 架构中提供的标头。

其他验证规则适用于允许的标头：
+ 每个目标最多 10 个请求标头、10 个响应标头和 10 个查询参数，以防止滥用和保持性能
+ 标题名称必须仅包含字母数字字符、连字符和下划线（regex:）`^[a-zA-Z0-9_-]+$`
+ 标头值最大限制为 4KB，以防止内存耗尽
+ 标题值必须仅包含可打印的 ASCII 字符
+ 禁止使用以开头`X-Amzn-`的标题（ X-Amzn-Bedrock-AgentCore-Runtime-Custom-\* 标头除外）

## 配置标头和查询参数传播
<a name="gateway-headers-configuration"></a>

创建或更新网关目标时，可以在目标级别配置标头和查询参数。标头和查询参数是为每个目标指定的，从而确保每个目标仅接收其所需的标头。

### Target-level 配置
<a name="gateway-headers-target-level"></a>

通过向目标添加`allowedRequestHeaders``allowedResponseHeaders`、和`allowedQueryParameters`字段来配置标头传播`metadataConfiguration`：

```
{
    "name": "my-target",
    "description": "my target description",
    "credentialProviderConfigurations": [{
        "credentialProviderType": "OAUTH",
        "credentialProvider": {
            "oauthCredentialProvider": {
                "providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:credential-provider/example",
                "scopes": []
            }
        }
    }],
    "targetConfiguration": {
        "mcp": {
            "mcpServer": {
                "endpoint": "https://example.com/mcp"
            }
        }
    },
    "metadataConfiguration": {
        "allowedRequestHeaders": [
            "request-header"
        ],
        "allowedResponseHeaders": [
            "response-header"
        ],
        "allowedQueryParameters": [
            "query-param"
        ]
    }
}
```

使用 Python 软件开发工具包：

```
import boto3

# Initialize the client
client = boto3.client('bedrock-agentcore', region_name='us-west-2')

# Create target with header propagation
response = client.create_gateway_target(
    gatewayId='gateway-123',
    name='mcp-target-with-headers',
    description='MCP target with header propagation',
    targetConfiguration={
        'mcp': {
            'mcpServer': {
                'endpoint': 'https://example.com/mcp'
            }
        }
    },
    metadataConfiguration={
        'allowedRequestHeaders': ['x-correlation-id', 'x-tenant-id'],
        'allowedResponseHeaders': ['x-rate-limit-remaining'],
        'allowedQueryParameters': ['version']
    }
)
```

## 来自拦截器 lambda 的标头传播
<a name="gateway-headers-interceptor-propagation"></a>

在网关中使用自定义拦截器 lambda 时，您可以通过在拦截器 lambda 响应中加入标头来动态控制标头传播。

### 拦截器标头传播的工作原理
<a name="gateway-headers-interceptor-overview"></a>

拦截器 lambda 可以通过以下方式影响标头传播：
+  **授权标头覆盖：**来自拦截器 lambda 响应的`Authorization`标头会自动传播到目标。虽然无法在目标的允许列表中配置`Authorization`标头，但当拦截器 lambda 提供时，它将被转发到目标。

  例如，如果您向目标添加了凭证提供商，该提供者提供了授权令牌，例如`Authorization: Bearer client-token`拦截器 lambda 提供的授权令牌`Authorization: Bearer refreshed-token`，则`Bearer refreshed-token`来自拦截器 lambda 的值将被转发到目标。
+  **自定义标头注入：拦截器 lambda 响应中的**其他标头与配置的目标标头允许列表合并。
+  **标头优先级：**如果发生冲突，拦截器 lambda 提供的标头优先于客户端提供的标头。

  例如，如果您在目标配置`x-tenant-id`中加入允许列表标头，并且传入请求提供`x-tenant-id: tenant-123`而拦截器 lambda 提供`x-tenant-id: tenant-456`，则`tenant-456`来自拦截器 lambda 的值将被转发到目标。
+  **安全验证：**所有 lambda 提供的标头都要遵守与配置的标头相同的验证规则。除授权标头外，所有其他标头都必须在目标创建期间列入允许名单，才能将其转发到目标。

### 在拦截器中实现标头传播
<a name="gateway-headers-interceptor-implementation"></a>

将您的拦截器 lambda 配置为返回应传播到目标的标头：

```
import json
import boto3

def lambda_handler(event, context):
    # Extract request context
    request_context = event.get('requestContext', {})
    user_identity = request_context.get('identity', {})

    # Fetch credentials from secure store (example)
    credentials_client = boto3.client('secretsmanager')
    secret = credentials_client.get_secret_value(
        SecretId=f"mcp-credentials/{user_identity.get('userId')}"
    )

    credentials = json.loads(secret['SecretString'])

    # Return response with headers to propagate
    return {
        "interceptorOutputVersion": "1.0",
        "mcp": {
            "transformedGatewayRequest": {
                "headers": {
                    # Authorization header will be propagated automatically
                    "Authorization": f"Bearer {credentials['access_token']}",
                    # Custom headers (must be in target allowlist)
                    "x-tenant-id": user_identity.get('tenantId'),
                    "x-correlation-id": request_context.get('requestId')
                },
                "body": event['mcp']['gatewayRequest']['body']
            }
        }
    }
```

 **拦截器标头传播的常见用例包括：**

 **凭据获取 **   
从安全保管库中检索短期令牌并将其作为授权标头注入，防止客户端应用程序中的凭据泄露。

 **上下文注入 **   
添加租户标识符、组织上下文或用户属性，这些属性源自经过身份验证的用户声明，而不是信任客户提供的值。

 **标题转换 **   
在标头到达目标之前，根据业务逻辑、合规性要求或安全策略对其进行转换或清理。

 **动态路由 **   
根据对用户属性或系统状态的实时分析，注入路由提示、功能标志或 A/B 测试标头。

### 安全注意事项
<a name="gateway-headers-interceptor-security"></a>

使用拦截器 lambda 实现标头传播时，请遵循以下安全最佳实践：
+  **验证标头来源：**仅传播在目标许可清单中明确配置或由可信拦截器 lambda 返回的标头
+  **清理敏感数据：在将标头转发到外部 MCP 服务器之前，**删除或掩盖 PII 和敏感信息
+  **使用最低权限：使用凭据获取和上下文检索所需的最低权限**配置拦截器 lambda IAM 角色
+  **实施审计**日志：用于安全监控和合规性的日志标头转换和凭据获取活动
+  **验证标头内容：**确保 lambda 生成的标头符合与配置的标头相同的验证规则

## 最佳实践
<a name="gateway-headers-best-practices"></a>

在实现标头传播时，请遵循以下最佳实践：

 **使用特定目标配置 **   
为每个目标配置标头，而不是全局配置标头。不同的目标可能需要不同的标头，目标特定配置可提供更好的安全隔离。

 **尽量减少标题数 **   
仅传播目标实际需要的标头。过多的标头会增加请求大小和处理开销。

 **使用语义标题名称 **   
选择能清楚表明其用途的描述性标题名称，例如`x-correlation-id`用于跟踪或`x-tenant-id`多租户。

 **实现正确的错误处理 **   
处理必填标题缺失或无效的情况。考虑是使请求失败还是提供默认值。

 **监控标题使用情况 **   
使用网关可观察性功能来监控正在传播哪些标头，并确定标头验证或处理中的任何问题。

 **测试标头传播 **   
在开发和测试期间，验证标头是否已正确传播到您的目标。使用请求记录或调试端点等工具来验证标头流。