Getting Started Guide

The Red Hat Single Sign-On Server is contained in one distribution file:

The 'RH-SSO-7.0.0.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries to run the Red Hat Single Sign-On server.

To unpack these files run the unzip or gunzip and tar utilities.

To boot the Red Hat Single Sign-On server, go to the bin/ directory of the server distribution.

To boot the server:

$ .../bin/standalone.sh

> ...\bin\standalone.bat

After the server boots, open your browser and go to the http://localhost:8080/auth URL. The page should look like this:

Red Hat Single Sign-On does not have any configured admin account out of the box. You must create one on the Welcome Page. This account will allow you to create an admin that can log into the master realm’s administration console so that you can start creating realms, users and registering applications to be secured by Red Hat Single Sign-On.

After you create the initial admin account, click on the Administration Console link on the bottom of the Welcome Page. Alternatively you can go to the console url directly at http://localhost:8080/auth/admin/

Enter the username and password you created on the Welcome Page. This will bring you to the Red Hat Single Sign-On Admin Console.

Before you can participate in this tutorial, you need to complete the installation of Red Hat Single Sign-On and create the initial admin user as shown in the Install and Boot tutorial.

Login to the Red Hat Single Sign-On Admin Console using the account you created in the Install and Boot tutorial.

Place the mouse over the top left corner drop down menu that is titled with Master. If you are logged in the master realm this drop down menu lists all the realms created. The last entry of this drop down menu is always Add Realm. Click this to add a realm.

This menu option will bring you to the Add Realm page. You will be creating a brand new realm from scratch so enter in demo for the realm name and click Create.

After creating the realm you are brought back to the main Admin Console page. The current realm will now be set to demo. You can switch between managing the master realm and the realm you just created by doing a mouseover on the top left corner drop down menu.

In this section you are going to create a new user in the demo realm as well as a temporary password for that account. The first step is to click on the Users in the left menu bar.

This menu option brings you to the user list page. On the right side of the empty user list, you should see an Add User button. Click that to start creating your new user.

The only required field is Username. Click save. This will bring you to the management page for your new user.

The next step is to define a temporary password for your new user. Click on the Credentials tab to bring you to the page that will allow you to do this.

Enter a new password and retype it within the Password Confirmation field. Once you do this a red Reset Password button should reappear. Clicking on that will reset the user’s password to the new one you specified. Please note that this is a temporary password and the user will be required to change it after they first log in. You can make it permanent by flipping the Temporary switch from On to Off before you click the Reset Password button.

After creating the user, logout of the management console by clicking the right hand drop down menu and selecting Sign Off. Next, login to the User Account Service of your demo realm with the user you just created by clicking this link:

Enter the username and temporary password you created. You will be asked to change and create a permanent password after you successfully login.

Finally, you will be brought to the User Account Service. Every user in a realm has access to this Account Service by default. It allows you to update profile information and change or add additional credentials. More information on this service is provided in the Server Administration Guide.

Before you can participate in this tutorial, you need to complete the installation of Red Hat Single Sign-On and create the initial admin user as shown in the Install and Boot tutorial. There is one caveat to this. You have to run a separate JBoss EAP 7 instance on the same machine as the Red Hat Single Sign-On server. This separate instance will run your Java Servlet application. Because of this you will have to run the Red Hat Single Sign-On under a different port so that there are no port conflicts when running on the same machine. Use the jboss.socket.binding.port-offset system property on 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 boot the Red Hat Single Sign-On server:

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

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

After booting up Red Hat Single Sign-On, you can then access the admin console at http://localhost:8180/auth/admin/

Download the JBoss EAP 7 distribution and unzip it into a directory on your machine.

Next download the RH-SSO-7.0.0-eap7-adapter.zip distribution.

Unzip this file into the root directory of your JBoss EAP 7 distribution.

Next perform the following actions:

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

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

This script will make the appropriate edits to the …​/standalone/configuration/standalone.xml file of your app server distribution. Finally, just boot the application server.

$ .../bin/standalone.sh

> ...\bin\standalone.bat

The project and code for the application you are going to secure is available in Red Hat Developers GitHub. You will need the following installed on your machine and available in your PATH before you can continue:

You can obtain the code by cloning the repository at https://github.com/redhat-developer/redhat-sso-quickstarts. Follow these steps to download the code, build it, and deploy it. Make sure your JBoss EAP 7 application server is started before you run these steps.

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

You should see some text scroll down in the application server console window. After the application is successfully deployed go to:

http://localhost:8080/vanilla

If you open up the application’s web.xml file you would see that the application is secured via BASIC authentication. If you click on the login button on the login page, the browser will pop up a BASIC auth login dialog.

The application is not 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. The next section describes how you can take this deployed application and secure it.

The next step you have to do is to define and register the client in the Red Hat Single Sign-On Admin Console. Log into the Admin Console with your admin account as you did in previous tutorials. In the top left hand drop down menu select and manage the demo realm. Click Clients in the left side menu. This will bring you to the Clients page.

On the right hand side you should see a button named Create. Click this button and fill in the fields as shown below:

After clicking the Save button your client application entry will be created. You now have to go back to the JBoss EAP 7 instance that the application is deployed on and configure it so that this app is secured by Red Hat Single Sign-On. You can obtain a template for the configuration you need by going to the Installation tab in the client entry in the Red Hat Single Sign-On Admin Console.

Select the Keycloak OIDC JBoss Subsystem XML option. This will generate an XML template that you’ll need to cut and paste.

Now that you have copied the XML template from the Installation tab, you need to paste this into the standalone.xml file that lives in the standalone/configuration directory of the application server instance your application is deployed on. Open this file and search for the following text:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>

Modify this a little bit to prepare it for pasting in your template from the Installation tab.

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
</subsystem>

Within the subsystem element, paste in the template. It will look something like this:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="WAR MODULE NAME.war">
    <realm>demo</realm>
    <realm-public-key>MIIBIjANBgkqhkiG9B</realm-public-key>
    <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>

Change the WAR MODULE NAME text to be vanilla as follows:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="vanilla.war">
  ...
</subsystem>

Reboot your application’s server and now when you visit http://localhost:8080/vanilla and hit the login button, you should get the Red Hat Single Sign-On login page. You can log in using the user you created in the Create New User chapter.