The need to manage a user base for an online system is very frequent. Goal of this project is to offer a generic user's data management microservice.
This microservice can offer a good and solid starting point for managing your accounts. Thanks to this Role Based Access Control implementation it's easy to define roles and permissions for your specific application/prototype and subsequently apply these access rules on the users.
This project lends itself very well to implement new prototypes or to create new solutions based on microservice architecture.
The solution is thought using the Docker technologies with two different containers:
- one Spring Boot REST Apis
- one MySql 8.0 database
The code has been well tested (> 115 tests) using JUnit and Mockito, H2 in memory database and some standard libraries for the integration tests.
If you're using this software or a part of it, you can support this open source with a small donation here:
The branch "spring-boot-3" contains the necessary updates in order to use this microservice with the last spring boot 3 version.
Remember that Spring Boot 3 is based on the Jakarta project and not the J2EE one. Also the spring fox / Swagger dependency has been removed. In addition the java version needed is the Java 17. The Dockerfile has been updated using the eclipse-temurin:17 docker image.
The REST apis offered from the "spring-boot-3" microservices are the same likes the standard java 8 version.
Here below the most relevant features exposed using REST Apis:
- Register a new user account
- Login with username & password
- Retrieve a single user account
- Retrieve the list of all the existing user accounts
- Update user account data (basic user data, contacts, address)
- Add or remove a role on an user account
- Delete a user account
- Define secured accounts that cannot be deleted but only modified
- Standard validation for email, phone, password
- Retrieve all the permissions
- Retrieve the list of the existing roles
- Create a new role
- Retrieve a single role
- Delete a role
- Add a permission on a role
- Remove a permission on a role
- Create a new permission
- Update an existing permission (also enabled or disable it)
- Retrieve single permission
- Delete not used permission
- Api to generate a salt random value to encrypt password (configuration)
Using a browser it's possible to interact with the REST apis with Swagger:
http://localhost:8090/swagger-ui.html
Another alternative is to using an external tool, for example Postman (https://www.postman.com/).
This project contains also the Postman export file with all the configured test calls:
Thanks to Docker it’s easy to create scalable and manageable applications built of microservices.
The project is designed to use two containers:
- one Java microservice
- one MySql database
The Docker environment is necessary in order to work with the containers and the setup depends about your Os.
Proceed the setup for the Docker environment: Get Docker
To compile and run the Java project you need to install a Java 8 JDK on your local machine.
Follow the instructions below to setup a local docker image for a mysql8.0 database:
The microservice application has been updated to support a docker dev-network and there are no needs to configure manually the IP address of the database target: this setup is necessary only one time.
Create the developer network:
docker network create dev-network
Check that the network has been defined:
docker network ls
Modify the file db.cmd and set a folder to use for the MySql's docker volume.
Run the MySql container:
./db.cmd
Execute the run bash script to compile and run the microservice container:
./run.cmd
Open a browser and explore the REST apis:
http://localhost:8090/swagger-ui.html
The RBAC microservice should be up and running and connecting with the MySql instance with the demo data. If you want to remove this demo data proceed to configure your system as in "Setup a ready and empty RBAC" section.
Everything should be up and running :)
You can also setup and work on this project without to consider to use Docker. You will just launch the Spring Boot application targeting the MySql database (on localhost or on a remote one).
Install Java 8 JDK.
Set up your MySql instance and create the empty database "users":
CREATE DATABASE IF NOT EXISTS users;
Create and grant a new MySql user on the "users" database.
Open the application.properties file located in /src/main/resources.
Target your localhost MySql database:
spring.datasource.url=jdbc:mysql://localhost:3306/users?useSSL=false&allowPublicKeyRetrieval=true
Set the username and password of the MySql's user:
spring.datasource.username=yourMySqlUser
spring.datasource.password=yourMySqlUserStrongPassword
Execute the microservice code using Maven:
./mvnw spring-boot:run
Open a browser and explore the REST apis:
http://localhost:8090/swagger-ui.html
The RBAC microservice should be up and running and connecting with the MySql instance with the demo data. If you want to remove this demo data proceed to configure your system as in "Setup a ready and empty RBAC" section.
Everything should be up and running using your local MySql :)
You can prepare a specific clean RBAC microservice setup without any demo data and without to reset the database content at each restart.
Install Java 8 JDK.
Set up your MySql instance and create the empty database "users":
CREATE DATABASE IF NOT EXISTS users;
Create and grant a new MySql user on the "users" database.
Open the application.properties file located in /src/main/resources.
Set the username and password of the MySql's user:
spring.datasource.username=yourMySqlUser
spring.datasource.password=yourMySqlUserStrongPassword
For a production environment consider to create a specific MySql user for the database "users" using a strong password.
Disable the demo data setting as below:
# enable initialization using schema.sql and data.sql
spring.datasource.initialize=false
spring.jpa.hibernate.ddl-auto=update
spring.datasource.initialization-mode=never
Configure a different encryption salt:
# password encryption
microservice.security.salt=WZeBXmCI9cAz3LyY9Sdllj9l5iPsXC
If you need, you can launch the microservice and using Swagger to call the rest endpoint /users/rbac/salt in order to generate a new random one.
Save the application.properties file.
Run the build of the microservice and lunch the container:
./run.cmd
The RBAC microservice should be up and running and connecting with the MySql instance without demo data. Proceed with your RBAC configuration using the REST apis:
http://localhost:8090/swagger-ui.html
Restarting the db or the microservices should not affect the persistence of your RBAC configuration.
I've followed the blog post below in order to implement an encryption and decryption method for sensible data such as passwords.
http://www.appsdeveloperblog.com/encrypt-user-password-example-java/
This project has been created in February 2020 by Andrea Giassi.
Andrea he's an italian Agile professional and Software Engineer actives in web systems and services. Since 2002, Andrea is working in the IT market for several different companies and start ups and it has contributed to the success of several solutions and products.
About me: https://www.linkedin.com/in/andreagiassi/
Please support this open source with a small donation here: