/auth-service

One centralized, dedicated authentication server for consumer apps and microservices.

Primary LanguageTypeScript

Auth Service

Auth Logo

Reliable, lightweight, dedicated JWT authentication as a microservice that provides separation of authentication concerns and brings scalibility to a distributed system.

Built with ❤️ and the NestJS framework.

Getting Started

The following is a guide to setting up Auth Service locally.

Prerequisites

  • Node.js 16 installed. You can use v16.14.2 as recommended by the project.
  • Yarn package manager. Install it with:
npm install -g yarn
  • PostgreSQL 13 installed. Make sure the database server has been started on your localhost, port 5432.

Installation & Setup

  1. Clone the repo
git clone https://github.com/anhdau185/auth-service.git
  1. Install packages
yarn install
  1. Configuration

Create a .env file by copying the project's sample file .env.dev:

cp .env.dev .env

and fill out all the empty fields in it with your own values.

  1. Build the project
yarn build
  1. Set up the database

Create a development database:

createdb auth_service_dev

and then run the schema migrations:

yarn migration:run
  1. Run the service in watch mode
yarn start:dev

The service can now be accessed via localhost:3000.

Setting up Using Docker

Auth Service can also run as a containerized application. In fact, this is the preferable way in which the service should be deployed and run in a production environment because of the portability (and many more advantages) that containers provide.

The following is an alternative setup guide using Docker containers.

Prerequisites

  • Latest version of Docker Desktop installed.
  • Check if docker and docker compose are running:
docker version
docker compose version

Installation & Setup

  1. Configuration

Create a .env file by copying the project's sample file .env.prod:

cp .env.prod .env

and fill out all the empty fields in it with your own values.

  1. Get the Docker images

Pull all the images needed to get the project up and running from Docker Hub:

# postgres image
docker pull postgres:13-alpine

# backend app image
docker pull anhdau185/auth-service:latest

# pgadmin4 image
docker pull dpage/pgadmin4:latest
  1. Run the service

Run the service as containers in the background with docker compose:

docker compose up --detach

The service can now be accessed via localhost:3000.

  1. Schema migrations (for the first spin-up)

If you are running the service for the first time or anytime the database schema is changed (which leads to a generation of a new migration file), you will need to run schema migrations before the service becomes actually usable.

To do this with your backend app running inside a Docker container, run the command:

docker exec auth yarn migration:run

The containerized service is now all set and ready for use!

  1. Stop the service

If you'd want to stop (and then remove) the service's running containers as a whole, run the command:

docker compose down

Using pgAdmin 4 to manage PostgreSQL

pgAdmin is an open-source administration and development tool for PostgreSQL. The web-based pgAdmin 4 is included in this project as a container running in parallel with the main service's containers.

To manage, administer, or simply interact with your PostgreSQL databases:

  1. Navigate to localhost:5050 on your browser

  2. Enter the admin credetials that you specified earlier in your .env file (env.PGADMIN_DEFAULT_EMAIL / env.PGADMIN_DEFAULT_PASSWORD)

  3. Connect to your database server (a.k.a. db container in this case) with:

  • Name: db_container (or whatever works for you)
  • Hostname: db
  • Port: can be obtained from env.POSTGRES_PORT (typically 5432)
  • Maintenance database: postgres
  • Username: can be obtained from env.POSTGRES_USER
  • Password: can be obtained from env.POSTGRES_PASSWORD

Happy managing your databases!

Workflows

Check out this doc for how to develop the service as well as how to deploy and monitor it on a production environment.

Usage

This section lists out all the APIs exposed by the Auth Service as well as how to test them.

API Documentation

API Name/Purpose Endpoint Request Body Bearer Token Required? Comment
Register a New User POST /users/signup { name; username; password; scope? } No
Get the User List GET /users Yes (Access Token) Needs authorization
Get a User GET /users/:id Yes (Access Token) Needs authorization
Update a User PATCH /users/:id { name; password } Yes (Access Token) Needs authorization
Delete a User DELETE /users/:id Yes (Access Token) Needs authorization
Sign In POST /auth/login { username; password } No
Authenticate a User POST /auth/protected Yes (Access Token)
Refresh Tokens POST /auth/refresh Yes (Refresh Token)
Sign Out POST /auth/logout Yes (Refresh Token)

Testing

Postman, a popular API platform, is a helpful tool to play around with and get used to the above APIs. Here are some sample collections that can be useful for testing these APIs:

Roadmap

  • Authentication with Local Strategy
  • JWT Authentication with Refresh Tokens
  • Rotating & Invalidating Refresh Tokens
  • User Authorization
    • Admin
    • User
    • Guest (Unauthorized)
  • API versioning

See open issues for a full list of proposed features (and known issues).

Contact

Hi I'm Anh Dau, author of this repo. You can reach out to me with the contact info at thecodinglad.com/about.