Step-up Authentication using Amazon Cognito, DynamoDB, API Gateway Lambda Authorizer, and Lambda functions

Key	Value
Environment
Services	Cognito, DynamoDB, API Gateway, Lambda, CloudFront, S3, IAM, Amplify
Integrations	CDK, AWS CLI
Categories	Serverless; Security, Identity, and Compliance
Level	Advanced
GitHub	Repository link

Introduction

The Step-up Authentication sample using Cognito, DynamoDB, API Gateway Lambda Authorizer, and Lambda functions demonstrates how to build and launch a Step-up workflow engine with an API Serving Layer on your local machine. This application sample uses Cognito as an identity provider, API Gateway with Authorizer Lambda function to trigger the Step-up workflow engine, and DynamoDB Service as the persistent layer the Step-up workflow Engine uses. The application client is implemented using ReactJS and Amplify, which allows us to invoke a privileged API and go through Step-up authentication. With the LocalSurf browser plugin, you can test the application on your local machine by making API requests to LocalStack instead of AWS to allow you to use the production code locally without changes. Refer to the official AWS blogs for additional design documentation and implementation details.

Architecture diagram

The following diagram shows the architecture that this sample application builds and deploys:

We are using the following AWS services and their features to build our infrastructure:

• Cognito User Pools used as user registry and an identity provider for user authentication.
• API Gateway to trigger the Step-up workflow engine for the Lambda Authorizer.
• DynamoDB as a key-value and document database to persist data used by Step-up workflow Engine.
• IAM to create policies to specify roles and permissions for various AWS services.
• CloudFront to create a local CloudFront distribution for the application accessible via CloudFront URLs.
• Lambda to create an Authorizer Lambda function to trigger the Step-up workflow engine.
• S3 to deploy the Amplify web application via CloudFront distribution on a locally accessible CloudFront URL.
• Amplify to create a web application that uses the Step-up workflow engine to authenticate users.

Prerequisites

• LocalStack Pro
• LocalSurf to repoint AWS service calls to LocalStack.
• AWS CLI with the awslocal wrapper.
• CDK with the cdklocal wrapper.
• NodeJS v18.0.0 with npm package manager.

Start LocalStack Pro with the appropriate configuration to enable the S3 website to send requests to the container APIs:

export LOCALSTACK_AUTH_TOKEN=<your-auth-token>

Then run:

EXTRA_CORS_ALLOWED_ORIGINS=* localstack start -d

The EXTRA_CORS_ALLOWED_ORIGINS configuration variable allows our website to send requests through the Amplify Web Application to the privileged API to enable us to demonstrate step-up authentication.

Instructions

You can build and deploy the sample application on LocalStack by running our Makefile commands. It abstracts the steps required to build and deploy the application, which are mentioned in detail in the build.sh and deploy-local.sh script, present in the deployment directory.

Building the resources

To build the resources, run the following command:

make build

This command runs the build.sh script, which packages the Lambda functions which would be part of the Step-up workflow Engine. The following Lambda functions are packaged:

• Step-up authorizer
• Step-up Challenge
• Step-up Initiate
• Sample API Lambda

Apart from this, the Amplify Web Application is also built and packaged to be deployed on the CloudFront distribution via an S3 bucket.

Deploying the resources

To deploy the resources, run the following command:

make deploy

The command bootstraps the CDK deployment and creates the local AWS resources using LocalStack. The output from the command will contain a local CloudFront distribution URL:

Copying dist contents to Web UI S3 bucket: step-up-auth-web-ui-000000000000-us-east-1
Invalidating cloudfront distribution cache: <DISTRIBUTION-ID>
Done!

Sample Web App URL: <DISTRIBUTION-ID>.cloudfront.localhost.localstack.cloud

To access the web application, copy and paste the CloudFront distribution URL in your browser. You will be redirected to the Cognito User Pool sign-in page. You can sign up for a new user and get started with the application.

Testing the application

To run the application, we need the LocalSurf browser plugin installed and enabled. Ideally, your applications should use configuration files to specify their AWS services. However, we inherited hard-coded AWS service endpoints in this sample application, which we need to repoint to LocalStack. We can do this using the LocalSurf browser plugin.

Your application's landing page contains a sing in form. To sign in, you need to have a user account. You can create a new user account by clicking the Register button.

To test the web application, open your application URL in your browser that was displayed on the terminal. Enter your username, password, email address, and phone number in the form displayed on the application.

Click on the Register button. Cognito will generate a verification code, which will be displayed in the terminal in the LocalStack logs. Use this code to confirm your Account.

Once you have confirmed your Account, you can sign in to the application with your username and password. You should see your session's information on the landing page.

Learn more

The sample application is based on a public AWS sample app that deploys a Step-up workflow engine on AWS. See these AWS blog posts for more details:

• Implement step-up authentication with Amazon Cognito, Part 1: Solution overview
• Implement step-up authentication with Amazon Cognito, Part 2: Deploy and test the solution

Contributing

We appreciate your interest in contributing to our project and are always looking for new ways to improve the developer experience. We welcome feedback, bug reports, and even feature ideas from the community. Please refer to the contributing file for more details on how to get started.