使用网关进行报头传播

什么是标题和查询参数传播

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

此功能作为分担责任模型运行：

标题限制

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

其他验证规则适用于允许的标头：

配置标题和查询参数传播

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

Target-level 配置

通过在目标中添加allowedRequestHeadersallowedResponseHeaders、和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 的标头传播

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

拦截器标头传播的工作原理

拦截器 lambda 可以通过以下方式影响标头传播：

在拦截器中实现标头传播

将拦截器 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']
            }
        }
    }

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

安全注意事项

使用拦截器 lambda 实现标头传播时，请遵循以下安全最佳实践：

最佳实践

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