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.
The following is a guide to setting up Auth Service locally.
- 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
, port5432
.
- Clone the repo
git clone https://github.com/anhdau185/auth-service.git
- Install packages
yarn install
- 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.
- Build the project
yarn build
- Set up the database
Create a development database:
createdb auth_service_dev
and then run the schema migrations:
yarn migration:run
- Run the service in watch mode
yarn start:dev
The service can now be accessed via localhost:3000
.
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.
- Latest version of Docker Desktop installed.
- Check if
docker
anddocker compose
are running:
docker version
docker compose version
- 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.
- 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
- 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
.
- 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!
- 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
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:
-
Navigate to
localhost:5050
on your browser -
Enter the admin credetials that you specified earlier in your
.env
file (env.PGADMIN_DEFAULT_EMAIL
/env.PGADMIN_DEFAULT_PASSWORD
) -
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
(typically5432
) - Maintenance database:
postgres
- Username: can be obtained from
env.POSTGRES_USER
- Password: can be obtained from
env.POSTGRES_PASSWORD
Happy managing your databases!
Check out this doc for how to develop the service as well as how to deploy and monitor it on a production environment.
This section lists out all the APIs exposed by the Auth Service as well as how to test them.
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) |
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:
- APIs: Download here
- Environment: Download here
- 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).
Hi I'm Anh Dau, author of this repo. You can reach out to me with the contact info at thecodinglad.com/about.