Integrating the Curity Identity Server with AWS API Gateway using the Phantom Token Pattern

The AWS API Gateway is very capable and can also be extended to leverage Lambda functions. More specifically custom Lambda Authorizers can be configured in order to protect configured APIs.

This article describes how to deploy and configure a custom Lambda Authorizer and how to configure an API to make use of that custom Lambda Authorizer to achieve the Phantom Token Pattern.

The details of the OAuth Introspection and Phantom Tokens is a useful read before diving fully into how to set up this integration.

Prerequisites

• An installation of the Curity Identity Server
• Basic understanding of the AWS ecosystem and especially the API Gateway and Lambda functions.

If you do not have an installation of the Curity Identity Server, follow this tutorial installation of the Curity Identity Server and configure the installation by running Curity Basic Setup Wizard as outlined in this tutorial Curity Basic Setup Wizard.

Configure the Curity Identity Server

The Curity Identity Server needs to be set up to handle introspection. This is the case by default but review the configuration of the system in use before continuing. This article assumes that the Curity Identity Server is set up to handle the application/jwt approach of introspection as outlined in the OAuth Introspection and Phantom Tokens article.

Build, Deploy and Configure the Lambda Authorizer Function

The code for the Curity AWS Phantom Token Lambda Authorizer function is available in the GitHub repository. Full details on building, deploying and configuring the Lambda Authorizer function itself is outlined in the readme.

Create & Configure the Authorizer

With the Lambda Authorizer function configured an Authorizer to be used by the AWS API Gateway can be configured.

In the AWS Management Console, go to API Gateway, choose the API to protect or create a new API.

1. Select Authorizers.
2. Click Create New Authorizer
3. Give it a name, ex. curity-authorizer
4. Make sure the type is set to Lambda
5. Under the Lambda Function section, make sure the correct Zone is selected, the previously configured Lambda Authorizer with the name curity-phantom-token-authorizer should be available in the text field
6. In the Lambda Event Payload section choose Token
7. For the Token Source, enter Authorization in the field
8. If Authorization Caching is left enabled the API Gateway will not invoke the Lambda function if the same Authorization header is used within the time span of the cache configuration (300 seconds by default)
9. Click Create
10. Then click Grant & Create

Configure API

1. For the API to protect, go to Resources
2. Select the Resource and the Method to protect
3. Click Method Request
4. Under Settings -> Authorization, choose the previously created Authorizer, curity-authorizer.

   Authorizer not available?

   The drop-down list is populated when the API method is created. If the Authorizer does not show up, delete the method, re-create it and the Authorizer should show up.
   
5. Go back to Method Execution
6. Click Integration Request
7. Set the Integration type to HTTP
8. In the HTTP Headers section, click Add header, for Name enter Authorization and for Mapped from enter context.authorizer.Authorization. Save and enable Caching as needed. This will pass the JWT from the introspection response in the upstream API Authorization header so that the API can consume the JWT.

Policy Document Paths

The Curity AWS Phantom Token Lambda Authorizer is by default coded to generate wildcard IAM policies to be able to handle multiple API paths. This handles an issue that is outlined in the Serverless Forum forum.

On row 62 in index.js, the getServiceArn method is called. This will strip the specific path and add a wildcard instead allowing the IAM policy to be applied to other methods and paths of the API. If this behavior is not desired, comment out row 62 and uncomment row 63.

Test Using OAuth Tools

1. In OAuth Tools, create a flow to obtain an Access Token.
2. Create a Call External API flow. Enter the URL for the AWS API Gateway exposed API. Configure the method according to what’s possible with the API. Select the token retrieved in the previous step from the drop-down list and click Send.

Resources

Useful resources that cover the topics of this article.

• An article on OAuth Introspection and Phantom Tokens
• AWS Lambda Authorizers
• AWS API Gateway