Secure APIs Hosted in Amazon Gateway With Asgardeo

Introduction

Amazon API Gateway is a service offered by AWS that enables users to create, publish, and maintain secure APIs on any scale. It supports both RESTful APIs and WebSocket APIs. However, It's crucial to secure these APIs before allowing applications to access them. The use of OAuth2 tokens and JWTs is the standard method of securing APIs.

This tutorial will guide you through the process of enabling controlled access to AWS-hosted RESTful APIs using Asgardeo as the Customer IAM(CIAM) provider. AWS supports different types of authorizers such as AWS Identity and Access Management (IAM) authorizers, AWS Lambda authorizers, and JWT authorizers. Asgardeo uses the JWT authorizers and issues JWT access tokens to enable authorized access to AWS-hosted APIs.

Consider a scenario where an application requires access to a secured API hosted on AWS. The two flows involved in the process are explained below.

Flow 1: Application gets a JWT access token

• The application requests a JWT from Asgardeo by providing the required credentials (client ID, client secret).
• Asgardeo sends a valid JWT to the application.

Flow 2: Application accesses the secured API hosted on AWS

• The application calls the API gateway with the JWT issued by Asgardeo.
• The API gateway calls the JWT authorizer to validate the token.
• The JWT authorizer calls Asgardeo and validates the token.
• The JWT authorizer sends back the validity of the given JWT.
• API gateway grants access (if the token is valid) to the application to access the secured API.
• The application receives the response after the requested operation is completed by the Lambda function connected to the API. 

This tutorial will guide you on:

1. How to deploy a RESTful API connected to a Lambda function in Amazon API Gateway.
2. How to secure the created API with Asgardeo and JWT authorizers. 

Step 1: Deploy an HTTP API in Amazon API Gateway

Amazon API Gateway supports both REST and HTTP APIs. HTTP APIs are optimized for performance and are more affordable compared to REST APIs. They can be used to send requests to AWS Lambda functions or any routable HTTP endpoint, making them ideal for serverless workloads. 

Follow the steps below to deploy an HTTP API connected to Lambda function in the Amazon API Gateway: 

1. Create a Lambda function in Amazon API Gateway.

See the instructions on Getting started with Lambda Guide.

For this tutorial, we will be using the getting-started-with-lambda-http blueprint, and the following code snippet will implement the Lambda function. 

	
    exports.handler = async (event) => {
            const response = {
                statusCode: 200,
                body: event.body,
            };
            return response;
        };
    

The function simply returns a response, including the request body as the response.

2. Add a public endpoint to the Lambda function through the API gateway trigger.

See the instructions on Adding an endpoint to your Lambda function Guide.

3. Test access to the public API endpoint.
   
   

Using Postman:





Using cURL

• cURL request:

    
curl --location --request POST '< API endpoint URL >' \
--header 'Content-Type: text/plain' \
--data-raw 'Hello World'
            
  
    

• Example cURL request:
  
  

    
curl --location --request POST 'https://sntfx54bil.execute-api.ap-northeast-1.amazonaws.com/default/demo_lambda_function' \
--header 'Content-Type: text/plain' \
--data-raw 'Hello World'

Note that the HTTP API created can be accessed by anyone with access to the access endpoint details. Therefore, it is essential to securing this API to ensure it’s accessible only with the required permissions. In the following sections, we will see how Asgardeo can be configured to cater to that requirement. Eventually, we will restrict our API only to those who have a valid JWT issued by Asgardeo.

Step 2: Configure Asgardeo application to generate JWT

To access a secured API, a valid JWT issued by Asgardeo is required. Follow these steps below to configure a standard-based application that supports OAuth2.0/OpenID Connect protocols to retrieve an access token: 

1. Sign in to the Asgardeo Console.
2. Go to Develop > Applications and click New Application.



3. On the Register New Application page, select Standard-Based Application.



4. Give a name for the application (e.g. demo_aws_application), select OAuth2.0 OpenID Connect as the Protocol, and click on Register.
   
5. Go to the Protocol tab and specify the following values:
• Select the Client Credential grant type in the Allowed grant types section.
• Select JWT token type in the Access Token section.

6. Specify the  Audience (eg: demo_aws_app_audience)in the  ID Token section and click on Update.

Step 3: Add JWT authenticator to the API Gateway

