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.
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.
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.
docker run -it --rm \
--name rabbitmq \
-p 5672:5672 \
-p 15672:15672 \
rabbitmq:3-management
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"
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.
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.
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 |
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 and their codes can be seen in errors/codes.go
To see an implementation of the jwt-auth API, please see the following example client.
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.
This project is licensed under the MIT License - see the LICENSE file for details.