Gateway를 사용한 헤더 전파

헤더 및 쿼리 파라미터 전파란 무엇입니까?

헤더 전파는 게이트웨이를 통해 수신되는 요청에서 구성된 대상으로 선택적 HTTP 헤더를 체계적으로 전달하고 응답 헤더를 클라이언트로 다시 선택적으로 전달하는 것을 말합니다. 헤더 전파와 마찬가지로 쿼리 파라미터 전파를 사용하면 수신 요청의 URL 쿼리 파라미터를 구성된 대상으로 전달할 수 있습니다. 이 기능은 클라이언트와 대상 간에 컨텍스트, 인증, 추적 및 기타 중요한 정보를 교환해야 하는 사용 사례에 사용할 수 있습니다. 게이트웨이에 대한 호출 도구 호출에 제공되거나 사용자 지정 인터셉터 Lambda에서 전송된 사전 허용 목록에 있는 헤더는 특정 대상으로 전달됩니다.

이 기능은 공동 책임 모델로 작동합니다.

헤더 제한

보안을 유지하고 민감한 정보의 노출을 방지하기 위해 다음 헤더는 제한되며 전파를 위해 구성할 수 없습니다.

허용되는 헤더에는 추가 검증 규칙이 적용됩니다.

헤더 및 쿼리 파라미터 전파 구성

게이트웨이 대상을 생성하거나 업데이트할 때 대상 수준에서 헤더 및 쿼리 파라미터를 구성할 수 있습니다. 헤더 및 쿼리 파라미터는 대상별로 지정되므로 각 대상이 필요한 헤더만 수신할 수 있습니다.

대상 수준 구성

대상의에 allowedRequestHeaders , allowedResponseHeaders 및 allowedQueryParameters 필드를 추가하여 헤더 전파를 구성합니다. 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"
        ]
    }
}

Python SDK 사용:

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

인터셉터 Lambda에서 헤더 전파

게이트웨이와 함께 사용자 지정 인터셉터 Lambda를 사용하는 경우 인터셉터 Lambda 응답에 헤더를 포함하여 헤더 전파를 동적으로 제어할 수 있습니다.

인터셉터 헤더 전파 작동 방식

인터셉터 람다는 다음과 같은 방식으로 헤더 전파에 영향을 미칠 수 있습니다.

인터셉터에서 헤더 전파 구현

대상에 전파해야 하는 헤더를 반환하도록 인터셉터 Lambda를 구성합니다.

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

인터셉터 헤더 전파의 일반적인 사용 사례는 다음과 같습니다.

보안 고려 사항

인터셉터 Lambda를 사용하여 헤더 전파를 구현할 때는 다음 보안 모범 사례를 따르세요.

모범 사례

헤더 전파를 구현할 때는 다음 모범 사례를 따르세요.