JWT Authentication Microservice

A simple JWT based authentication server.

Features:

• Token based stateless authentication.
• User sign up, sign in, sign out, update, confirm, delete, and reset password.
• Send welcome, confirm, and reset password emails.
• Issue access and refresh token on signin.
• Ability to store tokens in HTTPOnly cookies and/or receive in JSON response.
• Refresh token revocation on sign out and ability to revoke all refresh tokens on sign out everywhere.
• JWT signed using RS256 signing algorithm for asymmetric encryption.

Quick Start

This section will guide you through getting this project up and running as quickly as possible. It will only require that docker is installed and nothing else.

This quick start is recommended for experimenting/testing purposes only.

Run Postgresql

docker run -it --rm \
--name postgres \
-p 5432:5432 \
-e POSTGRES_DB=jwt-auth \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
postgres:11-alpine

Note: If you want to use an existing Postgresql setup with same port, then ensure that the jwt-auth database is created.

Run Rabbitmq

docker run -it --rm \
--name rabbitmq \
-p 5672:5672 \
-p 15672:15672 \
rabbitmq:3-management

Generate an RSA keypair with a 2048 bit private key

JA_KEYS_DIR="$HOME/.jwt-auth/keys"

mkdir -p "$JA_KEYS_DIR"
openssl genpkey -algorithm RSA -out "$JA_KEYS_DIR/private_key.pem" -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in "$JA_KEYS_DIR/private_key.pem" -out "$JA_KEYS_DIR/public_key.pem"

Run application

docker run \
--network host \
--volume "$JA_KEYS_DIR":/keys \
-e JA_TOKEN_PRIVATE_KEY_PATH=/keys/private_key.pem \
-e JA_TOKEN_PUBLIC_KEY_PATH=/keys/public_key.pem \
docker.pkg.github.com/mjah/jwt-auth/jwt-auth:latest serve

Go to localhost:9096/ping, if you receive a pong then you are now up and running.

Configuration

See the config.example.yml file for an example of the configuration.

Environment variables are also supported. This will be the configuration name in all capital letters, 'JA_' prefixed, and '.' replaced with '_'. E.g. email.smtp_host becomes JA_EMAIL_SMTP_HOST.

API

Public Routes

Path	Method	JSON Data	Shared Error Responses	Further Error Responses
/signup	POST	email (string, required) username (string, required) password (string, required) first_name (string, required) last_name (string, required) confirm_email_url (string, required)	DetailsInvalid DatabaseConnectionFailed DatabaseQueryFailed	EmailAndUsernameAlreadyExists EmailAlreadyExists UsernameAlreadyExists DefaultRoleAssignFailed PasswordGenerationFailed MessageQueueFailed
/signin	POST	email (string, required) password (string, required) remember_me (bool, required)	EmailDoesNotExist PasswordInvalid AccessTokenIssueFailed RefreshTokenIssueFailed
/confirm-email	POST	email (string, required) confirm_email_token (string, required)	EmailDoesNotExist EmailAlreadyConfirmed UUIDTokenDoesNotMatch UUIDTokenExpired
/reset-password	POST	email (string, required) reset_password_token (string, required) password (string, required)	EmailDoesNotExist UUIDTokenDoesNotMatch UUIDTokenExpired PasswordGenerationFailed
/send-confirm-email	POST	email (string, required) confirm_email_url (string, required)	EmailDoesNotExist EmailAlreadyConfirmed MessageQueueFailed
/send-reset-password	POST	email (string, required) reset_password_url (string, required)	EmailDoesNotExist MessageQueueFailed

Private Routes

Accessing private routes will require the refresh token in the authorization bearer.

Path	Method	JSON Data	Shared Error Responses	Further Error Responses
/user	GET		AuthorizationBearerTokenEmpty RefreshTokenCookieEmpty JWTTokenInvalid DatabaseConnectionFailed DatabaseQueryFailed UserDoesNotExist UserIsNotActive RefreshTokenIsRevoked
/user	PATCH	email (string, optional) username (string, optional) password (string, optional) first_name (string, optional) last_name (string, optional)	DetailsInvalid EmailAndUsernameAlreadyExists EmailAlreadyExists UsernameAlreadyExists PasswordGenerationFailed
/user	DELETE
/signout	GET
/signout-all	GET
/refresh-token	GET		AccessTokenIssueFailed

Error Responses

Error responses and their codes can be seen in errors/codes.go

Example Client

To see an implementation of the jwt-auth API, please see the following example client.

Contributing

Any feedback and pull requests are welcome and highly appreciated. Please open an issue first if you intend to send in a larger pull request or want to add additional features.

License

This project is licensed under the MIT License - see the LICENSE file for details.