This template allows you to create a web app with a log in box for the Front End that generates AWS STS credentials to authenticate the Back End once a signed metamask signature is verified as belonging to the account that signed it, the dApp allows that user to interact with its data & smart contracts.
Table of Contents
Summary:
- Lets you spin up your web app with Eth Cognito auth, super easy & fast!!
- Is fully configurable (edit Terraform, Serverless Framework, Next.js & Ethereum 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) and has not had any form of security testing / auditing
- Good for small-scale prototypes, think well & test LOTS before deploying into production
- Will generate bills in your AWS account and creates smart contracts to handle funds, DO NOT USE if you don't understand AWS, Terraform, Serverless Framework and Solidity.
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.
This library and template is not related in anyway to where I am employed and is not endorsing this technical approach for web3 authentication, this is to be used for experimentation and inspiration.
Lastly, deploying smart contracts can result in users data / funds being compromised and stolen. If you decide to use this template be sure to thoroughly test and audit your code base to help increase security and reduce risk of hacks and exploits.
What does this template do?
This template helps you create all smart contracts, 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 using your Ethereum account address.
It does this as follows:
- User clicks a log in button and creates a signature
- The Front End takes this signature and sends it to the Back End to verify that the person that signed the signature is the same as the person that is attempting to log in
- Once verified, access credentials are provided back to the Front End, which can then be used to allow access past the log in screen to interact with the dApp’s smart contracts and Back End data.
This template is powered by Terraform, Serverless Framework, Next.js and Ethereum, 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.
Ethereum is the blockchain used, along with other related technologies that is used for creation of, and interaction with smart contracts.
Next.js is the Front End that renders the login form and communicates with the Back End via the AWS4Sign library and with the Ethereum network via Web3.js.
The way a user would then interact with the dApp by clicking the log in button:
- The Front End retrieves the address of your Ethereum account
- An HTTP request to the Back End is made to retrieve the nonce associated with that account / create one if it doesn’t exist.
- A Metamask pop up would then appear to request the user creates a signature with their private key and nonce, approving their access to the dApp.
- An HTTP request is made using the signature and users account address, to the API Gateway that retrieves access credentials by:
- Verifying the signature by checking the provided nonce matches the nonce in the DynamoDB database and provided address matches the address retrieved from the signature.
- Creating / retrieving a Cognito identity based on the Ethereum address.
- Generating and returning AWS STS access credentials to the Front End.
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 Eth-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.
{
"eth_tf_sls_service_name": "my-eth-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",
"eth_network": "goerli",
"eth_network_api_url": "https://eth-goerli.g.alchemy.com/v2/abcdefghijklmnopqrstuvwxyz",
"eth_account_address": "678910",
"next_greeter": "abcdefg", // address of deployed greeter contract
"next_jmbToken": "hijklmnop", // address of deployed erc20 token contract
"next_greeterArtifact": {...}, // ABI for the deployed greeter contract
"next_jmbTokenArtifact": {...}, // ABI for the deployed ERC20 token contract
}
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.
And there you go – you’re in!!
Assuming you have a basic understanding of how to interact with Solidity Smart contracts using Metamask, there is nothing stopping you from logging in and adapting this codebase!
GO MAKE SOME COOL STUFF 😀
