Interface Summary
Interface	Description
HttpJwtAuthorizerProps	(experimental) Properties to initialize HttpJwtAuthorizer.
HttpLambdaAuthorizerProps	(experimental) Properties to initialize HttpTokenAuthorizer.
HttpUserPoolAuthorizerProps	(experimental) Properties to initialize HttpUserPoolAuthorizer.
WebSocketLambdaAuthorizerProps	(experimental) Properties to initialize WebSocketTokenAuthorizer.

Class Summary
Class	Description
HttpIamAuthorizer	(experimental) Authorize HTTP API Routes with IAM.
HttpJwtAuthorizer	(experimental) Authorize Http Api routes on whether the requester is registered as part of an AWS Cognito user pool.
HttpJwtAuthorizer.Builder	(experimental) A fluent builder for `HttpJwtAuthorizer`.
HttpJwtAuthorizerProps.Builder	A builder for `HttpJwtAuthorizerProps`
HttpJwtAuthorizerProps.Jsii$Proxy	An implementation for `HttpJwtAuthorizerProps`
HttpLambdaAuthorizer	(experimental) Authorize Http Api routes via a lambda function.
HttpLambdaAuthorizer.Builder	(experimental) A fluent builder for `HttpLambdaAuthorizer`.
HttpLambdaAuthorizerProps.Builder	A builder for `HttpLambdaAuthorizerProps`
HttpLambdaAuthorizerProps.Jsii$Proxy	An implementation for `HttpLambdaAuthorizerProps`
HttpUserPoolAuthorizer	(experimental) Authorize Http Api routes on whether the requester is registered as part of an AWS Cognito user pool.
HttpUserPoolAuthorizer.Builder	(experimental) A fluent builder for `HttpUserPoolAuthorizer`.
HttpUserPoolAuthorizerProps.Builder	A builder for `HttpUserPoolAuthorizerProps`
HttpUserPoolAuthorizerProps.Jsii$Proxy	An implementation for `HttpUserPoolAuthorizerProps`
WebSocketLambdaAuthorizer	(experimental) Authorize WebSocket Api routes via a lambda function.
WebSocketLambdaAuthorizer.Builder	(experimental) A fluent builder for `WebSocketLambdaAuthorizer`.
WebSocketLambdaAuthorizerProps.Builder	A builder for `WebSocketLambdaAuthorizerProps`
WebSocketLambdaAuthorizerProps.Jsii$Proxy	An implementation for `WebSocketLambdaAuthorizerProps`

Enum Summary
Enum Description

HttpLambdaResponseType
(experimental) Specifies the type responses the lambda returns.

Enum Summary
Enum	Description
HttpLambdaResponseType	(experimental) Specifies the type responses the lambda returns.

Package software.amazon.awscdk.services.apigatewayv2.authorizers Description

AWS APIGatewayv2 Authorizers

Introduction
HTTP APIs
WebSocket APIs
- Lambda Authorizer

Introduction

API Gateway supports multiple mechanisms for controlling and managing access to your HTTP API. They are mainly classified into Lambda Authorizers, JWT authorizers and standard AWS IAM roles and policies. More information is available at Controlling and managing access to an HTTP API.

HTTP APIs

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.

Default Authorization

When using default authorization, all routes of the api will inherit the configuration.

In the example below, all routes will require the manage:books scope present in order to invoke the integration.

 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpJwtAuthorizer;
 
 
 String issuer = "https://test.us.auth0.com";
 HttpJwtAuthorizer authorizer = HttpJwtAuthorizer.Builder.create("DefaultAuthorizer", issuer)
         .jwtAudience(List.of("3131231"))
         .build();
 
 HttpApi api = HttpApi.Builder.create(this, "HttpApi")
         .defaultAuthorizer(authorizer)
         .defaultAuthorizationScopes(List.of("manage:books"))
         .build();

Route Authorization

Authorization can also configured for each Route. When a route authorization is configured, it takes precedence over default authorization.

The example below showcases default authorization, along with route authorization. It also shows how to remove authorization entirely for a route.

GET /books and GET /books/{id} use the default authorizer settings on the api
POST /books will require the [write:books] scope
POST /login removes the default authorizer (unauthenticated route)

 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpJwtAuthorizer;
 import software.amazon.awscdk.services.apigatewayv2.integrations.HttpUrlIntegration;
 
 
 String issuer = "https://test.us.auth0.com";
 HttpJwtAuthorizer authorizer = HttpJwtAuthorizer.Builder.create("DefaultAuthorizer", issuer)
         .jwtAudience(List.of("3131231"))
         .build();
 
 HttpApi api = HttpApi.Builder.create(this, "HttpApi")
         .defaultAuthorizer(authorizer)
         .defaultAuthorizationScopes(List.of("read:books"))
         .build();
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books")
         .methods(List.of(HttpMethod.GET))
         .build());
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIdIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books/{id}")
         .methods(List.of(HttpMethod.GET))
         .build());
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books")
         .methods(List.of(HttpMethod.POST))
         .authorizationScopes(List.of("write:books"))
         .build());
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("LoginIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/login")
         .methods(List.of(HttpMethod.POST))
         .authorizer(new HttpNoneAuthorizer())
         .build());

