Propagation d'en-têtes avec Gateway

Qu'est-ce que la propagation des paramètres d'en-tête et de requête

La propagation des en-têtes fait référence au transfert systématique des en-têtes HTTP sélectifs des demandes entrantes via votre passerelle vers des cibles configurées, ainsi qu'au transfert sélectif des en-têtes de réponse au client. Tout comme la propagation des en-têtes, la propagation des paramètres de requête permet de transférer les paramètres de requête URL des demandes entrantes vers des cibles configurées. Cette fonctionnalité peut être utilisée dans les cas d'utilisation où vous devez échanger des informations de contexte, d'authentification, de suivi et d'autres informations critiques entre le client et les cibles. Les en-têtes pré-autorisés fournis lors de l'appel de l'outil d'appel à la passerelle ou envoyés par l'intercepteur personnalisé Lambda seront transmis aux cibles spécifiques.

Cette fonctionnalité fonctionne comme un modèle de responsabilité partagée :

Restrictions d'en-tête

Pour garantir la sécurité et empêcher la divulgation d'informations sensibles, les en-têtes suivants sont restreints et ne peuvent pas être configurés pour la propagation :

Des règles de validation supplémentaires s'appliquent aux en-têtes autorisés :

Configuration de la propagation des paramètres d'en-tête et de requête

Vous pouvez configurer les paramètres d'en-tête et de requête au niveau de la cible lors de la création ou de la mise à jour des cibles de passerelle. Les en-têtes et les paramètres de requête sont spécifiés par cible, ce qui garantit que chaque cible ne reçoit que les en-têtes dont elle a besoin.

Target-level configuration

Configurez la propagation des en-têtes en ajoutant allowedRequestHeadersallowedResponseHeaders, et allowedQueryParameters des champs à ceux de votre cible 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"
        ]
    }
}

À l'aide du 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']
    }
)

Propagation d'en-têtes depuis l'intercepteur Lambda

Lorsque vous utilisez des lambdas d'interception personnalisés avec votre passerelle, vous pouvez contrôler dynamiquement la propagation des en-têtes en incluant des en-têtes dans la réponse lambda de l'intercepteur.

Comment fonctionne la propagation des en-têtes de l'intercepteur

Les lambdas de l'intercepteur peuvent influencer la propagation des en-têtes de la manière suivante :

Implémentation de la propagation d'en-tête dans les intercepteurs

Configurez votre intercepteur lambda pour renvoyer des en-têtes qui doivent être propagés à la cible :

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

Les cas d'utilisation courants pour la propagation d'en-têtes d'intercepteur incluent :

Considérations sur la sécurité

Lorsque vous implémentez la propagation d'en-têtes avec des intercepteurs lambdas, suivez les meilleures pratiques de sécurité suivantes :

Bonnes pratiques

Suivez les meilleures pratiques suivantes lors de la mise en œuvre de la propagation des en-têtes :