Difficulty: beginner
Estimated Time: 15 minutes

In this scenario you will learn more about developing Spring Boot Microservices using the Red Hat OpenShift Application Runtimes platform. You will learn about how to implement Single Sign-On (SSO) using KeyCloak and Spring Security.

How is Spring Boot supported on OpenShift?

Spring is one of the most popular Java Frameworks and offers an alternative to the Java EE programming model. Spring is also very popular for building applications based on a microservices Architecture due to Spring's support for packaging applications into self-contained, deployable JAR files. For web applications, Spring Boot can embed a servlet container, like Apache Tomcat. This allows for the creation of a self-sufficient JAR file which can be deployed and run without external tools (other than the Java Runtime of course!). These bootable applications (sometimes also called fat JARs or über JARs) fit the container model very well because the starting, stopping, and monitoring of an application is handled by the container platform (e.g., OpenShift), instead of an application server. Additionally, a container definition is simpler compared to deploying a war file.

Red Hat tests and certifies a certain version of Spring and Spring Boot for usage on the OpenShift platform as part of Red Hat OpenShift Application Runtimes. Red Hat also provides full support for Apache Tomcat, Hibernate and Apache CXF (for REST services) when used in a Spring Boot application on OpenShift Application Runtimes.

In this scenario you learned about Spring Boot and how it can be used to enable Single Sign-On using KeyCloak. We will add additional scenarios that explain more how to build Spring Boot applications on OpenShift shortly, so check back to learn.openshift.com

To summarize: TODO

Spring Boot is a powerful and easy to use framework for developing everything from monolithic applications to microservices, but Spring Boot becomes every better when we package it in a container and use an orchestrated platform like OpenShift. When using OpenShift we can, in a very consistent and fast way, deploy our Spring application to multiple environments without worry of environment differences. OpenShift also enables things like Deployment Pipelines and Blue/Green deployments but that was not covered in this scenario.

Additional Resources

More background and related information on Red Hat OpenShift Application Runtimes and Eclipse Vert.x can be found here:

  • Red Hat OpenShift Application Runtimes for Developers - Here you can get started with a project using different boosters and clone that project to your local computer. This also enables you to deploy your application on your own private OpenShift Container Platform or use OpenShift Online that is provided for free from Red Hat.
  • Project Snowdrop homepage - This site has a lot of details of the work that Red Hat is doing to make Spring work great on Kubernetes and OpenShift.

SSO with KeyCloak

Step 1 of 6

Step 1

Review the base structure of the application

For your convenience, this scenario has been created with a base project using the Java programming language and the Apache Maven build tool. The base project contains an application with unprotected resources.

This project already includes everything you need. Start by reviewing the base project's content by executing a tree in your terminal.

The output should look something like this:

├── config
│   └── realm.json
├── pom.xml
└── src
    └── main
        ├── fabric8
        │   ├── deployment.yml
        │   ├── keycloak.json
        │   ├── postgresql.json
        │   └── route.yml
        ├── java
        │   └── com
        │       └── example
        │           ├── Application.java
        │           └── service
        │               ├── SecurityConfig.java
        │               └── WebController.java
        └── resources
            └── templates
                ├── external.html
                ├── layout.html
                └── secured.html

Except for the fabric8 directory and the index.html, this matches what you would get if you generated an empty project using the Spring Initializr. For the moment you can ignore the content of the fabric8 folder (we will discuss this later).

One thing that differs slightly is the pom.xml file.

As you review the content, you will notice that there are a couple of TODO comments. Do not remove them! These comments are used as markers for later exercises in this scenario.

Notice that the Keycloak Adapter dependency has already been configured.


1. Test the application locally

As we develop the application we want to be able to test and verify our change at different stages. One way we can do that locally is by using the spring-boot maven plugin.

Run the application by executing the following command:

mvn spring-boot:run -DskipTests -Psolution

Click on the Web browser link and you should see the unsecured view of the spring-boot application.

NOTE: The Katacoda terminal window is like your local terminal. Everything that you run here you should be able to execute on your local computer as long as you have Java SDK 1.8 and Maven installed. In later steps, we will also use the oc command line tool for OpenShift commands.

2. Verify the application

You will eventually see a output similar to Started Application in 4.497 seconds (JVM running for 9.785). Open the application by clicking on the Local Web Browser tab or clicking here.

You should now see an HTML page with the SSO with KeyCloak welcome message. If you see this then you've successfully set up the application! If not check the logs in the terminal. Spring Boot adds helper layers to catch common errors and print helpful messages to the console.

Now click on the click here link under Secured Resource. The page will not load because there isn't an instance of Keycloak running yet. We will configure Keycloak in the next section and set it up so that the secured resource can be accessed after logging in through Keycloak.

4. Stop the application

Before moving on, click in the terminal window and then press ctrl-c.


You have now successfully executed the first step in this scenario. In the next step we will

Local Web Browser
OpenShift Console