AWS Cognito – Web Application Integration Basics

Introduction

In previous post on AWS Cognito Basics – User Pools. we covered the basics of AWS Cognito and also created a User pool. Following is the recap:

Recap

AWS Cognito lets you add user sign-up, sign-in and access-control to your web and mobile apps quickly and easily:

• User pools are user directories.
• Signup and Singin services.
• A built in customizable web UI to sing users.
• Social Sign-in with IDPs.
• User directories management and user profiles.
• Security features (MFA, password policy etc.)
• It is also integrated with Lambda triggers.
• Also provides the ability to create groups and assign users to groups.

Furthermore we also created a public app-client (web app) and configured its callback and sign-out redirect URLs and OAuth 2.0 Flows (Authorization Code Grant and implicit grant).

Please refer to previous post if you are new to these topics.

What We Will Cover Today

So we know the theory and what AWS Cognito is offering to us and now lets take a step further and implement the following scenario:

We have a static web-application (HTML, JavaScript , CSS) and it does not have a dedicated backend yet. Lets see, how can we integrate login/logout functionalities using AWS Cognito.

This is a very simple example, but it will setup the foundation we will extend for advance scenarios later.

Setting up a Simple Web Application

First thing first, I setup a git repository with a very simple web-application. All the source code is available from there. Clone the repo and check the readme file to run the application locally. You can also use your own application for exercise and simply follow the steps.

Application has one html page index.html and index.js file as the entry-point JavaScript file. There are some libraries like jQuery, bootstrap for styling and ParceJS as bundler and following is the UI for your reference:

So boiler plate basic web page with our focus on user-name placeholder and two buttons (Login and Logout) and without any kind of setup with AWS Cognito.

This is our starting point and we will integrate AWS Cognito.

As mentioned in previous post, Cognito offers hosted UI, so we do not have to really create all the corresponding Login, Logout, Password reset etc. UI pages ourselves. We can simply use hosted UI. Of course Hosted UI will not give us the flexibility and ease to customize our own design as we like, but its ideal when focus is not initially on the UI part and if needed, we can setup custom UI pages ourselves later.

AWS Amplify integration

Since AWS Amplify projects leverage Cognito user-pools for authentication, apps that leverage Cognito can utilize the drop-in libraries and UI components from amplify even if they aren’t using the Amplify service.

This means, we do not have to write all the boiler plate code to make calls to idp and work with headers, retries etc. We will simply add the package and delegate tasks to the aws-amplify library to handle it and give us the response which we will handle in our application code.

For more information, please check the docs available on this link.

We can install the amplify package via npm command as shown below:

npm install aws-amplify

We’ll start by importing the Auth module from AWS Amplify SDK. This is what we are going to use to authenticate against our Cognito user pool.

Next, we will need to configure Amplify with our user-pool id and WebClient id and other settings, that we created in previous post. We can find these values from AWS management console:

(Note the https in the redirect URLs, ParcelJS allow us to use https in development, if needed.)

• UserPoolId: This uniquely identifies a AWS Cognito UserPool and which manages the Users.
• userPoolWebAppClientId: grants an application to connect to and access AWS Cognito for reading and writing User data.
• Region: Where the Cognito is currently created

With this, Auth module is connected with our user-pool.

aws-amplify and ParcelJS integration issue

I ran into following issue (parecelJS) so if you also see some browser console error similar to following:

add the following import statement to index.js file to resolve it:

Get Current Authenticated User

Amplify makes contact our Cognito user-pool very straight forward.

Following is the JavaScript code, which uses Auth module (aws-amplify) we imported earlier and we can simply call the methods on it:

based on result from this method call, we can update the user interface by passing the returning object to setUserState function.

Here is the setUserState function:

Nothing fancy, very typical JavaScript to show/hide DOM elements.

with all this wiring in place (you can check the source-code for details), we can run the application:

and you can see that it now shows only Login button (Logout button and user-name place-holder are hidden when user is not logged). Console window log shows the authentication status.

And now because this information is available to us on client-side, we can render it to UI as needed:

Looking good, lets take it one step further and trigger the Hosted UI when user click the Login button:

Trigger Hosted UI

As mentioned earlier and we also saw this in previous post, AWS Cognito User Pool’s Hosted UIs helps setting up authentication workflows in minutes and the ease of integration on the client-apps helps in speeding up the application development process.

This is a pure no-code approach to get started with a fully-functional authentication module for your applications.

Following code triggers the Hosted UI when user click the login button:

here is the handler function:

and here is the login UI

These UI components and related functionalities are coming from hosted UI. User can now Sign in, Sign up, reset password etc.

Sign-up screen

Forgot Password UI

Sign in to Application

We have few user accounts from previous post or you can sign up for a new account. Here is how the UI displays the singed-in user (name placeholder and logout button are shown, login button is hidden)

browser console shows us the information about this user:

Logout Function

Similar to Sign-in, the logout functionality is straight forward to implement:

Auth module is again doing all the heavy lifting and we are just delegating this task to it. Once user is logged out, they will be redirected to the redirectSignOut URL we configured earlier.

Deploying the Application and Testing

Ok, application is working in development environment. Lets deploy it to AWS and test it.

I’ve setup the S3 bucket, CloudFront distro and certificates. These topics are covered in my earlier posts, so I will not go into those details here. The application is deployed and available on the following url:

https://cognito.awsclouddemos.com/

Following are the changes made to application JavaScript code and the user-pool for deployment purposes.

and following is the deployed application with user signed-in:

So that’s it for today. We’ve made some progress, integrated Cognito User Pool with our web application and the process was not that difficult and we got out-of-the-box common user related functionalities and UI components with built-in scalability, resiliency and availability of AWS managed service infrastructure.

Related Links

• Deployed Application
• AWS Cognito Basics – User Pools
• Parcel JS – A Blazing fast, zero configuration web application bundler
• Amplify Libraries
• Migrate On-Prem Web app (.NET Core, Angular and Postgres) – to AWS Serverless

Summary

In this post, we integrated a simple web-application to AWS Cognito using JavaScript.

AWS Cognito is a great service which greatly simplifies users related tasks and central identity concerns for us and we get more time to spend on developing functionality which delivers business value.

The Amplify JavaScript libraries are supported for different web and mobile frameworks including React, React Native, Angular, Ionic, and Vue. You can check the docs here.

You can find the sample application source code from this git repository.

We will cover more advance application scenarios in upcoming posts. Let me know if you have some questions or comments. Till next time, happy coding.