OIDC Integration with HTTP APIs for API Gateway

In my previous post I wrote up how to secure API Gateway using Lambda custom authorizers, Okta and Serverless Framework. Since then, AWS has released (in preview beta) HTTP API’s for API Gateway. This new API type has built-in support for OIDC integration, making the process of securing API Gateway with OIDC providers much easier.

Here are 6 quick steps to set this up.

Create an OIDC secured HTTP API

Step 1: Select the API type
Chose the HTTP API type to build

Step 2: Configure the API integrations
Select Integration type HTTP, an Integration target (which is an HTTP method, this example uses GET), and supply the Integration URL to be secured.

Step 3: Configure the routes
Route configuration provides the ability to add multiple routes to different paths for various HTTP request methods. This example adds a single route for GET requests on the root path.

Step 4: Create a stage
Just as with REST API’s, it is required to deploy to a stage.

Step 5: Review and create the new API
Perform a quick review and create the new HTTP API.

With the HTTP API created and the Invoke URL available, it can now be secured with OIDC.

Step 6: Create OIDC Authorizer
From the left side menu bar, select Authorization. This will display the available routes and an option to add a new OIDC authorizer.

Select the Create and attach authorizer button.

The authorizer requires a name and Identity source (where API Gateway should look for the JWT), in this example, API Gateway will look in the Authorization header. This is configured with the following syntax:

$request.header.Authorization

Also required, is the Issuer URL (the URL of the OIDC provider) and the required Audience values for the OIDC app. For example, using Okta we would provide the Okta app Client ID and the audience from the Okta API Authorization server.

With all the values entered, Create and attach.

If required, additional Oauth 2.0 scopes can be added to the Authorizer.

This screen can be accessed from the Authorization menu option on the left side nav and selecting the route

Note: Although not documented or configurable yet, the OIDC fetched JSON Web Key Set (JWKS) is cached by API Gateway for some default amount of time.

Testing out the secured API

A quick curl to access the new API without a JWT in the Authorization header will return an HTTP 401 Unauthorized with a message, as expected.

curl https://ewwwpjn8l2.execute-api.us-west-2.amazonaws.com/dev -v
HTTP/2 401
{"message": “Unauthorized”}

Adding the Authorization header with JWT should return a HTTP 200 OK with the response payload of the endpoint.

curl -H “Authorization: <JWT >” https://ewwwpjn8l2.execute-api.us-west-2.amazonaws.com/dev -v

Support for HTTP APIs

Currently, the new HTTP API’s can be created with the AWS CLI, CloudFormation, AWS SDK, and Serverless Application Model (SAM). Expect to see support landing soon in Serverless Framework as well.

What’s missing from HTTP API’s?

AWS has told us that the new HTTP API’s are lower in latency and have up to a 70% cost reduction for usage. This is great!

Keep in mind that the new HTTP API’s are missing some of the features that are part of the standard REST APIs. Options such as caching, throttling and usage plans, to name a few, are currently not available with HTTP APIs. Here’s a full feature comparison of HTTP API’s and REST API’s.

However, if your application does not require any of the advanced features of API Gateway REST API’s, the HTTP API’s are a really nice way to to go.

It is worth mentioning again, HTTP API’s are still in beta preview as of this writing, so I’d expect things to change in the coming months.