Propagação de cabeçalho com Gateway

O que é propagação de cabeçalhos e parâmetros de consulta

A propagação do cabeçalho se refere ao encaminhamento sistemático de cabeçalhos HTTP seletivos das solicitações recebidas por meio do gateway para destinos configurados e ao encaminhamento seletivo dos cabeçalhos de resposta de volta ao cliente. Semelhante à propagação de cabeçalho, a propagação de parâmetros de consulta permite o encaminhamento de parâmetros de consulta de URL das solicitações recebidas para destinos configurados. Esse recurso pode ser usado para casos de uso em que você precisa trocar contexto, autenticação, rastreamento e outras informações críticas entre o cliente e os destinos. Os cabeçalhos pré-permitidos fornecidos na chamada da ferramenta de invocação para o gateway ou enviados pelo interceptor personalizado lambda serão encaminhados para os alvos específicos.

Esse recurso funciona como um modelo de responsabilidade compartilhada:

restrições de cabeçalho

Para manter a segurança e evitar a exposição de informações confidenciais, os cabeçalhos a seguir são restritos e não podem ser configurados para propagação:

Regras de validação adicionais se aplicam aos cabeçalhos permitidos:

Configurando a propagação do cabeçalho e dos parâmetros de consulta

Você pode configurar parâmetros de cabeçalho e consulta no nível de destino ao criar ou atualizar destinos de gateway. Os cabeçalhos e os parâmetros de consulta são especificados por destino, garantindo que cada destino receba somente os cabeçalhos de que precisa.

Target-level configuração

Configure a propagação do cabeçalho adicionando allowedRequestHeadersallowedResponseHeaders,, e allowedQueryParameters campos aos do metadataConfiguration seu destino:

{
    "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 o SDK do 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']
    }
)

Propagação do cabeçalho a partir do interceptor lambda

Ao usar lambdas de interceptores personalizados com seu gateway, você pode controlar dinamicamente a propagação do cabeçalho incluindo cabeçalhos na resposta lambda do interceptor.

Como funciona a propagação do cabeçalho do interceptor

Os lambdas do Interceptor podem influenciar a propagação do cabeçalho das seguintes maneiras:

Implementando a propagação de cabeçalhos em interceptores

Configure seu interceptor lambda para retornar cabeçalhos que devem ser propagados para o destino:

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

Casos de uso comuns para propagação de cabeçalhos de interceptores incluem:

Considerações sobre segurança

Ao implementar a propagação do cabeçalho com lambdas do interceptor, siga estas melhores práticas de segurança:

Práticas recomendadas

Siga estas melhores práticas ao implementar a propagação de cabeçalhos: