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 を使用してヘッダー伝達を実装する場合は、次のセキュリティのベストプラクティスに従ってください。

ベストプラクティス

ヘッダー伝達を実装するときは、次のベストプラクティスに従ってください。