As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Propagação de cabeçalho com Gateway

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

A propagação de cabeçalhos se refere ao encaminhamento sistemático de cabeçalhos HTTP seletivos de solicitações recebidas por meio de seu gateway para destinos configurados e ao encaminhamento seletivo de 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 os destinos configurados. Esse recurso pode ser usado em casos de uso em que você precisa trocar contexto, autenticação, rastreamento e outras informações críticas entre o cliente e os alvos. Os cabeçalhos pré-permitidos fornecidos na chamada da ferramenta de invocação para o gateway ou enviados do interceptor personalizado lambda serão encaminhados para os destinos 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 adicionais de validação se aplicam aos cabeçalhos permitidos:

Configurando a propagação do cabeçalho e do parâmetro 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 alvo, garantindo que cada alvo receba somente os cabeçalhos necessários.

Target-level configuração

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

{
    "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 de 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 interceptores 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 de cabeçalhos com lambdas de interceptores, siga estas melhores práticas de segurança:

Práticas recomendadas

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