ralugli / microservice-template-java

:white_check_mark: A template for a microservice written in Java and a resource server under Ego with JWT authorization

Java Microservice Quickstart Template

Spring-Boot application preconfigured for to use EGO generated JWTs for authorization.

Features

This template provides the following:

• Spring-Boot Application with Spring Security
• JWT Authorization
• JWT Asymmetric Verification - fetches public-key from web on start-up
• JWT Filter - User Role and Status requirements implemented by default
• Docker and Docker-Compose configuration

Template Guide

Here is a convenient list of steps to create a new application based on this template:

1. Fork this!
2. Update pom.xml:
   • groupId
   • artifactId
   • name
   • description
3. Update application.yml:
   • auth.jwt.publicKeyUrl - URL to fetch the JWT verification key
4. Configure Codacy:
   • Go to Codacy Project Wizard and add your new repository.
5. Configure CircleCI:
   • Go to CircleCI Add Projects and add your project.
   • Go to CircleCI project settings and modify environment variables
     • If not there, add new environment variable: EGO_TEST_SERVER_KEY_URL . This should store the URL used for auth.jwt.publicKeyUrl value in CircleCI tests.
6. Update README.md:
   • Replace current README with template - README.template.md
   • Remove template file
   • Update Project name and description in new README
   • Update Shields in Introduction section
     • Codacy - Badge Markdown code can be found on Codacy project's settings page
     • CircleCI - Build from example using github organization, project, and branch names

Requirements

The application can be run locally or in a docker container, the requirements for each setup are listed below.

EGO

A running instance of EGO is required to generate the Authorization tokens and to provide the verification key.

EGO can be cloned and run locally if a public instance is not setup.

Local

• Java 8 SDK
• Maven

Docker

• Docker

Quick Start

Make sure the JWT Verification Key URL is configured, then you can run the server in a docker container or on your local machine.

Configure JWT Verification Key

Update application.yml. Set auth.jwt.publicKeyUrl to the URL to fetch the JWT verification key. The application will not start if it can't set the verification key for the JWTConverter.

The default value in the application.yml file is set to connect to EGO running locally on its default port 8081.

Run Local

$ mvn spring-boot:run

Application will run by default on port 1234

Configure the port by changing server.port in application.yml

Run Docker

First build the image:

$ docker-compose build

When ready, run it:

$ docker-compose up

Application will run by default on port 1234

Configure the port by changing services.api.ports in docker-compose.yml. Port 1234 was used by default so the value is easy to identify and change in the configuration file.

Test Endpoint

The application has a single endpoint /test that will accept GET and POST requests with a valid token.

A JWT must be passed in a request header, following the Bearer token pattern. Below is a usable value to test with, it is valid vs. the example keystore given in the EGO repo.

Authorization=Bearer eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MTI3NjIxODIsImV4cCI6MjE0NzQ4MzY0Nywic3ViIjoiNjA2IiwiaXNzIjoiZWdvIiwiYXVkIjpbXSwiY29udGV4dCI6eyJ1c2VyIjp7Im5hbWUiOiJEZW1vLlVzZXJAZXhhbXBsZS5jb20iLCJlbWFpbCI6IkRlbW8uVXNlckBleGFtcGxlLmNvbSIsInN0YXR1cyI6IkFwcHJvdmVkIiwiZmlyc3ROYW1lIjoiRGVtbyIsImxhc3ROYW1lIjoiVXNlciIsImNyZWF0ZWRBdCI6IjIwMTctMTEtMjIgMDM6MTA6NTUiLCJsYXN0TG9naW4iOiIyMDE3LTEyLTA4IDA3OjQzOjAyIiwicHJlZmVycmVkTGFuZ3VhZ2UiOm51bGwsInJvbGVzIjpbIlVTRVIiXX19LCJqdGkiOiI0OGE5NGIzNy1mMTJlLTQxNWQtYjM1Zi1kZDhmOThiMDQ4ZDcifQ.Cmgbd_xnUp8dPnIJvmUXmh5LYnHgHSk_n_0VzCn0k9r4WVNdsupb-MQqJvgOMg3K8si5mzhIjzLi9rZL5N_JwFXtpjKXKRVT7KF4mYfqF7bVNm6tkQg6CeAGhiuaMujhLhASS79LVBPKOv1tk79WuVu-VKHzyLS1h3yFQAsjLVQxA6_0MD7zKa1W3Nbhte6lHwgiNo1AlxuIJzP37-2saNb-aUy9DigmH3_C2oPqxpBu-YNnaekO5jNmbfucMinlpxCpEw-UvpvxI9Xk_9E73TNQE9acNQyyg_BxdnVbwDsR-kG5QXNrlEAxGm-1yY6w8Nvqxcp-3uoff6K0uKLUdQ

Test cURL requests:

curl -X GET \
 http://localhost:1234/test \
 -H 'authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MTI3NjIxODIsImV4cCI6MjE0NzQ4MzY0Nywic3ViIjoiNjA2IiwiaXNzIjoiZWdvIiwiYXVkIjpbXSwiY29udGV4dCI6eyJ1c2VyIjp7Im5hbWUiOiJEZW1vLlVzZXJAZXhhbXBsZS5jb20iLCJlbWFpbCI6IkRlbW8uVXNlckBleGFtcGxlLmNvbSIsInN0YXR1cyI6IkFwcHJvdmVkIiwiZmlyc3ROYW1lIjoiRGVtbyIsImxhc3ROYW1lIjoiVXNlciIsImNyZWF0ZWRBdCI6IjIwMTctMTEtMjIgMDM6MTA6NTUiLCJsYXN0TG9naW4iOiIyMDE3LTEyLTA4IDA3OjQzOjAyIiwicHJlZmVycmVkTGFuZ3VhZ2UiOm51bGwsInJvbGVzIjpbIlVTRVIiXX19LCJqdGkiOiI0OGE5NGIzNy1mMTJlLTQxNWQtYjM1Zi1kZDhmOThiMDQ4ZDcifQ.Cmgbd_xnUp8dPnIJvmUXmh5LYnHgHSk_n_0VzCn0k9r4WVNdsupb-MQqJvgOMg3K8si5mzhIjzLi9rZL5N_JwFXtpjKXKRVT7KF4mYfqF7bVNm6tkQg6CeAGhiuaMujhLhASS79LVBPKOv1tk79WuVu-VKHzyLS1h3yFQAsjLVQxA6_0MD7zKa1W3Nbhte6lHwgiNo1AlxuIJzP37-2saNb-aUy9DigmH3_C2oPqxpBu-YNnaekO5jNmbfucMinlpxCpEw-UvpvxI9Xk_9E73TNQE9acNQyyg_BxdnVbwDsR-kG5QXNrlEAxGm-1yY6w8Nvqxcp-3uoff6K0uKLUdQ'

curl -X POST \
  http://localhost:1234/test \
  -H 'authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MTI3NjIxODIsImV4cCI6MjE0NzQ4MzY0Nywic3ViIjoiNjA2IiwiaXNzIjoiZWdvIiwiYXVkIjpbXSwiY29udGV4dCI6eyJ1c2VyIjp7Im5hbWUiOiJEZW1vLlVzZXJAZXhhbXBsZS5jb20iLCJlbWFpbCI6IkRlbW8uVXNlckBleGFtcGxlLmNvbSIsInN0YXR1cyI6IkFwcHJvdmVkIiwiZmlyc3ROYW1lIjoiRGVtbyIsImxhc3ROYW1lIjoiVXNlciIsImNyZWF0ZWRBdCI6IjIwMTctMTEtMjIgMDM6MTA6NTUiLCJsYXN0TG9naW4iOiIyMDE3LTEyLTA4IDA3OjQzOjAyIiwicHJlZmVycmVkTGFuZ3VhZ2UiOm51bGwsInJvbGVzIjpbIlVTRVIiXX19LCJqdGkiOiI0OGE5NGIzNy1mMTJlLTQxNWQtYjM1Zi1kZDhmOThiMDQ4ZDcifQ.Cmgbd_xnUp8dPnIJvmUXmh5LYnHgHSk_n_0VzCn0k9r4WVNdsupb-MQqJvgOMg3K8si5mzhIjzLi9rZL5N_JwFXtpjKXKRVT7KF4mYfqF7bVNm6tkQg6CeAGhiuaMujhLhASS79LVBPKOv1tk79WuVu-VKHzyLS1h3yFQAsjLVQxA6_0MD7zKa1W3Nbhte6lHwgiNo1AlxuIJzP37-2saNb-aUy9DigmH3_C2oPqxpBu-YNnaekO5jNmbfucMinlpxCpEw-UvpvxI9Xk_9E73TNQE9acNQyyg_BxdnVbwDsR-kG5QXNrlEAxGm-1yY6w8Nvqxcp-3uoff6K0uKLUdQ'

If everything is working as expected, the request should return a pleasant greeting. ;)