Navigate back to the homepage
📚 Books

Writing Custom Authorizers for AWS API Gateway

Mark Pollmann
January 27th, 2018 · 4 min read

If you want to go serverless with your web app and you need an API running Lambda functions behind API Gateway on AWS is an excellent choice. The technology is mature, fast and cheap (if you know what you’re doing). You even get the first 1 million invocations for free each month. Once it’s set up you don’t have to provision servers and worry about over- or underprovisioning; you just pay per API call.

Getting everything correctly configured is no small feat, though.

What are Custom Authorizers?

You probably don’t want everyone to be able to call your REST-endpoint that fetches personal data from the database, the caller has to be authenticated. You could write this logic in the same Lambda function that handles the request but that could get messy very fast. Also you would have to duplicate this code for every endpoint and we don’t want to repeat ourselves.

There are two types of Custom Authorizers, token-based and request-based. They differ in the way they grant the caller permission to use the resource, either they get a token back or

High-level Overview

The AWS docs provide this useful overview of the dataflow:

Custom Authorizer Workflow

A simplistic round of steps

  1. Client sends a request to your API
  2. API Gateway extracts the token from the request and calls your custom authorizer with it
  3. Custom authorizer evaluates the token, generates a policy and sends it back to API Gateway.
  4. API Gateway evaluates the policy and calls your real lambda function that is registered for the API endpoint.


For our example we need three things:

  1. A lambda function that gets triggered when somebody calls our API Gateway endpoint.
  2. The actual API Gateway endpoint.
  3. A lambda function that serves as our custom authorizer.

Let’s get started.

The Lambda Function

Let’s log into AWS and create a new lambda function from scratch:

Custom Authorizer

We give it just a basic execution role (to be able to write to CloudWatch) and use Node 6.10 as the runtime (still waiting for Node 8 and async/await).

We leave the code as is:

Custom Authorizer

The API Gateway Endpoint

Now we go to API Gateway and set up a new API:

New API Gateway API

In the next window, under actions we create a new resource under /test and enable CORS so we don’t run into trouble by calling the API from our own machine:

New Resource

After creating the resource we create a GET method (again under Actions) select Lambda integration type with Lambda proxy integration and select our lambda function we created in step one (remember the region you created the lambda function in):

Setup get endpoint

Give API Gateway permission to execute your function in the next window and we’re good to go.

Deploying the API

Again under Actions, we select deploy API, create a new stage and call it dev:

Deploy the API

Now we have a deployed API. If you open all tabs until the GET endpoint you should find your exact url:

Deploy the API

Let’s try calling our (totally unauthenticated) endpoint with cURL:

Deploy the API

It works! Now let’s go about authenticating it:

The Custom Authenticator

We create a new lambda function as seen in step 1:

Deploy the API

We leave the code as is for now.

The idea is that our function will:

  1. Get the token passed to it on the event object
  2. It does its authentication thing (validating the token)
  3. And then returns a policy document to API Gateway to explain if and what the caller is allowed to do.

To do step 1 we go back to API Gateway, select our API, then Authorizers and Create Authorizer

Deploy the API

Here we can specify from which header API Gateway will extract the token and pass it to our authorizer. Usually the header should be called authorization or something like it but just to show you that you can use whatever you want we call it bananaHeader. Click create and go back to your GET /test method. Click on method request and under Authorization select your new authorizer:

Deploy the API

Click the little checkmark and under Actions deploy the API again to stage dev.

Now when we call our /test endpoint our authenticator lambda function will run first. As of right now it just returns “Hello from lambda” which will of course authenticate nothing. Let’s try calling the endpoint:

Deploy the API

As expected, we’re not getting through to our real endpoint. Let’s write the custom authentication:

The Custom Authentication Code

In a real API your authentication code can get quite complex, calling services like Auth0 to see if the token is valid and not yet expired but let’s keep it simple. The AWS docs have a great example for this. The token is a string and can either be ‘allow’, ‘deny’, ‘unauthorized’ or something else. Depending on which is the case they generate the corresponding policy document to tell API Gateway what the user is allowed to do.

Here’s the code:

1// A simple TOKEN authorizer example to demonstrate how to use an authorization token
2// to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
3// a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
4// the request if the token value is 'deny'. If the token value is 'Unauthorized', the function
5// returns the 'Unauthorized' error with an HTTP status code of 401. For any other token value,
6// the authorizer returns an 'Invalid token' error.
8exports.handler = function(event, context, callback) {
9 var token = event.authorizationToken
10 switch (token.toLowerCase()) {
11 case "allow":
12 callback(null, generatePolicy("user", "Allow", event.methodArn))
13 break
14 case "deny":
15 callback(null, generatePolicy("user", "Deny", event.methodArn))
16 break
17 case "unauthorized":
18 callback("Unauthorized") // Return a 401 Unauthorized response
19 break
20 default:
21 callback("Error: Invalid token")
22 }
25// Help function to generate an IAM policy
26var generatePolicy = function(principalId, effect, resource) {
27 var authResponse = {}
29 authResponse.principalId = principalId
30 if (effect && resource) {
31 var policyDocument = {}
32 policyDocument.Version = "2012-10-17"
33 policyDocument.Statement = []
34 var statementOne = {}
35 statementOne.Action = "execute-api:Invoke"
36 statementOne.Effect = effect
37 statementOne.Resource = resource
38 policyDocument.Statement[0] = statementOne
39 authResponse.policyDocument = policyDocument
40 }
42 // Optional output with custom properties of the String, Number or Boolean type.
43 authResponse.context = {
44 stringKey: "stringval",
45 numberKey: 123,
46 booleanKey: true,
47 }
48 return authResponse

Let’s use it in our lambda function and click save:

Deploy the API

The Finish

This should be it!

If we call our API and provide a header called bananaHeader with value “allow” we should get back our hello from lambda.

Let’s try it:

Deploy the API

Looks good!


Authenticating endpoints in AWS can be quite a lot of configuration but once it’s set up it’s a cheap and easy way to get it done. If your method of authentication changes, because you switch providers for example, just update your lambda code and you’re good to go.

Thanks for reading!

More articles from Mark Pollmann

Notes on Jan Koum's talk at Stanford

An interesting talk about WhatsApp's beginnings

August 20th, 2017 · 1 min read

Using NodeJS with TypeScript in 2020

Note: This article is aimed at Node developers looking into TypeScript and is planned as a living document. When I find something noteworthy…

May 15th, 2020 · 4 min read
© 2017–2020 Mark Pollmann
Link to $ to $ to $