SwaggerJS/API Explorer using AWS Sigv4 authentication on Amazon API Gateway.

The AWS Lambda+API Gateway serverless stack has become immensely popular in the past couple of years. It is very easy to get started building APIs at a very low cost that will scale with you and your business(or remain free for your toy project). That said, I have found that many developers building on the AWS serverless stack have a difficult time understanding their authentication/authorization options, let alone picking the right option for them and understanding all the tooling involved.

While not the most flexible option available, the easiest authentication method to start with for API Gateway is ‘AWS_IAM’. With this option, API access is gated by IAM policy and can take advantage of AWS Sigv4 features like pre-signing. This is the best option if these APIs are accessed from your own compute nodes that already have IAM roles available to them(e.g. your code on EC2 or Lambda) or from end user-facing applications using Cognito Identity Pools.

A ‘problem’ with this approach is that AWS Sigv4 is pretty complicated. API Gateway will generate SDKs for you in a number of popular languages but…they kind of suck and now you have a bunch more dependencies to manage during build and run-time. So..what if you could just ‘steal’ the signing logic from the AWS SDKs you probably already use in your application?

Another very interesting aspect about API Gateway is it’s Swagger support. Even if you don’t build your API in Swagger, you can still export a Swagger definition from API Gateway.

Putting these ideas together, I built a simple Client Authorization implementation for SwaggerJS that is a simple adapter..pulling the signing code from the AWS JS SDK and signing ‘sigv4’ requests for SwaggerJS.

I went one step further and, with a few changes to the demo page for SwaggerUI(A handy API Explorer), built a simple live API Gateway API Explorer(source). Just enter your API Gateway region, API Id, Stage Name, and access/secret key and start exploring your API as currently deployed.

(Don’t worry, I promise I’m not stealing your credentials. This is entirely in the browser).

This example pulls together the AWS JS SDK, SwaggerJS, Swagger UI, and less than 100 lines of new code to provide a powerful demonstration of leveraging existing technologies to secure your severless APIs while not reinventing any wheels. You can most likely extend this technique to other platforms that AWS supports but API Gateway does not yet generate an SDK for.

Are you using Swagger clients for your serverless APIs? Do you want to learn more about serverless and serverless security? Let me know in the comments.