joelroxell / heimdall

Heimdall is a minimal authentication service tailored for dockerized development and deployment.

Heimdall(beta)

Authentication microservice.

Heimdall is a minimal authentication service tailored for dockerized development and deployment.

Maintainer: Joel Roxell <[email protected]>

TL;DR

TOC

• Dependencies
• Environment
• API
  • Register a User
  • Get User information
  • Sign in
  • Reset User password
• Development
  • Prerequisites
  • Setup
  • Tools & Scripts

Dependencies

• Redis
• MongoDB

Environment

VARIABLE	DESCRIPTION
NODE_ENV	Sets the application to either production or development mode
SECRET	Secret which is used to sign and verify JWTs
SALT_ROUNDS	Amount of rounds that bcrypt should use on encryption
TOKEN_TTL	Minutes before a token expires

API

METHOD	URI	ERROR CODE	SUCCESS CODE	OUTPUT
POST	/user/register	400, 409	201	User
GET	/user	400, 403	200	User
POST	/user/reset-password	400, 403	200	User
POST	/auth/sign-in	400, 401	200	Token(encoded)

Register a User

POST /user/register

Creates a new User

HEADERS

Content-Type: json/application

REQUEST BODY

NOTE: both properties must be of type String

{
  "email": "[email protected]",
  "password": "someSecretPassword"
}

RESPONSE

HTTP 201 - User was created successfully

{
  "email": "[email protected]"
}

HTTP 400 - Invalid request body

{
  "error": "request body did not pass validation"
}

HTTP 409 - User Already exists

{
  "error": "a user with that email already exists"
}

Get User information

GET /user

Returns a JSON string containing user information.

HEADERS

Content-Type: json/application Authentication: Bearer {encoded-JWT}

RESPONSE

HTTP 200 - User was created successfully

{
  "email": "[email protected]"
}

HTTP 403 - Invalid JWT

{
  "error": "jwt expired|invalid token"
}

Sign in

GET /user/sign-in

Returnes a encoded JWT on success.

HEADERS

Content-Type: json/application

RESPONSE

HTTP 200 - User signed in successfully

{
 "token": "{header.payload.signature}"
}

HTTP 400 - Invalid request body

{
  "error": "request body did not pass validation"
}

HTTP 401 - Invalid credentials

{
  "error": "authentication failed"
}

Reset User password

PUT /user/reset-password

Sets a new password for the specific User and returnes the updated User.

HEADERS

Content-Type: json/application Authentication: Bearer {encoded-JWT}

RESPONSE

HTTP 200 - User was created successfully

{
  "email": "[email protected]"
}

HTTP 400 - Invalid request body

{
  "error": "request body did not pass validation"
}

HTTP 403 - Invalid JWT

{
  "error": "jwt expired|invalid token"
}

Development

Prerequisites

To be able to get this project up and running, you'll need:

• Docker
• Docker Compose
• npm

Setup

Follow these steps to get going:

• git clone [email protected]:JoelRoxell/heimdall.git
• docker-compose up

The service will now build and run in a Docker container. The codebase is mounted into the container and the server will be restarted on save.

Tools & Scripts

SCRIPT	USAGE	CAVEATS
npm test	Runs all unit tests using mocha	The container must be running.
npm run test:watch	Runs all unit tests and watches for changes	The container must be running.
npm run test:debug	Runs all unit tests and watches with node --inspect	The container must be running.
npm run cov	Runs all unit tests and generates coverage	The container must be running.
npm run open:cov	Opens the code coverage report in the default browser	The container must be running.
npm run precommit	Runs eslint just like the git precommit hook does	-
npm run bash	Enters the container with bash	The container must be running.
npm run reinstall	Installs dependencies using yarn inside the container	The container must be running.
npm run generate:pem	Generates a new .pem and .pub file used to sign JWTs	Requers the container to be rebooted.

Testing

Tests should be easy to read. You can use this standard when writing tests.

describe <subject>
	it (the subject) should <act like this> when <this action is performed>

Real example:

describe('Request handler', function() {
	it('should return false when receiving invalid payload', function() {
		// ...
	});
});