Chapter 4. Securing a JBoss Servlet Application

This section describes how to secure a Java servlet application on the JBoss EAP application server by:

  • Installing the Red Hat Single Sign-On client adapter on a JBoss EAP application server distribution
  • Creating and registering a client application in the Red Hat Single Sign-On admin console
  • Configuring the application to be secured by Red Hat Single Sign-On

4.1. Before You Start

Before you can secure a Java servlet application, you must complete the installation of Red Hat Single Sign-On and create the initial admin user as shown in Installing and Booting.

There is one caveat: Even though JBoss EAP is bundled with Red Hat Single Sign-On, you cannot use this as an application container. Instead, you must run a separate JBoss EAP instance on the same machine as the Red Hat Single Sign-On server to run your Java servlet application. Run the Red Hat Single Sign-On using a different port than the JBoss EAP, to avoid port conflicts.

To adjust the port used, change the value of the jboss.socket.binding.port-offset system property when starting the server from the command line. The value of this property is a number that will be added to the base value of every port opened by the Red Hat Single Sign-On server.

To start the Red Hat Single Sign-On server while also adjusting the port:

Linux/Unix

$ cd bin
$ ./standalone.sh -Djboss.socket.binding.port-offset=100

Windows

> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100

After starting Red Hat Single Sign-On, go to http://localhost:8180/auth/admin/ to access the admin console.

4.2. Installing the Client Adapter

Download the JBoss EAP distribution and extract it from the compressed file into a directory on your machine.

Download the RH-SSO-7.3.1.GA-eap7-adapter.zip distribution.

Extract the contents of this file into the root directory of your JBoss EAP distribution.

Run the appropriate script for your platform:

EAP 6.3 and Linux/Unix

$ cd bin
$ ./jboss-cli.sh --file=adapter-install-offline.cli

EAP 6.3 and Windows

> cd bin
> jboss-cli.bat --file=adapter-install-offline.cli

EAP 7.2.5 and Linux/Unix

$ cd bin
$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli

EAP 7.2.5 and Windows

> cd bin
> jboss-cli.bat --file=adapter-elytron-install-offline.cli

Note

This script will make the necessary edits to the …​/standalone/configuration/standalone.xml file of your app server distribution and may take some time to complete.

Start the application server.

Linux/Unix

$ cd bin
$ ./standalone.sh

Windows

> ...\bin\standalone.bat

4.3. Downloading, Building, and Deploying Application Code

You must have the following installed on your machine and available in your PATH before you continue:

  • Java JDK 8
  • Apache Maven 3.1.1 or higher
  • Git
Note

You can obtain the code by cloning the repository at https://github.com/redhat-developer/redhat-sso-quickstarts. Use the branch matching the version of Red Hat Single Sign-On in use.

Make sure your JBoss EAP application server is started before you continue.

To download, build, and deploy the code, complete the following steps.

Clone Project

$ git clone https://github.com/redhat-developer/redhat-sso-quickstarts
$ cd redhat-sso-quickstarts/app-profile-jee-vanilla
$ mvn clean wildfly:deploy

During installation, you will see some text scroll by in the application server console window.

To confirm that the application is successfully deployed, go to http://localhost:8080/vanilla and a login page should appear.

Note

If you click Login, the browser will pop up a BASIC auth login dialog. However, the application is not yet secured by any identity provider, so anything you enter in the dialog box will result in a Forbidden message being sent back by the server. You can confirm that the application is currently secured via BASIC authentication by finding the setting in the application’s web.xml file.

4.4. Creating and Registering the Client

To define and register the client in the Red Hat Single Sign-On admin console, complete the following steps:

  1. Log in to the admin console with your admin account.
  2. In the top left drop-down menu select and manage the Demo realm. Click Clients in the left side menu to open the Clients page.

    Clients

    clients

  3. On the right side, click Create.
  4. Complete the fields as shown here:

    Add Client

    add client

  5. Click Save to create the client application entry.
  6. Click the Installation tab in the Red Hat Single Sign-On admin console to obtain a configuration template.
  7. Select Keycloak OIDC JBoss Subsystem XML to generate an XML template. Copy the contents for use in the next section.

    Template XML

    client install selected

4.5. Configuring the Subsystem

To configure the JBoss EAP instance that the application is deployed on so that this app is secured by Red Hat Single Sign-On, complete the following steps.

  1. Open the standalone/configuration/standalone.xml file in the JBoss EAP instance that the application is deployed on and search for the following text:

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
  2. Modify this text to prepare the file for pasting in contents from the Keycloak OIDC JBoss Subsystem XML template we obtained Red Hat Single Sign-On admin console Installation tab by changing the XML entry from self-closing to using a pair of opening and closing tags:

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    </subsystem>
  3. Paste the contents of the template within the <subsystem> element, as shown in this example:

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
      <secure-deployment name="WAR MODULE NAME.war">
        <realm>demo</realm>
        <auth-server-url>http://localhost:8180/auth</auth-server-url>
        <public-client>true</public-client>
        <ssl-required>EXTERNAL</ssl-required>
        <resource>vanilla</resource>
      </secure-deployment>
    </subsystem>
  4. Change the name to vanilla.war:

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
      <secure-deployment name="vanilla.war">
      ...
    </subsystem>
  5. Reboot the application server.
  6. Go to http://localhost:8080/vanilla and click Login. When the Red Hat Single Sign-On login page opens, log in using the user you created in Creating a New User.