aws-cdk-lib

import type { Construct } from 'constructs'; import type { GatewayExceptionLevel, IGateway } from './gateway-base'; import { GatewayBase } from './gateway-base'; import type { IGatewayAuthorizerConfig } from './inbound-auth/authorizer'; import type { IInterceptor } from './interceptor'; import type { ICredentialProviderConfig } from './outbound-auth/credential-provider'; import type { IGatewayProtocolConfig } from './protocol'; import type { IRestApi } from '../../../aws-apigateway'; import * as cognito from '../../../aws-cognito'; import * as iam from '../../../aws-iam'; import type * as kms from '../../../aws-kms'; import type { ApiSchema } from './targets/schema/api-schema'; import type { ToolSchema } from './targets/schema/tool-schema'; import { GatewayTarget } from './targets/target'; import type { ApiGatewayToolConfiguration, MetadataConfiguration } from './targets/target-configuration'; import type { IFunction } from '../../../aws-lambda'; /** * The enforcement mode for a policy engine associated with a gateway. * */ /****************************************************************************** * Props *****************************************************************************/ /** * Options for adding a Lambda target to a gateway */ export interface AddLambdaTargetOptions { /** * The name of the gateway target * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) * @default - auto generate */ readonly gatewayTargetName?: string; /** * Optional description for the gateway target * @default - No description */ readonly description?: string; /** * The Lambda function to associate with this target */ readonly lambdaFunction: IFunction; /** * The tool schema defining the available tools */ readonly toolSchema: ToolSchema; /** * Credential providers for authentication * @default - [GatewayCredentialProvider.iamRole()] */ readonly credentialProviderConfigurations?: ICredentialProviderConfig[]; } /** * Options for adding an OpenAPI target to a gateway */ export interface AddOpenApiTargetOptions { /** * The name of the gateway target * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) * @default - auto generate */ readonly gatewayTargetName?: string; /** * Optional description for the gateway target * @default - No description */ readonly description?: string; /** * The OpenAPI schema defining the API */ readonly apiSchema: ApiSchema; /** * Whether to validate the OpenAPI schema or not * Note: Validation is only performed for inline and asset-based schema and during CDK synthesis. * S3 schemas cannot be validated at synthesis time. * @default true */ readonly validateOpenApiSchema?: boolean; /** * Credential providers for outbound authentication (OpenAPI targets use API Key or OAuth, not IAM). * * @default - none (no credential configuration on the target; supply providers for secured backends) */ readonly credentialProviderConfigurations?: ICredentialProviderConfig[]; } /** * Options for adding a Smithy target to a gateway */ export interface AddSmithyTargetOptions { /** * The name of the gateway target * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) * @default - auto generate */ readonly gatewayTargetName?: string; /** * Optional description for the gateway target * @default - No description */ readonly description?: string; /** * The Smithy model defining the API */ readonly smithyModel: ApiSchema; /** * Credential providers for authentication * @default - [GatewayCredentialProvider.iamRole()] */ readonly credentialProviderConfigurations?: ICredentialProviderConfig[]; } /** * Options for adding an MCP Server target to a gateway */ export interface AddMcpServerTargetOptions { /** * The name of the gateway target * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) * @default - auto generate */ readonly gatewayTargetName?: string; /** * Optional description for the gateway target * @default - No description */ readonly description?: string; /** * The HTTPS endpoint URL of the MCP server * * The endpoint must: * - Use HTTPS protocol * - Be properly URL-encoded * - Point to an MCP server that implements tool capabilities */ readonly endpoint: string; /** * Credential providers for authentication * * MCP servers require explicit authentication configuration. * OAuth2 is strongly recommended over NoAuth. */ readonly credentialProviderConfigurations: ICredentialProviderConfig[]; } /** * Options for adding an API Gateway target to a gateway */ export interface AddApiGatewayTargetOptions { /** * The name of the gateway target * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) * @default - auto generate */ readonly gatewayTargetName?: string; /** * Optional description for the gateway target * @default - No description */ readonly description?: string; /** * The REST API to integrate with * Must be in the same account and region as the gateway * [disable-awslint:prefer-ref-interface] */ readonly restApi: IRestApi; /** * The stage name of the REST API * @default - Uses the deployment stage from the RestApi (restApi.deploymentStage.stageName) */ readonly stage?: string; /** * Tool configuration defining which operations to expose */ readonly apiGatewayToolConfiguration: ApiGatewayToolConfiguration; /** * Credential providers for authentication * API Gateway targets support IAM and API key authentication * @default - Empty array (service handles IAM automatically) */ readonly credentialProviderConfigurations?: ICredentialProviderConfig[]; /** * Metadata configuration for passing headers and query parameters * Allows you to pass additional context through headers and query parameters * @default - No metadata configuration */ readonly metadataConfiguration?: MetadataConfiguration; } /** * Properties for defining a Gateway */ export interface GatewayProps { /** * The name of the gateway * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) * The name must be unique within your account * @default - auto generate */ readonly gatewayName?: string; /** * Optional description for the gateway * Valid characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and spaces * The description can have up to 200 characters * @default - No description */ readonly description?: string; /** * The protocol configuration for the gateway * @default - A default protocol configuration will be created using MCP with following params * supportedVersions: [MCPProtocolVersion.MCP_2025_03_26], * searchType: McpGatewaySearchType.SEMANTIC, * instructions: "Default gateway to connect to external MCP tools", */ readonly protocolConfiguration?: IGatewayProtocolConfig; /** * The authorizer configuration for the gateway * @default - A default authorizer will be created using Cognito */ readonly authorizerConfiguration?: IGatewayAuthorizerConfig; /** * The verbosity of exception messages * Use DEBUG mode to see granular exception messages from a Gateway * @default - Exception messages are sanitized for presentation to end users */ readonly exceptionLevel?: GatewayExceptionLevel; /** * The AWS KMS key used to encrypt data associated with the gateway * @default - No encryption */ readonly kmsKey?: kms.IKey; /** * The IAM role that provides permissions for the gateway to access AWS services * @default - A new role will be created */ readonly role?: iam.IRole; /** * Tags for the gateway * A list of key:value pairs of tags to apply to this Gateway resource * @default - No tags */ readonly tags?: { [key: string]: string; }; /** * Interceptor configurations for the gateway * * Interceptors allow you to run custom code during each gateway invocation: * - REQUEST interceptors execute before the gateway calls the target * - RESPONSE interceptors execute after the target responds * * A gateway can have at most one REQUEST interceptor and one RESPONSE interceptor. * * @default - No interceptors * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-interceptors.html */ readonly interceptorConfigurations?: IInterceptor[]; } /** * Attributes for importing an existing Gateway */ export interface GatewayAttributes { /** * The ARN of the gateway */ readonly gatewayArn: string; /** * The ID of the gateway */ readonly gatewayId: string; /** * The name of the gateway */ readonly gatewayName: string; /** * The IAM role that provides permissions for the gateway */ readonly role: iam.IRole; } /****************************************************************************** * Class *****************************************************************************/ /** * Gateway resource for AWS Bedrock Agent Core. * Serves as an integration point between your agent and external services. * * @resource AWS::BedrockAgentCore::Gateway * @see https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html */ export declare class Gateway extends GatewayBase { /** Uniquely identifies this class. */ static readonly PROPERTY_INJECTION_ID: string; /** * Import an existing Gateway using its attributes * * @param scope The construct scope * @param id The construct id * @param attrs The attributes of the existing Gateway * @returns An IGateway instance representing the imported gateway */ static fromGatewayAttributes(scope: Construct, id: string, attrs: GatewayAttributes): IGateway; /** * The ARN of the gateway * @attribute */ readonly gatewayArn: string; /** * The unique identifier of the gateway * @attribute */ readonly gatewayId: string; /** * The name of the gateway */ readonly gatewayName: string; /** * The description of the gateway */ readonly description?: string; /** * The protocol configuration for the gateway */ readonly protocolConfiguration: IGatewayProtocolConfig; /** * The authorizer configuration for the gateway */ readonly authorizerConfiguration: IGatewayAuthorizerConfig; /** * The exception level for the gateway */ readonly exceptionLevel?: GatewayExceptionLevel; /** * The KMS key used for encryption */ readonly kmsKey?: kms.IKey; /** * The IAM role for the gateway */ readonly role: iam.IRole; /** * The URL endpoint for the gateway * @attribute */ readonly gatewayUrl?: string; /** * The status of the gateway * @attribute */ readonly status?: string; /** * The status reasons for the gateway * @attribute */ readonly statusReason?: string[]; /** * Timestamp when the gateway was created * @attribute */ readonly createdAt?: string; /** * Timestamp when the gateway was last updated * @attribute */ readonly updatedAt?: string; /** * Tags applied to the gateway */ readonly tags?: { [key: string]: string; }; /** * The Cognito User Pool created for the gateway (if using default Cognito authorizer) */ userPool?: cognito.IUserPool; /** * The Cognito User Pool Client created for the gateway (if using default Cognito authorizer) */ userPoolClient?: cognito.IUserPoolClient; /** * The REQUEST interceptor configuration * @internal */ private requestInterceptorConfig?; /** * The RESPONSE interceptor configuration * @internal */ private responseInterceptorConfig?; /** * The Cognito User Pool Domain created for the gateway (if using default Cognito authorizer) */ userPoolDomain?: cognito.IUserPoolDomain; /** * The Cognito Resource Server created for the gateway (if using default Cognito authorizer) */ resourceServer?: cognito.IUserPoolResourceServer; /** * The OAuth2 token endpoint URL for client credentials flow. * Only available when using the default Cognito authorizer. */ readonly tokenEndpointUrl?: string; /** * The OAuth2 scope strings for client credentials flow. * Only available when using the default Cognito authorizer. */ readonly oauthScopes?: string[]; constructor(scope: Construct, id: string, props?: GatewayProps); /** * Add a Lambda target to this gateway * This is a convenience method that creates a GatewayTarget associated with this gateway * * @param id The construct id for the target * @param props Properties for the Lambda target * @returns The created GatewayTarget */ addLambdaTarget(id: string, props: AddLambdaTargetOptions): GatewayTarget; /** * Add an OpenAPI target to this gateway * This is a convenience method that creates a GatewayTarget associated with this gateway * * @param id The construct id for the target * @param props Properties for the OpenAPI target * @returns The created GatewayTarget */ addOpenApiTarget(id: string, props: AddOpenApiTargetOptions): GatewayTarget; /** * Add a Smithy target to this gateway * This is a convenience method that creates a GatewayTarget associated with this gateway * * @param id The construct id for the target * @param props Properties for the Smithy target * @returns The created GatewayTarget */ addSmithyTarget(id: string, props: AddSmithyTargetOptions): GatewayTarget; /** * Add an MCP server target to this gateway * This is a convenience method that creates a GatewayTarget associated with this gateway * * @param id The construct id for the target * @param props Properties for the MCP server target * @returns The created GatewayTarget * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html */ addMcpServerTarget(id: string, props: AddMcpServerTargetOptions): GatewayTarget; /** * Add an API Gateway target to this gateway * This is a convenience method that creates a GatewayTarget associated with this gateway * * @param id The construct id for the target * @param props Properties for the API Gateway target * @returns The created GatewayTarget * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html */ addApiGatewayTarget(id: string, props: AddApiGatewayTargetOptions): GatewayTarget; /** * Creates the service role for the gateway to assume * * The service role starts with minimal permissions. Additional permissions * are added automatically when targets are configured: * - KMS encryption: Automatically grants encrypt/decrypt permissions * * For other target types, manually grant permissions using standard CDK grant methods: * @internal */ private createGatewayRole; /** * Validates the gateway name format * Pattern: ^([0-9a-zA-Z][-]?){1,48}$ * Max length: 48 characters * @param name The gateway name to validate * @throws Error if the name is invalid * @internal */ private validateGatewayName; /** * Validates the description format * Max length: 200 characters * @param description The description to validate * @throws Error if validation fails * @internal */ private validateDescription; /** * Creates a default Cognito authorizer for the gateway * Provisions a Cognito User Pool and configures M2M (machine-to-machine) JWT authentication * using OAuth 2.0 client credentials grant flow * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-idp-cognito.html * @internal */ private createDefaultCognitoAuthorizerConfig; /** * Creates a default MCP protocol configuration for the gateway * Provides sensible defaults for MCP protocol settings * @internal */ private createDefaultMcpProtocolConfiguration; /** * Add an interceptor to this gateway * * Interceptors allow you to run custom code at specific points in the gateway request/response flow: * - REQUEST interceptors execute before the gateway calls the target * - RESPONSE interceptors execute after the target responds * * A gateway can have at most one REQUEST interceptor and one RESPONSE interceptor. * @param interceptor The interceptor to add (use LambdaInterceptor factory methods) * @throws Error if an interceptor of the same type already exists */ addInterceptor(interceptor: IInterceptor): void; /** * Validates and initializes interceptors from the provided configurations * @internal */ private validateAndInitializeInterceptors; /** * Renders the interceptor configurations for CloudFormation * Returns undefined if no interceptors are configured * @internal */ private renderInterceptorConfigurations; }