JWT Authorizers

JWT authorizers allow the use of JSON Web Tokens (JWTs) as part of OpenID Connect and OAuth 2.0 frameworks to allow and restrict clients from accessing HTTP APIs.

When configured, API Gateway validates the JWT submitted by the client, and allows or denies access based on its content.

The location of the token is defined by the identitySource which defaults to the http Authorization header. However it also supports a number of other options. It then decodes the JWT and validates the signature and claims, against the options defined in the authorizer and route (scopes). For more information check the JWT Authorizer documentation.

Clients that fail authorization are presented with either 2 responses:

401 - Unauthorized - When the JWT validation fails
403 - Forbidden - When the JWT validation is successful but the required scopes are not met

 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpJwtAuthorizer;
 import software.amazon.awscdk.services.apigatewayv2.integrations.HttpUrlIntegration;
 
 
 String issuer = "https://test.us.auth0.com";
 HttpJwtAuthorizer authorizer = HttpJwtAuthorizer.Builder.create("BooksAuthorizer", issuer)
         .jwtAudience(List.of("3131231"))
         .build();
 
 HttpApi api = new HttpApi(this, "HttpApi");
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books")
         .authorizer(authorizer)
         .build());

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.

Clients accessing an API that uses a user pool authorizer must first sign in to a user pool and obtain an identity or access token. They must then use this token in the specified identitySource for the API call. More information is available at using Amazon Cognito user pools as authorizer.

 import software.amazon.awscdk.core.*;
 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpUserPoolAuthorizer;
 import software.amazon.awscdk.services.apigatewayv2.integrations.HttpUrlIntegration;
 
 
 UserPool userPool = new UserPool(this, "UserPool");
 
 HttpUserPoolAuthorizer authorizer = new HttpUserPoolAuthorizer("BooksAuthorizer", userPool);
 
 HttpApi api = new HttpApi(this, "HttpApi");
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books")
         .authorizer(authorizer)
         .build());

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.

Lambda authorizers depending on their response, fall into either two types - Simple or IAM. You can learn about differences here.

 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpLambdaAuthorizer;
 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpLambdaResponseType;
 import software.amazon.awscdk.services.apigatewayv2.integrations.HttpUrlIntegration;
 
 // This function handles your auth logic
 Function authHandler;
 
 
 HttpLambdaAuthorizer authorizer = HttpLambdaAuthorizer.Builder.create("BooksAuthorizer", authHandler)
         .responseTypes(List.of(HttpLambdaResponseType.SIMPLE))
         .build();
 
 HttpApi api = new HttpApi(this, "HttpApi");
 
 api.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books")
         .authorizer(authorizer)
         .build());

IAM Authorizers

API Gateway supports IAM via the included HttpIamAuthorizer and grant syntax:

 import software.amazon.awscdk.services.apigatewayv2.authorizers.HttpIamAuthorizer;
 import software.amazon.awscdk.services.apigatewayv2.integrations.HttpUrlIntegration;
 
 AnyPrincipal principal;
 
 
 HttpIamAuthorizer authorizer = new HttpIamAuthorizer();
 
 HttpApi httpApi = HttpApi.Builder.create(this, "HttpApi")
         .defaultAuthorizer(authorizer)
         .build();
 
 HttpRoute[] routes = httpApi.addRoutes(AddRoutesOptions.builder()
         .integration(new HttpUrlIntegration("BooksIntegration", "https://get-books-proxy.myproxy.internal"))
         .path("/books/{book}")
         .build());
 
 routes[0].grantInvoke(principal);

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.

 import software.amazon.awscdk.services.apigatewayv2.authorizers.WebSocketLambdaAuthorizer;
 import software.amazon.awscdk.services.apigatewayv2.integrations.WebSocketLambdaIntegration;
 
 // This function handles your auth logic
 Function authHandler;
 
 // This function handles your WebSocket requests
 Function handler;
 
 
 WebSocketLambdaAuthorizer authorizer = new WebSocketLambdaAuthorizer("Authorizer", authHandler);
 
 WebSocketLambdaIntegration integration = new WebSocketLambdaIntegration("Integration", handler);
 
 WebSocketApi.Builder.create(this, "WebSocketApi")
         .connectRouteOptions(WebSocketRouteOptions.builder()
                 .integration(integration)
                 .authorizer(authorizer)
                 .build())
         .build();

Package software.amazon.awscdk.services.apigatewayv2.authorizers