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:
$ cd bin $ ./standalone.sh -Djboss.socket.binding.port-offset=100
> ...\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
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.
$ cd bin $ ./standalone.sh
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
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.
$ 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.
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
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:
- Log in to the admin console with your admin account.
In the top left drop-down menu select and manage the
Clientsin the left side menu to open the Clients page.
- On the right side, click Create.
Complete the fields as shown here:
- Click Save to create the client application entry.
- Click the Installation tab in the Red Hat Single Sign-On admin console to obtain a configuration template.
Select Keycloak OIDC JBoss Subsystem XML to generate an XML template. Copy the contents for use in the next section.
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.
standalone/configuration/standalone.xmlfile in the JBoss EAP instance that the application is deployed on and search for the following text:
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>
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>
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"> <secure-deployment name="vanilla.war"> ... </subsystem>
- Reboot the application server.
- 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.