Chapter 3. Using Red Hat Single Sign-On with Spring Boot

Red Hat Single Sign-On client adapters are libraries that make it very easy to secure applications and services with Red Hat Single Sign-On. You can use the Keycloak Spring Boot adapter to secure your Spring Boot project.

3.1. Using Red Hat Single Sign-On with Spring Boot Container

To secure a Spring Boot application, add the Keycloak Spring Boot adapter JAR to your project. The Keycloak Spring Boot adapter takes advantage of Spring Boot’s autoconfiguration feature so all you need to do is add the Keycloak Spring Boot starter to your project.

Procedure

  1. To manually add the Keycloak Spring Boot starter, add the following to your project’s pom.xml. 

    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-spring-boot-starter</artifactId>
</dependency>

  2. Add the Adapter BOM dependency. 

    <dependencyManagement>
  <dependencies>
        <dependency>
          <groupId>org.keycloak.bom</groupId>
          <artifactId>keycloak-adapter-bom</artifactId>
          <version>3.4.17.Final-redhat-00001</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
  </dependencies>
</dependencyManagement>

  3. Configure your Spring Boot project to use Keycloak. Instead of a keycloak.json file, you can configure the realm for the Spring Boot Keycloak adapter using the normal Spring Boot configuration. For example, add following configuration to src/main/resources/application.properties file. 

    keycloak.realm = demorealm
keycloak.auth-server-url = http://127.0.0.1:8080/auth
keycloak.ssl-required = external
keycloak.resource = demoapp
keycloak.credentials.secret = 11111111-1111-1111-1111-111111111111
keycloak.use-resource-role-mappings = true

    You can disable the Keycloak Spring Boot Adapter (for example in tests) by setting keycloak.enabled = false. To configure a Policy Enforcer, unlike keycloak.json, policy-enforcer-config must be used instead of just policy-enforcer.

  4. Specify the Java EE security configuration in the web.xml. The Spring Boot Adapter will set the login-method to KEYCLOAK and configure the security-constraints at the time of startup. An example configuration is given below. 

    keycloak.securityConstraints[0].authRoles[0] = admin
keycloak.securityConstraints[0].authRoles[1] = user
keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff
keycloak.securityConstraints[0].securityCollections[0].patterns[0] = /insecure


keycloak.securityConstraints[1].authRoles[0] = admin
keycloak.securityConstraints[1].securityCollections[0].name = admin stuff
keycloak.securityConstraints[1].securityCollections[0].patterns[0] = /admin

    Note: If you plan to deploy your Spring Application as a WAR then do not use the Spring Boot Adapter. Use the dedicated adapter for the application server or servlet container you are using. Your Spring Boot should also contain a web.xml file.

3.2. Build and deploy Spring Boot CXF JAXRS Keycloak quickStart

This example demonstrates how you can use Apache CXF JAXRS which is secured by Keycloak with Spring Boot. The quickstart uses Spring Boot to configure an application that includes a CXF JAXRS endpoint with Swagger enabled, which is secured by Keycloak. You can run this quickstart in the standalone mode.

Note

This is an upstream demo with no support from Red Hat. See section Using Spring Boot BOM in the Deploying into Spring Boot guide

Procedure

To run this quickstart as a standalone project on your local machine:

  1. Download the Spring Boot CXF JAXRS Keycloak quickstart[https://github.com/ffang/spring-boot-cxf-keycloak] and extract the archive on your local filesystem.

  2. Navigate to the quickstart directory and build the project. 

    cd PROJECT_DIR
mvn clean package

  3. Run the following command to build and deploy the Spring Boot CXF JAXRS Keycloak quickstart. 

    mvn spring-boot:run

    This starts the Keycloak auth server with predefined configuration (./src/main/resources/keycloak-config/realm-export-new.json) along with CXF JAXRS SB2 endpoint.

  4. You can then access the CXF JAXRS endpoint directly from your web browser, for example, open http://localhost:8080/services/helloservice/sayHello/FIS to access the endpoint. Since the CXF JAXRS endpoint is secured by Keycloak, this will redirect request to Keycloak auth server.
  5. Enter admin as the username and passw0rd as the password. This fetches the OAuth2 JWT token and redirects to the CXF JAXRS endpoint. You can see Hello FIS, Welcome to CXF RS Spring Boot World!!! message on the browser.