Serverless JWT Auth Boilerplate (⚠️ Work In Progress)

A Serverless REST API boilerplate for authenticating with email/password over JWT (JSON Web Tokens).

In production, it uses:

AWS Lambda for computing
AWS Dynamodb for database storage
AWS Cloudformation to provision the AWS resources
AWS S3 for object storage (storing the code)

Installation

# Install the Serverless CLI
yarn global add serverless

# Clone the repo
git clone https://github.com/mcnamee/serverless-jwt-auth.git serverless-jwt-auth

# Install dependencies
cd serverless-jwt-auth && yarn install

# Add your environment variables (and update the JWT secret)
cp env.example.yml env.prod.yml

Usage

Development

You can use Serverless Offline while you develop, which starts a local DynamoDB instance (data is reset on each start)

yarn start

# OR to use env.staging.yml environment variables:
# yarn start --STAGE staging

Tests

yarn test

Production

1. Setup your AWS credentials

Create a new AWS IAM user and assign the AdministratorAccess policy to the new user (later, it's best to reduce the permissions this IAM User has for security reasons).

serverless config credentials --provider aws --key <YOUR_AWS_KEY> --secret <YOUR_AWS_SECRET>

2. Then deploy to AWS

sls deploy

# OR to use env.dev.yml environment variables:
# sls deploy --STAGE dev

Endpoints

Register

Request: POST /register

{
  "firstname": "John",
  "lastname": "Smith",
  "email": "john@smith.co",
  "password": "123Abc123"
}

# Response

{
  "message": "Success - you are now registered",
  "data": {
    "token": "<YOUR-JWT-TOKEN>",
    "firstName": "John",
    "lastName": "Smith",
    "createdAt": 1536717884934,
    "level": "standard",
    "id": "37ff3e00-b630-11e8-b87d-85b1d165e421",
    "email": "john@doe.com",
    "updatedAt": 1536717884934
  }
}

Login

# Request: POST /login

{
  "email": "john@smith.co",
  "password": "123Abc123"
}

# Response

{
  "message": "Success - you are now logged in",
  "data": {
    "token": "<YOUR-JWT-TOKEN>",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": 1536134110955,
    "level": "standard",
    "id": "03969310-b0e1-11e8-a48b-efa31124d46c",
    "email": "john@doe.com",
    "updatedAt": 1536134110955
  }
}

My Details

# Request: GET /user

# Response

{
  "message": "Success - user data retrieved",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": 1536134110955,
    "level": "standard",
    "id": "03969310-b0e1-11e8-a48b-efa31124d46c",
    "email": "john@doe.com",
    "updatedAt": 1536276034130
  }
}

Update User

Request: PUT /user

{
	"firstName": "Jane",
	"lastName": "Doe",
	"email": "jane@doe.com",
	"password": "123Abc"
}

# Response

{
  "message": "Success - user updated",
  "data": {
    "firstName": "Jane",
    "lastName": "Doe",
    "createdAt": 1536134110955,
    "level": "standard",
    "id": "03969310-b0e1-11e8-a48b-efa31124d46c",
    "email": "john@doe.com",
    "updatedAt": 1536276156160
  }
}

mcnamee / serverless-jwt-auth