spring-jwt-template

Description

This is a template to help you to get started with jwt-based spring boot backend.

Besides, this project can be used as a Single-Sign On center (or authentication service) directly. We will use open-ssl to generate the private and public key and sign JWT tokens with the private key. Other applications can use the public key to verify the JWT tokens.

Features

• basic models for user, access token, and refresh token
• login api issue access token and refresh token
• web login api issue access/refresh tokens in http only cookie
• set max login failure attempts block login for a while if too many failure attempts
• refresh api exchange new tokens via refresh token
• web refresh api exchange new tokens via the refresh token in http only cookie
• register api with email verification
• logout api revoke access token via redis blacklist
• change password api
• forget and reset password api
• admin api user activate/deactivate, change role, and getUserList
• validation on @RequestBody
• @RateLimit on user or ip based on bucket token algorithm and redis
• api documentation via swagger (at path /swagger-ui/index.html)

Architecture

Online demo

https://frontend.joejoe2.com

Example frontend

We provide an example frontend application written in Vue.js at here to work with this project.

Get started

1. install Docker, JDK-17 and Maven (recommended to use IntelliJ IDE)

2. clone the repo and run mvn install or ./mvnw install

3. set up a postgresql server on localhost:5432 with database spring-test

4. set up a redis server on localhost:6379

5. install open-ssl and run ./jwtRSA256.sh

6. cd to ./src/main/resources/, then copy application-dev.properties and application-dev.yml to application.properties and application.yml

7. edit application.properties depends on your need

   • db related settings

   # connect to database `spring-test` on localhost:5432
   spring.datasource.url=jdbc:postgresql://localhost:5432/spring-test
   
   # set username and password to connect to your database
   spring.datasource.username=postgres
   spring.datasource.password=pa55ward
   
   spring.datasource.driver-class-name=org.postgresql.Driver
   spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
   spring.jpa.properties.hibernate.hbm2ddl.auto=update
   

   • jwt related settings

   # change this to your desired issuer in jwt
   jwt.issuer=joejoe2.com
   
   # domain for access/refresh tokens in cookie(if you are using web login api)
   # can be exact domain or example.com for all subdomains
   jwt.cookie.domain=example.com
   
   # specify lifetime of access and refresh token in seconds
   jwt.access.token.lifetime=900
   jwt.refresh.token.lifetime=1800
   

   • default admin account

   # username can only contain a-z, A-Z, and 0-9 
   # max length is 32
   default.admin.username=admin
   
   # password can only contain a-z, A-Z, and 0-9
   # min length is 8, max length is 32
   default.admin.password=pa55ward
   
   # change to your email
   [email protected]
   

   • mail sender (need to send verification code to newly registered user)

   # this is a example if you use the gmail as smtp server to send eamil
   spring.mail.host=smtp.gmail.com
   spring.mail.port=587
   [email protected]
   spring.mail.password=pa55ward
   spring.mail.properties.mail.smtp.auth=true
   spring.mail.properties.mail.smtp.starttls.enable=true
   

   • set reset password url(redirect user to your reset password page in frontend, we will append token for you to send the password reset request)

   # set reset password url
   reset.password.url=http://localhost:8888/resetPassword?token=
   

   • set allow host(cors for your frontend)

   # for frontend applications at any port of the localhost
   allow.host=http://localhost:[*]
   # for the frontend application at frontend.example.com
   allow.host=https://frontend.example.com
   # for frontend applications belong to subdomains of .example.com
   allow.host=https://*.example.com
   

   • login related settings (ex. block user to login for 900 seconds after 5 consecutive unsuccessful attempts with incorrect password)

   # login max attempt settings
   login.maxAttempts=5
   # in seconds
   login.attempts.coolTime=900
   

8. copy the contents of private.key and public.key (generated at project root in step 4.) into application.yml

   jwt:
    secret:
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        ... your PRIVATE KEY ...
        -----END PRIVATE KEY-----
      publicKey: |
        -----BEGIN PUBLIC KEY-----
        ... your PUBLIC KEY ...
        -----END PUBLIC KEY-----
   

9. now you can start to develop your own project

Notice

We use RSA private key to sign tokens and public key to verify tokens (described in above). So you can use the public key to parse and verify the tokens out of this application (could use this application as an AuthService).

Testing

run mvn test or ./mvnw test

Lint

run

mvn spotless:apply

or

./mvnw spotless:apply

Deploy

1. install docker and docker-compose
2. copy ./env/application.env.example to ./env/application.env and edit just like application.properties(mentioned above), but you need to set jwt.secret.privateKey and jwt.secret.publicKey like this format

   jwt.secret.publicKey="-----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzFVaIiZtFKJgIrrXa9ZQ
   fHeGu3o/CFGAhybGXXcU6XWZpyIHNTUdx7ah1z+pMecXWqOIkmKVN92ktgV+TAEB
   mB91TMr23dMU95JC5wz7H1sxUmO+0HuA5XkGUTXf6GqpIAYLvKnNNhd8eCFm/YAE
   S9LMsRBVZqgAb7GDJDb+B4NTzUGtWn71/2rSnDsXg1+aV271MM7n20AcvRruXDWx
   bz5Wx5kKnTbwrOSvQ1chCo/gg+t+xCUdZ78SyT2bRuUIe+d0qHyqdY6i4lvbiXzC
   noZRygIMYfRyxh0y52Mw6NXLvowOZ2DDYtQMeJglyocOFeYqSgqiRsaELvoQ/5Y8
   1wIDAQAB
   -----END PUBLIC KEY-----"
   

3. copy ./nginx/nginx-certbot.env.example to ./nginx/nginx-certbot.env (just set CERTBOT_EMAIL at first line)
4. edit ./nginx/user_conf.d/server.conf (just change server_name to your own FQDN)
5. make sure that POSTGRES_PASSWORD and POSTGRES_DB in ./docker-compose.yml is same with settings in ./env/application.env
6. docker-compose up or docker-compose up -d