---
title: "Integrating the Curity Identity Server with AWS API Gateway using the Split Token approach"
description: "How to configure the Curity Identity Server, DynamoDB, an AWS Lambda Authorizer to use the Split Token approach with the AWS API Gateway"
url: "https://curity.io/resources/learn/integration-aws-split-token/"
date: "2020-07-13"
area: "tutorials"
topic: "howtos"
pagegroup: "split-token-integration"
repository: "https://github.com/curityio/aws-token-publisher"
---

# Integrating the Curity Identity Server with AWS API Gateway using the Split Token approach

## Overview

The AWS API Gateway is very powerful and have lots of possibilities for extensions. One such extension is the ability to create a custom [Lambda Authorizer](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html).

This how-to will cover how to configure the Curity Identity Server to send a partial token or a split token to a configured instance of AWS DynamoDB. Setting up a Lambda Authorizer that the AWS API Gateway can leverage to authorize the incoming API call and pass on a JWT to the upstream API.

The details of the [Split Token approach](https://curity.io/resources/learn/split-token-pattern/) 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 as it related to the API Gateway, DynamoDB and Lambda functions.

If you do not have an installation of the Curity Identity Server, follow this tutorial [installation of the Curity Identity Server](https://curity.io/resources/learn/run-curity-docker/) and configure the installation by running Curity Basic Setup Wizard as outlined in this tutorial [Curity Basic Setup Wizard](https://curity.io/resources/learn/first-config/).

## Configure the AWS Token Publisher

The Curity Identity Server has the capability to configure event listeners. These are plugins that will trigger when a specific event occurs in the system. For the purpose of integrating with the AWS API Gateway there is a specific AWS token publisher plugin. The plugin can be obtained from [Curity's GitHub repo](https://github.com/curityio/aws-token-publisher) and there are full instructions on how to deploy the plugin: [AWS Split Token Publisher Event Listener](https://curity.io/resources/learn/aws-token-publisher/)

The AWS Token Publisher will detect when a token is issued. In order to integrate with AWS API Gateway the Curity Identity Server needs to send the hashed signature part of the issued token along with the header and body to an instance of DynamoDB. This information will later be read by the Lambda Authorizer invoked by the AWS API Gateway.

## Configure the split token procedure

In addition to the Curity Identity Server sending the token information to the DynamoBD instance when a token is issued the way the tokens are issued also needs to be modified. This can be achieved by modifying the procedure that runs when the Curity Identity Server executed the procedure for **Authorization Code**.

![Configure token procedure](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/configure-token-procedure.png)

1.  Go to Profiles > Token Service > Endpoints, find the endpoint with the type oauth-token and click the select box in the Flows column.
2.  Next find the "Authorization Code" procedure and click the select box next to it. Enter a name for your procedure and click save.
3.  A popup will appear where you can type the procedure code. Replace the code in the popup with the following one:

```javascript
function result(context) {
    var delegationData = context.getDefaultDelegationData();
    var issuedDelegation = context.delegationIssuer.issue(delegationData);

    var accessTokenData = context.getDefaultAccessTokenData();
    var issuedAccessToken = context.getDefaultAccessTokenJwtIssuer().issue(accessTokenData, issuedDelegation);

    var token = issuedAccessToken.split('.')[2];

    var refreshTokenData = context.getDefaultRefreshTokenData();
    var issuedRefreshToken = context.refreshTokenIssuer.issue(refreshTokenData, issuedDelegation);

    var responseData = {
        access_token: token,
        scope : accessTokenData.scope,
        refresh_token: issuedRefreshToken,
        token_type: 'bearer',
        expires_in: secondsUntil(accessTokenData.exp)
    };

    if (context.scopeNames.contains('openid')) {
        var idTokenData = context.getDefaultIdTokenData();

        var idTokenIssuer = context.idTokenIssuer;
        idTokenData.at_hash = idTokenIssuer.atHash(issuedAccessToken);

        responseData.id_token = idTokenIssuer.issue(idTokenData, issuedDelegation);
    }

    return responseData;
}
```

4.  Click the Update button to save changes in the procedure. You can then close the popup. Save and Commit changes to the server.

## Configure DynamoDB

1.  Got to AWS Management Console
2.  Search for the DynamoDB service
3.  Click `Create table`
4.  Name the table, ex `split-token`
5.  Enter a **Primary key**, ex. `hashed_signature`. Make sure the data type is set to **String**
6.  Click **Create**

![Create DynamoDB Table](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/dynamodb-create-table.png)

### Configure the lambda-authorizer

1.  In the AWS Management Console, go to **Lambda**
    
2.  Choose **Create function** and then **Author from scratch**
    
3.  Give the function a name, ex. `curity-split-token-authorizer`
    
4.  Choose the **Node.js 16.x** runtime (or newer)
    
5.  Click **Create function**
    
    ![Create Lambda Authorizer](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/create-lambda-authorizer.png)
6.  In the default **index.js**, replace all the code with the following code:
    

7.  In the **Environment variables** section, click **Edit**
8.  Click **Add environment variable**
9.  Add, **Key** `TABLE_NAME` with the Value configured in DynamoDB, ex. `split-token`
10.  Add, **Key** `KEY_NAME` with the Value configured in DynamoDB, ex. `hashed_signature`
11.  Click **Save**

![Lambda Environment Variables](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/lambda-env-var.png)

## Configure AWS API GW

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

### Create & configure the Authorizer

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-split-token-authorizer` should be available in the text field
6.  In the **Lambda Event Payload** section choose **Request**
7.  For **Identity Sources** choose **Header** and 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) ![Lambda Environment Variables](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/create-api-authorizer.png)
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`. **NOTE:** The drop-down list is populated when the API method is created. If the Authorizer does not show up, delete the method and re-create it and the Authorizer should show up.
5.  In the HTTP Request Headers section, click **Add header** and enter `Authorization` then click the grey checkbox to the right. ![Configure Method Request](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/configure-method-request.png)
6.  Go back to **Method Execution**
7.  Click **Integration Request**
8.  Set the **Integration type** to `HTTP`
9.  In the HTTP Headers section, click **Add header**, for **Name** enter `Authorization` and for **Mapped from** enter `method.request.header.Authorization` Expand **Mapping Templates**
10.  Choose `When there are no templates defined (recommended)`
11.  Click **Add mapping template**
12.  Under Content-Type, enter `application/json` and click the checkbox
13.  In the template editor, on line 1, enter `#set($context.requestOverride.header.Authorization = $context.authorizer.token)`
14.  Click **Save** ![Configure Method Request](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/integration-request.png)

## Test using OAuth Tools

1.  In [OAuth Tools](https://oauth.tools/?utm_source=curity.io&utm_medium=Link&utm_content={props.utmContent}), create a flow, for example the code flow. The Access token created should now be the signature part of the split-token and will be much longer than a traditional access token provided.
2.  Now 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 flow from the drop down list. Add a header with the name `Content-Type` and the value `application/json` and click Send.

![OAuth Tools](https://curity.io/images/resources/operate/tutorials/integration/aws-api-gw/oauth-tools.png)

## Resources

Useful resources that covers the topics of this article.

-   [The Curity Identity Server plugins documentation](https://curity.io/docs/identity-server/developer-guide/plugins/)
-   [The Curity Java SDK documentation](https://curity.io/docs/idsvr-java-plugin-sdk/latest/)
-   An article on the [Split Token Approach](https://curity.io/resources/learn/split-token-pattern/).
-   The code for the Curity Event Listener plugin: [aws-token-publisher](https://github.com/curityio/aws-token-publisher)
-   [AWS Lambda Authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)
-   [AWS Lambda with DynamoDB](https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html)
-   [AWS API Gateway](https://aws.amazon.com/api-gateway/)
