Eth Auth Template

Wrapper.js Eth Auth

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


Building on that last point.. 👇

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.

Toggle the below tabs to understand how.

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:

  1. User clicks a log in button and creates a signature 
  2. 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
  3. 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:

  1. The Front End retrieves the address of your Ethereum account
  2. An HTTP request to the Back End is made to retrieve the nonce associated with that account / create one if it doesn’t exist.
  3. 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.
  4. 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": "",
  "tf_sls_next_domain_name": "",
  "tf_state_s3_bucket": "",
  "tf_state_s3_key": "terraform.tfstate",
  "eth_network": "goerli",
  "eth_network_api_url": "",
  "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!