Propagazione delle intestazioni con Gateway

Cos'è la propagazione dei parametri di intestazione e query

La propagazione delle intestazioni si riferisce all'inoltro sistematico di intestazioni HTTP selettive dalle richieste in entrata attraverso il gateway a destinazioni configurate e all'inoltro selettivo delle intestazioni di risposta al client. Analogamente alla propagazione delle intestazioni, la propagazione dei parametri di query consente l'inoltro dei parametri di query URL dalle richieste in entrata alle destinazioni configurate. Questa funzionalità può essere utilizzata nei casi d'uso in cui è necessario scambiare contesto, autenticazione, tracciamento e altre informazioni critiche tra client e destinazioni. Le intestazioni pre-consentite, fornite nella chiamata dello strumento di invoke a gateway o inviate da Custom Interceptor lambda, verranno inoltrate ai target specifici.

Questa funzionalità funziona come un modello di responsabilità condivisa:

Restrizioni relative all'intestazione

Per mantenere la sicurezza e prevenire l'esposizione di informazioni riservate, le seguenti intestazioni sono limitate e non possono essere configurate per la propagazione:

Alle intestazioni consentite si applicano regole di convalida aggiuntive:

Configurazione della propagazione dei parametri di intestazione e query

È possibile configurare i parametri di intestazione e query a livello di destinazione durante la creazione o l'aggiornamento delle destinazioni del gateway. Le intestazioni e i parametri di query vengono specificati per destinazione, assicurando che ogni destinazione riceva solo le intestazioni necessarie.

Target-level configurazione

Configura la propagazione dell'intestazione aggiungendo allowedRequestHeaders allowedQueryParameters campi e a quelli del tuo target: allowedResponseHeaders 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"
        ]
    }
}

Usando l'SDK 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']
    }
)

Propagazione dell'intestazione dall'interceptor lambda

Quando si utilizzano interceptor lambda personalizzati con il gateway, è possibile controllare dinamicamente la propagazione delle intestazioni includendo le intestazioni nella risposta lambda dell'interceptor.

Come funziona la propagazione degli interceptor header

Gli interceptor lambda possono influenzare la propagazione dell'intestazione nei seguenti modi:

Implementazione della propagazione delle intestazioni negli intercettori

Configura il tuo interceptor lambda per restituire le intestazioni che devono essere propagate al bersaglio:

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

I casi d'uso più comuni per la propagazione degli interceptor header includono:

Considerazioni relative alla sicurezza

Quando implementi la propagazione delle intestazioni con interceptor lambda, segui queste best practice di sicurezza:

Best practice

Segui queste best practice quando implementi la propagazione delle intestazioni: