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.

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 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 and configure the installation by running Curity Basic Setup Wizard as outlined in this tutorial Curity Basic Setup Wizard.

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 and there are full instructions on how to deploy the plugin: AWS Split Token Publisher Event Listener

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.

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:

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

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

   

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

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)
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.
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

Test using OAuth Tools

1. In OAuth Tools, 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.

Resources

Useful resources that covers the topics of this article.

• The Curity Identity Server plugins documentation
• The Curity Java SDK documentation
• An article on the Split Token Approach.
• The code for the Curity Event Listener plugin: aws-token-publisher
• AWS Lambda Authorizers
• AWS Lambda with DynamoDB
• AWS API Gateway