feat(apigatewayv2): Lambda authorizer for WebSocket API

packages/@aws-cdk/aws-apigatewayv2-authorizers/README.md

@@ -22,9 +22,11 @@
 - [HTTP APIs](#http-apis)
  - [Default Authorization](#default-authorization)
  - [Route Authorization](#route-authorization)
-- [JWT Authorizers](#jwt-authorizers)
- - [User Pool Authorizer](#user-pool-authorizer)
-- [Lambda Authorizers](#lambda-authorizers)
+ - [JWT Authorizers](#jwt-authorizers)
+ - [User Pool Authorizer](#user-pool-authorizer)
+ - [Lambda Authorizers](#lambda-authorizers)
+- [WebSocket APIs](#websocket-apis)
+ - [Lambda Authorizer](#lambda-authorizer)
 
 ## Introduction
 
@@ -37,7 +39,7 @@ API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-acces
 
 Access control for Http Apis is managed by restricting which routes can be invoked via.
 
-Authorizers, and scopes can either be applied to the api, or specifically for each route.
+Authorizers and scopes can either be applied to the api, or specifically for each route.
 
 ### Default Authorization
 
@@ -110,7 +112,7 @@ api.addRoutes({
 });
 ```
 
-## JWT Authorizers
+### JWT Authorizers
 
 JWT authorizers allow the use of JSON Web Tokens (JWTs) as part of [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) and [OAuth 2.0](https://oauth.net/2/) frameworks to allow and restrict clients from accessing HTTP APIs.
 
@@ -144,7 +146,7 @@ api.addRoutes({
 });
 ```
 
-### User Pool Authorizer
+#### User Pool Authorizer
 
 User Pool Authorizer is a type of JWT Authorizer that uses a Cognito user pool and app client to control who can access your Api. After a successful authorization from the app client, the generated access token will be used as the JWT.
 
@@ -170,7 +172,7 @@ api.addRoutes({
 });
 ```
 
-## Lambda Authorizers
+### Lambda Authorizers
 
 Lambda authorizers use a Lambda function to control access to your HTTP API. When a client calls your API, API Gateway invokes your Lambda function and uses the response to determine whether the client can access your API.
 
@@ -196,3 +198,36 @@ api.addRoutes({
  authorizer,
 });
 ```
+
+## WebSocket APIs
+
+You can set an authorizer to your WebSocket API's `$connect` route to control access to your API.
+
+### Lambda Authorizer
+
+Lambda authorizers use a Lambda function to control access to your WebSocket API. When a client connects to your API, API Gateway invokes your Lambda function and uses the response to determine whether the client can access your API.
+
+```ts
+import { WebSocketLambdaAuthorizer } from '@aws-cdk/aws-apigatewayv2-authorizers';
+import { WebSocketLambdaIntegration } from '@aws-cdk/aws-apigatewayv2-integrations';
+
+// This function handles your auth logic
+declare const authHandler: lambda.Function;
+
+// This function handles your WebSocket requests
+declare const handler: lambda.Function;
+
+const authorizer = new WebSocketLambdaAuthorizer('Authorizer', authHandler);
+
+const integration = new WebSocketLambdaIntegration(
+ 'Integration',
+ handler,
+);
+
+new apigwv2.WebSocketApi(this, 'WebSocketApi', {
+ connectRouteOptions: {
+ integration,
+ authorizer,
+ },
+});
+```

packages/@aws-cdk/aws-apigatewayv2-authorizers/lib/index.ts

@@ -1 +1,2 @@
 export * from './http';
+export * from './websocket';

packages/@aws-cdk/aws-apigatewayv2-authorizers/lib/websocket/index.ts

@@ -0,0 +1 @@
+export * from './lambda';

packages/@aws-cdk/aws-apigatewayv2-authorizers/lib/websocket/lambda.ts

@@ -0,0 +1,89 @@
+import {
+ WebSocketAuthorizer,
+ WebSocketAuthorizerType,
+ WebSocketRouteAuthorizerBindOptions,
+ WebSocketRouteAuthorizerConfig,
+ IWebSocketRouteAuthorizer,
+ IWebSocketApi,
+} from '@aws-cdk/aws-apigatewayv2';
+import { ServicePrincipal } from '@aws-cdk/aws-iam';
+import { IFunction } from '@aws-cdk/aws-lambda';
+import { Stack, Names } from '@aws-cdk/core';
+
+// keep this import separate from other imports to reduce chance for merge conflicts with v2-main
+// eslint-disable-next-line no-duplicate-imports, import/order
+import { Construct as CoreConstruct } from '@aws-cdk/core';
+
+/**
+ * Properties to initialize WebSocketTokenAuthorizer.
+ */
+export interface WebSocketLambdaAuthorizerProps {
+
+ /**
+ * The name of the authorizer
+ * @default - same value as `id` passed in the constructor.
+ */
+ readonly authorizerName?: string;
+
+ /**
+ * The identity source for which authorization is requested.
+ *
+ * @default ['$request.header.Authorization']
+ */
+ readonly identitySource?: string[];
+}
+
+/**
+ * Authorize WebSocket Api routes via a lambda function
+ */
+export class WebSocketLambdaAuthorizer implements IWebSocketRouteAuthorizer {
+ private authorizer?: WebSocketAuthorizer;
+ private webSocketApi?: IWebSocketApi;
+
+ constructor(
+ private readonly id: string,
+ private readonly handler: IFunction,
+ private readonly props: WebSocketLambdaAuthorizerProps = {}) {
+ }
+
+ public bind(options: WebSocketRouteAuthorizerBindOptions): WebSocketRouteAuthorizerConfig {
+ if (this.webSocketApi && (this.webSocketApi.apiId !== options.route.webSocketApi.apiId)) {
+ throw new Error('Cannot attach the same authorizer to multiple Apis');
+ }
+
+ if (!this.authorizer) {
+ this.webSocketApi = options.route.webSocketApi;
+ this.authorizer = new WebSocketAuthorizer(options.scope, this.id, {
+ webSocketApi: options.route.webSocketApi,
+ identitySource: this.props.identitySource ?? [
+ '$request.header.Authorization',
+ ],
+ type: WebSocketAuthorizerType.LAMBDA,
+ authorizerName: this.props.authorizerName ?? this.id,
+ authorizerUri: lambdaAuthorizerArn(this.handler),
+ });
+
+ this.handler.addPermission(`${Names.nodeUniqueId(this.authorizer.node)}-Permission`, {
+ scope: options.scope as CoreConstruct,
+ principal: new ServicePrincipal('apigateway.amazonaws.com'),
+ sourceArn: Stack.of(options.route).formatArn({
+ service: 'execute-api',
+ resource: options.route.webSocketApi.apiId,
+ resourceName: `authorizers/${this.authorizer.authorizerId}`,
+ }),
+ });
+ }
+
+ return {
+ authorizerId: this.authorizer.authorizerId,
+ authorizationType: 'CUSTOM',
+ };
+ }
+}
+
+/**
+ * constructs the authorizerURIArn.
+ */
+function lambdaAuthorizerArn(handler: IFunction) {
+ return `arn:${Stack.of(handler).partition}:apigateway:${Stack.of(handler).region}:lambda:path/2015-03-31/functions/${handler.functionArn}/invocations`;
+}

packages/@aws-cdk/aws-apigatewayv2-authorizers/test/websocket/lambda.test.ts

@@ -0,0 +1,46 @@
+import { Template } from '@aws-cdk/assertions';
+import { WebSocketApi } from '@aws-cdk/aws-apigatewayv2';
+import { WebSocketLambdaIntegration } from '@aws-cdk/aws-apigatewayv2-integrations';
+import { Code, Function, Runtime } from '@aws-cdk/aws-lambda';
+import { Stack } from '@aws-cdk/core';
+import { WebSocketLambdaAuthorizer } from '../../lib';
+
+describe('WebSocketLambdaAuthorizer', () => {
+ test('default', () => {
+ // GIVEN
+ const stack = new Stack();
+
+ const handler = new Function(stack, 'auth-function', {
+ runtime: Runtime.NODEJS_12_X,
+ code: Code.fromInline('exports.handler = () => {return true}'),
+ handler: 'index.handler',
+ });
+ const integration = new WebSocketLambdaIntegration(
+ 'Integration',
+ handler,
+ );
+
+ const authorizer = new WebSocketLambdaAuthorizer('default-authorizer', handler);
+
+ // WHEN
+ new WebSocketApi(stack, 'WebSocketApi', {
+ connectRouteOptions: {
+ integration,
+ authorizer,
+ },
+ });
+
+ // THEN
+ Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Authorizer', {
+ Name: 'default-authorizer',
+ AuthorizerType: 'REQUEST',
+ IdentitySource: [
+ '$request.header.Authorization',
+ ],
+ });
+
+ Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Route', {
+ AuthorizationType: 'CUSTOM',
+ });
+ });
+});

packages/@aws-cdk/aws-apigatewayv2-integrations/test/websocket/integ.lambda.expected.json

@@ -284,6 +284,7 @@
  "Ref": "mywsapi32E6CE11"
  },
  "RouteKey": "$connect",
+ "AuthorizationType": "NONE",
  "Target": {
  "Fn::Join": [
  "",
@@ -373,6 +374,7 @@
  "Ref": "mywsapi32E6CE11"
  },
  "RouteKey": "$disconnect",
+ "AuthorizationType": "NONE",
  "Target": {
  "Fn::Join": [
  "",
@@ -462,6 +464,7 @@
  "Ref": "mywsapi32E6CE11"
  },
  "RouteKey": "$default",
+ "AuthorizationType": "NONE",
  "Target": {
  "Fn::Join": [
  "",
@@ -551,6 +554,7 @@
  "Ref": "mywsapi32E6CE11"
  },
  "RouteKey": "sendmessage",
+ "AuthorizationType": "NONE",
  "Target": {
  "Fn::Join": [
  "",

packages/@aws-cdk/aws-apigatewayv2/README.md

@@ -35,12 +35,13 @@ Higher level constructs for Websocket APIs | ![Experimental](https://img.shields
  - [Publishing HTTP APIs](#publishing-http-apis)
  - [Custom Domain](#custom-domain)
  - [Mutual TLS](#mutual-tls-mtls)
- - [Managing access](#managing-access)
+ - [Managing access to HTTP APIs](#managing-access-to-http-apis)
  - [Metrics](#metrics)
  - [VPC Link](#vpc-link)
  - [Private Integration](#private-integration)
 - [WebSocket API](#websocket-api)
  - [Manage Connections Permission](#manage-connections-permission)
+ - [Managing access to WebSocket APIs](#managing-access-to-websocket-apis)
 
 ## Introduction
 
@@ -254,7 +255,7 @@ declare const apiDemo: apigwv2.HttpApi;
 const demoDomainUrl = apiDemo.defaultStage?.domainUrl; // returns "https://example.com/demo"
 ```
 
-## Mutual TLS (mTLS)
+### Mutual TLS (mTLS)
 
 Mutual TLS can be configured to limit access to your API based by using client certificates instead of (or as an extension of) using authorization headers.
 
@@ -277,7 +278,7 @@ new DomainName(stack, 'DomainName', {
 
 Instructions for configuring your trust store can be found [here](https://aws.amazon.com/blogs/compute/introducing-mutual-tls-authentication-for-amazon-api-gateway/)
 
-### Managing access
+### Managing access to HTTP APIs
 
 API Gateway supports multiple mechanisms for [controlling and managing access to your HTTP
 API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control.html) through authorizers.
@@ -419,3 +420,9 @@ stage.grantManageConnections(lambda);
 // for all the stages permission
 webSocketApi.grantManageConnections(lambda);
 ```
+
+### Managing access to WebSocket APIs
+
+API Gateway supports multiple mechanisms for [controlling and managing access to a WebSocket API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html) through authorizers.
+
+These authorizers can be found in the [APIGatewayV2-Authorizers](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-apigatewayv2-authorizers-readme.html) constructs library.

packages/@aws-cdk/aws-apigatewayv2/lib/http/authorizer.ts

@@ -166,7 +166,7 @@ export class HttpAuthorizer extends Resource implements IHttpAuthorizer {
  }
 
  /**
- * This check is required because Cloudformation will fail stack creation is this property
+ * This check is required because Cloudformation will fail stack creation if this property
  * is set for the JWT authorizer. AuthorizerPayloadFormatVersion can only be set for REQUEST authorizer
  */
  if (props.type === HttpAuthorizerType.LAMBDA && typeof authorizerPayloadFormatVersion === 'undefined') {