To secure the API, a JWT authenticator must be added to the API created in AWS. Follow these steps to add a JWT authenticator:

1. Click the API gateway name (e.g.: demo_lambda_function-API) under Triggers. 
2. When redirected to the API gateway details page, go to Develop > Routes.
3. Select the routes that need to be secured and click Attach Authorization.
   
4. Click on Create and attach an authorizer. You can also select an existing authorizer.
   
5. Enter the details of the authorizer as follows:
   

   Authorizer type:	Select JWT as the method of controlling access to the API.
   Name:	Name of the authorizer. (e.g. demo_aws_jwt_authorizer).
   Audience:	This should be the same audience added when creating the application in Asgardeo (e.g. demo_aws_app_audience).
   Issuer URL:	Get the value for the issuer URL from the Info tab of the application created in Asgardeo.

   



6. Create the authorizer by clicking on Create and attach.

Step 4: Access the secure API

After successfully securing the API in AWS by adding a JWT authorizer, we’ll attempt to access the API. 

Access the API without a token

First, we’ll attempt to access the API without using an access token.

Using Postman:

Using cURL: 

• cURL request
  

    
curl --location --request POST ' < API endpoint URL >' \
--header 'Content-Type: text/plain' \
--data-raw 'Hello World'

    

• Example cURL request:

    
curl --location --request POST 'https://sntfx54bil.execute-api.ap-northeast-1.amazonaws.com/default/demo_lambda_function' \
--header 'Content-Type: text/plain' \
--data-raw 'Hello World'

This will result in an error message stating that you are not authorized to access the API as it is no longer publicly available. 

Retrieve the access token from Asgardeo

Next, we’ll retrieve the JWT from Asgardeo using the Client Credentials flow. 

To do this, copy the Client ID and Client Secret from the Protocol tab of the created application in Asgardeo.

Then, invoke the token endpoint in Asgardeo to get the access token.

Using Postman:

Using cURL

• cURL request:
  

    
curl -X POST https://api.asgardeo.io/t/ < organization_name > /oauth2/token \ 
-u  < Client ID >:< Client Secret > \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
            
 
            

• Example cURL request:
  
  

    
curl -X POST https://api.asgardeo.io/t/lakshia/oauth2/token \
-u qA8VrBU6qC77XCONz9vszmz0Ucoa:cem_8gQmTH6jmZAk8tHKsscm_fEa \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'

Access using a token

Once you have received the access token from Asgardeo, you can use it to access the API by using it for authorization as a Bearer token.

Using Postman:

Using cURL

• cURL request:
  
  

    
curl --location --request POST 'https://sntfx54bil.execute-api.ap-northeast-1.amazonaws.com/default/demo_lambda_function' \
--header 'Authorization: Bearer eyJ4NXQiOiJaVGMy…A2hA' \
--header 'Content-Type: text/plain' \
--data-raw 'Hello World'
          
 

• Example cURL request:
  
  

    
curl --location --request POST 'https://sntfx54bil.execute-api.ap-northeast-1.amazonaws.com/default/demo_lambda_function' \
--header 'Authorization: Bearer eyJ4NXQiOiJaVGMy…A2hA' \
--header 'Content-Type: text/plain' \
--data-raw 'Hello World'

Postman Collection

The Postman Collection linked below contains the requests used in this tutorial for the following:

1. Accessing the API without a token (before and after securing the HTTP API with a JWT authenticator).
2. Retrieving the JWT from Asgardeo.
3. Accessing the API with the JWT from Asgardeo.

Postman Collection: 

https://elements.getpostman.com/redirect?entityId=21586123-752ee057-0575-4a5b-b9a2-b1d15f23bfe8&entityType=collection

Summary

The Amazon API Gateway is a robust tool for building and managing RESTful APIs. This tutorial covers the creation of a public HTTP API endpoint linked to a Lambda function, configuring an Asgardeo application to obtain a valid JWT, and securing the API with a JWT authorizer that only allows requests with a valid Asgardeo JWT. By following this tutorial, readers will gain an understanding of how to secure an Amazon API Gateway hosted HTTP API using Asgardeo. Additionally, the tutorial showcases Asgardeo's CIAM capabilities for enterprise applications. 

For further information, please feel free to reach out to us and join our rapidly growing developer community.