Propagasi header dengan Gateway

Apa itu propagasi parameter header dan query

Propagasi header mengacu pada penerusan sistematis header HTTP selektif dari permintaan masuk melalui gateway Anda ke target yang dikonfigurasi, dan penerusan selektif header respons kembali ke klien. Mirip dengan propagasi header, propagasi parameter kueri memungkinkan penerusan parameter kueri URL dari permintaan masuk ke target yang dikonfigurasi. Fitur ini dapat digunakan untuk kasus penggunaan di mana Anda perlu bertukar konteks, otentikasi, penelusuran, dan informasi penting lainnya antara klien dan target. Header yang telah diijinkan sebelumnya yang disediakan dalam panggilan alat pemanggilan ke gateway atau dikirim dari lambda pencegat khusus, akan diteruskan ke target tertentu.

Fitur ini beroperasi sebagai model tanggung jawab bersama:

Pembatasan header

Untuk menjaga keamanan dan mencegah paparan informasi sensitif, header berikut dibatasi dan tidak dapat dikonfigurasi untuk propagasi:

Aturan validasi tambahan berlaku untuk header yang diizinkan:

Mengkonfigurasi propagasi parameter header dan kueri

Anda dapat mengonfigurasi parameter header dan kueri pada tingkat target saat membuat atau memperbarui target gateway. Header dan parameter kueri ditentukan per target, memastikan bahwa setiap target hanya menerima header yang dibutuhkannya.

Target-level konfigurasi

Konfigurasikan propagasi header dengan menambahkan allowedRequestHeadersallowedResponseHeaders,, dan allowedQueryParameters bidang ke target Anda: 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"
        ]
    }
}

Menggunakan 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']
    }
)

Propagasi header dari interceptor lambda

Saat menggunakan lambda pencegat khusus dengan gateway Anda, Anda dapat mengontrol propagasi header secara dinamis dengan menyertakan header dalam respons lambda pencegat Anda.

Cara kerja propagasi header interceptor

Interceptor lambda dapat mempengaruhi propagasi header dengan cara berikut:

Menerapkan propagasi header di pencegat

Konfigurasikan lambda pencegat Anda untuk mengembalikan header yang harus disebarkan ke target:

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']
            }
        }
    }

Kasus penggunaan umum untuk propagasi header pencegat meliputi:

Pertimbangan keamanan

Saat menerapkan propagasi header dengan lambda pencegat, ikuti praktik terbaik keamanan berikut:

Praktik terbaik

Ikuti praktik terbaik ini saat menerapkan propagasi header: