17. June 2016
6 min

How to secure a web application with WildFly Swarm

What’s this blog post about?

The focus of this post is to create and secure a microservice with Java EE. More detailed, a simple REST application with JAX-RS is created with WildFly Swarm and security functionalities are added with Keycloak. The result will be a simple microservice and can be deployed on any Java platform.

What is WildFly Swarm?

That’s how the developers describe it: “…innovative approach to packaging and running Java EE applications by packaging them with just enough of the platform to java jar your application”.
My understanding in short: A simple way to create an individual microservice which can be run on any Java platform.

As described in its documentation, WildFly Swarm splits the WildFly Application Server into “fine-grained parts” called “fractions” and makes it possible to put those parts together to your application as so called “uberjars”. The “uberjar” is a self-contained and executable Java archive. So it’s nothing more than a standard jar file with your application, the required WildFly logic and the Buildfile with all dependencies. That means, if you only need JPA, JAX-RS and transactions within your application, you can select those fractions and include them in your maven dependencies (Note: Gradle is supported as well.) You want to add Logstash and Swagger? Then add it to your dependencies! You don’t need transactions? You just have to remove them! If you’re tired of manually adding dependencies to your Buildfile, you can also use the “WildFly Swarm Project Generator” and select all needed fractions for your application and download the result as a zip file.

What is Keycloak?

That’s how the developers describe it: “Keycloak is an SSO solution for web apps, mobile and RESTful web services. It is an authentication server where users can centrally login, logout, register, and manage their user accounts.”
My understanding in short: A way to secure your microservice with a lot of features (like SSO, Social Login,…).

Keycloak is built on top of the OAuth 2.0, Open ID Connect, JSON Web Token (JWT) and SAML 2.0 specifications. Main features are the centralized management of users/roles and the possibility to deploy it with an existing app server, as a black-box appliance, or as an Openshift cloud service. It provides Social Login capabilities, Single-Sign-On, LDAP integration and many more security functionalities (http://keycloak.jboss.org/). Note: The focus of this post is not to show all features of Keycloak, but only the ones needed to secure your microservice.

How to create your application?

Here are the steps to create a simple REST application with a standalone Keycloak Server:

  1. Navigate to http://wildfly-swarm.io/generator/
  2. Enter a Group ID and Artifact ID
  3. Enter and select the following dependencies: JAX-RS, Keycloak, Keycloak Server
  4. Click on “Generate Project” WildFly Swarm - project generator
  5. Download the zip file and unzip it in any directory of your choice
  6. Run “mvn wildfly-swarm:run”
  7. Navigate to http://localhost:8080/rest/hello and check the output message: Hello from WildFly Swarm!
  8. Congratulations! You have created a microservice with built-in security in just a few minutes.

What’s inside?

Let’s have look what’s inside the generated project and start with the pom.xml:

As you can see in line 6 the packaging is pre-configured as “war”. In the following lines you can see the plugin dependencies of WildFly Swarm, starting with the BOM (“Bill Of Materials”) dependency and the wildfly-swarm-plugin. That’s all! The last few lines are the dependencies for Java EE 7 and the ones you selected for the generator: JaxRS, Keycloak and Keycloak Server. Those are dependencies which are provided by the WildFly Swarm project and differ from the standard project dependencies:

The project also contains two Java classes. The RestApplication containing the ApplicationPath…

… and the HelloWorldEndpoint with the path and a simple GET operation:

Now it’s time to configure the built-in security!

How to secure your application?

Here are the steps to secure your application with Keycloak:

  1. Navigate to http://localhost:8080/auth
  2. Enter a username and password (2x times)
  3. Navigate to http://localhost:8080/auth/admin
  4. Login with your new user (Note: the user will be automatically added to the ‘admin’ role)
  5. Navigate to Clients WildFly Swarm - Keyclok - Clients
  6. Add a new client with the following data WildFly Swarm - Keycloak - Add Client Note: Clients are trusted browser apps and web services in a realm, which can request a login. In our example it is the path of the above created REST application which will be called via a web browser.
  7. Navigate to the “Installation” tab and select Format Option “Keycloak OIDC JSON” WildFly Swarm - Keycloak - Installation Note: This file is a client adapter configuration in JSON format and supports the OpenID Connect (OIDC) protocol which you can download or cut and paste to configure your clients.
  8. Click on download and save it to the src/main/webapp/WEB-INF directory of your unzipped project
  9. Add the following web.xml to the same directory (src/main/webapp/WEB-INF). It includes the definition of the authorization method “KEYCLOAK”:
  10. Stop your previous execution in the terminal (Ctrl + C)
  11. Run “mvn package” and “mvn wildfly-swarm:run” or “java -jar security-swarm.jar” in the “target” directory of your project.
  12. Navigate to http://localhost:8080/rest/hello, enter your credentials and look at the message: Hello from WildFly Swarm!
  13. You’re done! You just secured your application with Keycloak.

What’s next?

It’s up to you! With the work done so far it is possible to extend your microservice with more functionalities: Let’s think of log analysis with Logstash or persisting data with JPA or UI elements with JSF. Keep in mind that you can deploy your project anywhere and everywhere conform to the microservice “guidelines”. The focus of this post was just to show you one way to create and secure a microservice with WildFly Swarm and Keycloak. The concept of WildFly Swarm, to split the application server to “fractions”, is a great approach towards microservices and is in my opinion a concept with future potential. With Keycloak you can secure your application and provide further security functionalities, but admittedly it is not the most lightweight solution if you only need basic authentication. Therefore in one of my next posts I will show you a more lightweight solution to secure web applications.

Comment article


  1. Duygu Kücük

    Hi Simon,

    unfortunately the source is not available on GitHub, but you can easily generate the introduced sample application with the project generator.
    You can find the default main class in org.wildfly.swarm.Swarm. Please also refer to the documentation (No User-Provided main(…))

  2. Simon

    Is the source available on github? I would like to see the main class of this program.