Propagación de encabezados con Gateway

¿Qué es la propagación de encabezados y parámetros de consulta

La propagación de encabezados se refiere al reenvío sistemático de los encabezados HTTP selectivos de las solicitudes entrantes a través de la puerta de enlace a los destinos configurados, y al reenvío selectivo de los encabezados de respuesta al cliente. Al igual que la propagación de encabezados, la propagación de parámetros de consulta permite reenviar los parámetros de consulta de URL de las solicitudes entrantes a los destinos configurados. Esta función se puede utilizar en casos de uso en los que es necesario intercambiar información de contexto, autenticación, rastreo y otra información crítica entre el cliente y el destino. Los encabezados prepermitidos incluidos en la herramienta de invocación, llamada a la puerta de enlace o enviados desde el interceptor lambda personalizado, se reenviarán a los objetivos específicos.

Esta función funciona como un modelo de responsabilidad compartida:

Restricciones de encabezado

Para mantener la seguridad y evitar la exposición de información confidencial, los siguientes encabezados están restringidos y no se pueden configurar para su propagación:

Se aplican reglas de validación adicionales a los encabezados permitidos:

Configuración de la propagación de encabezados y parámetros de consulta

Puede configurar los parámetros de cabecera y consulta en el nivel de destino al crear o actualizar los destinos de la puerta de enlace. Los encabezados y los parámetros de consulta se especifican por destino, lo que garantiza que cada destino reciba solo los encabezados que necesita.

Target-level configuración

Configure la propagación del encabezado añadiendo allowedRequestHeaders y allowedQueryParameters campos a los de su objetivometadataConfiguration: allowedResponseHeaders

{
    "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"
        ]
    }
}

Uso del SDK de 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']
    }
)

Propagación del encabezado desde el interceptor lambda

Al utilizar lambdas interceptoras personalizadas con su puerta de enlace, puede controlar dinámicamente la propagación de los encabezados al incluir los encabezados en la respuesta lambda del interceptor.

Cómo funciona la propagación de los encabezados de los interceptores

Las lambdas interceptoras pueden influir en la propagación de las cabeceras de las siguientes maneras:

Implementación de la propagación de encabezados en los interceptores

Configura tu interceptor lambda para que devuelva los encabezados que deberían propagarse al objetivo:

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

Los casos de uso más comunes para la propagación de encabezados de interceptores incluyen:

Consideraciones de seguridad

Al implementar la propagación de encabezados con lambdas interceptoras, siga estas prácticas recomendadas de seguridad:

Prácticas recomendadas

Siga estas prácticas recomendadas al implementar la propagación de encabezados: