使用 Gateway 進行標頭傳播

什麼是標頭和查詢參數傳播

標頭傳播是指透過閘道從傳入請求到已設定目標的選擇性 HTTP 標頭的系統性轉送，以及將回應標頭的選擇性轉送回用戶端。與標頭傳播類似，查詢參數傳播可讓 URL 查詢參數從傳入請求轉送到設定的目標。此功能可用於您需要在用戶端和目標之間交換內容、身分驗證、追蹤和其他重要資訊的使用案例。呼叫工具呼叫閘道或從自訂攔截器 lambda 傳送的預先允許清單標頭，將會轉送至特定目標。

此功能做為共同責任模型運作：

標頭限制

為了維護安全性並防止暴露敏感資訊，下列標頭受到限制，且無法設定為傳播：

其他驗證規則適用於允許的標頭：

設定標頭和查詢參數傳播

您可以在建立或更新閘道目標時，在目標層級設定標頭和查詢參數。每個目標指定標頭和查詢參數，確保每個目標僅接收所需的標頭。

目標層級組態

將 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 SDK：

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 實作標頭傳播時，請遵循下列安全最佳實務：

最佳實務

實作標頭傳播時，請遵循下列最佳實務：