This template allows you to create a web app with basic authentication & authorisation, consisting of a log in box for the Front End that generates a JSON Web Token (JWT) to authenticate the Back End.
Table of Contents
Summary:
- Lets you spin up your web app with Cognito auth, super easy & fast!!
- Is fully configurable (edit Terraform, Serverless Framework and Next.js files)
- Can be used as inspiration for your own project, steal what you like and ignore the rest 😀
- Does not have tests written in the codebase yet (e.g JEST unit tests etc)
- Good for small-scale prototypes, think well & test LOTS before deploying into production
- Will generate bills in your AWS account, DO NOT USE if you don't understand AWS, Terraform & Serverless Framework
Building on that last point.. 
This means that you will be billed by Amazon for usage of those resources.
You are responsible for what you create using this library, it is VERY important that you fully understand what it does before you use it.
If you are uncomfortable with your understanding of what this library does, or you are not familiar with AWS/Terraform/Serverless Framework - then it is my recommendation that you DO NOT use this library.
Deploying resources with this template will result in you getting billed by AWS, you need to understand the nature of - and be comfortable with how - these bills are generated.
What does this template do?
This template helps you create all cloud resources and setup a local host development environment for your own web app with authentication.
This template allows you to create an that that is set up for Front End and Back End authentication.
It does this with Amazon Cognito, that:
- Sets up user credentials
- Creates a log in form on the Front End
- Generates a JSON Web Token (JWT) upon successful login on the Front End, which can then be used to authenticate the Back End API and retrieve data
This template is powered by Terraform, Serverless Framework and Next.js, the breakdown of what they each do is as follows.
Terraform is responsible for creating all cloud resources, excluding lambda functions.
Serverless Framework creates the lambda functions that run the Back End business logic and deploys them to the API Gateway created by Terraform.
Next.js is the Front End that renders the login form and communicates with the Back End via HTTP requests and with AWS Cognito via the Amplify library.
The way a user would then interact with the app is as follows:
- A user visits the url for your web app using their devices web browser, the Next.js pages and content is served to them from the S3 bucket.
- Once the page loads, the user signs in using their AWS Cognito details.
- Once they have successfully logged in:
- a JWT is generated
- an http reuest is make to the API Gateway
- the HTTP API is queried and profile photos are retrieved to be visualised for other users rendered positions
How to use this template
To use this template follow the below steps.
Step 1: Install
Look at the Installation instructions to install the required libraries.
Step 2: Unwrap
Follow the steps outlined in the Setup instructions until you get to Step 3, at that point please bear the below points in mind:
- choose the Auth template by running the command
unwrap Auth. - if you decide that you’d rather create the AWS Secret yourself manually, then the JSON format you want to adapt is below – be sure to replace all values as appropriate to your configuration.
{
"tf_sls_service_name": "my-auth-wrapperjs-config",
"tf_sls_next_stage": "dev",
"tf_sls_next_region": "eu-west-2",
"tf_sls_next_root_domain_name": "jamesmiller.blog",
"tf_sls_next_domain_name": "dev.jamesmiller.blog",
"tf_state_s3_bucket": "my-wrapperjs-config.jamesmiller.blog",
"tf_state_s3_key": "terraform.tfstate"
}
Step 3: Gobble
Continue on from Step 3 until you’ve completed Step 6 of the Setup instructions, you can now run gobble dev to run the application and access the log in webpage on http://localhost:3000.
To log into your web app, you’ll need to create Amazon Cognito credentials, first step to doing this is to find your Cognito user pool.
Then you need to add a new user, to do this you need to click on the ‘Create user’ button.
Fill out the form like shown below (please note you do not need to enter a phone number), then click ‘Create user’.
Please note, the email address you enter will receive an email with the password you’ve created – the user will need to enter this password to log into the site.
Use the credentials you’ve created in the log in form.
You will be prompted to create a new password on log in, fill this out.
And there you go – you’re in!!
If you open your console log, you’ll see ‘Hello World!! :D’ – this is a message that is returned when a http request is made to the API Gateway – if you see this then all is working!
GO MAKE SOME COOL STUFF 😀
