The RH-SSO server .zip file contains the scripts and binaries to run the RH-SSO server. The procedure to install RH-SSO in a RHEL platform from a .zip file is the following:

There are some key differences between the containerized version of RH-SSO and the one installed on bare metal or virtualized machines.

The first one is the start method. There is no choice between stand-alone and domain mode in a containerized RH-SSO instance, because the task of configuring and controlling the server instance is delegated to the Red Hat OpenShift scheduler, the container image start parameters, and the scripts that execute the start procedure.

Additionally, these scripts generate all relevant configuration files by using environment variables in the containerized version, and you cannot edit the files directly.

Being a level 3 operator, the RH-SSO operator must be able to automate provisioning, manage configuration, perform patches and minor version upgrades, and perform scheduled backups of data. The RH-SSO operator achieves all these operations by means of various custom resources, which are covered in more detail later in this course.

RH-SSO comes with its own H2 Java-based in-memory relational database. This database is only for testing purposes, because it is not viable in high concurrency situations. Thus, Red Hat recommends to replace it by a production ready external database when deploying RH-SSO in real environments. You can connect RH-SSO to relational databases by using Java Database Connectivity (JDBC) with the JDBC drivers provided by database vendors.

The procedure to configure RH-SSO to connect to an external database needs the following steps:

You can also create a JBoss CLI script to automate the previous steps. The following example is a JBoss CLI script to connect to a PostgreSQL database. This script declares the JDBC driver in the datasources subsystem and modifies the existing datasource configuration to connect it to the external database.

batch

set DB_USERNAME=<db_username> 
set DB_PASSWORD=<db_password>
set DRIVER_NAME=postgres
set DRIVER_MODULE_NAME=org.postgres
set XA_DATABASESOURCE_CLASS="org.postgresql.xa.PGXADataSource"
set CONNECTION_URL="jdbc:postgresql://<postgres_ip>:5432/keycloak"
set FILE=<postgresql-jar-path>

embed-server --std-out=echo

module add --name=$DRIVER_MODULE_NAME --resources=$FILE --dependencies=javax.api,javax.resource.api 

/subsystem=datasources/jdbc-driver=$DRIVER_NAME:add( \ 
  driver-name=$DRIVER_NAME, \
  driver-module-name=$DRIVER_MODULE_NAME, \
  xa-datasource-class=$XA_DATABASESOURCE_CLASS \
)

/subsystem=datasources/data-source=KeycloakDS:remove() 
/subsystem=datasources/data-source=KeycloakDS:add( \
  jndi-name=java:jboss/datasources/KeycloakDS, \
  enabled=true, \
  use-java-context=true, \
  connection-url=$CONNECTION_URL, \
  driver-name=$DRIVER_NAME, \
  user-name=$DB_USERNAME, \
  password=$DB_PASSWORD \
)

/subsystem=elytron/key-store=httpsKS:add(relative-to=jboss.server.config.dir,path=sso.lab.example.com.p12,credential-reference={clear-text=redhat123},type=PKCS12) 
/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=redhat123})
/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2", "TLSv1.3"])
/subsystem=elytron/server-ssl-context=httpsSSC:write-attribute(name=cipher-suite-names,value=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:
TLS_AES_128_GCM_SHA256)
/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=httpsSSC)
/socket-binding-group=standard-sockets/socket-binding=http:write-attribute(name=port, value=8443)
/socket-binding-group=standard-sockets/socket-binding=https:write-attribute(name=port, value=8080)

run-batch

After creating the JBoss CLI script, you can run it by using the JBoss management CLI to connect to the external database.

[rhsso@sso rh-sso-7.6]$ bin/jboss-cli.sh \
  --file=/opt/rh-sso-7.6/bin/sso-extensions.cli
...output omitted...

By default, RH-SSO binds to the local host loop back address 127.0.0.1. Thus, the authentication and authorization server is only available on the local machine. If you want RH-SSO to be available on your network, then you must set the bind address.

You can set the bind address by modifying the jboss.bind.address system property on the XML configuration file. For example, for the stand-alone mode you can set the bind address in the interfaces XML block in the standalone/configuration/standalone.xml file:

    ...output omitted...
    <interfaces>
        <interface name="management"> 
            <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
        </interface>
        <interface name="public"> 
            <inet-address value="${jboss.bind.address:127.0.0.1}"/>
        </interface>
    </interfaces>
    ...output omitted...

You can also set the bind address manually from the command line when booting your RH-SSO instance by using the -Djboss.bind.address option:

[rhsso@sso rh-sso-7.6]$ bin/standalone.sh -Djboss.bind.address=192.168.0.20
...output omitted...

By default, RH-SSO uses port 8080 for HTTP connections and port 8443 for HTTPS connections. You can set the socket port binding by modifying the jboss.http.port and jboss.https.port system properties on the XML configuration file. For example, for the stand-alone mode you can set the socket port binding in the socket-binding-group XML block in the standalone/configuration/standalone.xml file:

    ...output omitted...
    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>
        <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
        <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="${jboss.mail.server.host:localhost}" port="${jboss.mail.server.port:25}"/>
        </outbound-socket-binding>
    </socket-binding-group>
    ...output omitted...

You can also set the socket port binding manually from the command line when booting your RH-SSO instance by using the -Djboss.http.port and -Djboss.https.port options:

[rhsso@sso rh-sso-7.6]$ bin/standalone.sh -Djboss.http.port=1234
...output omitted...

You can find the boot scripts for the different RH-SSO operating modes in the bin directory. For example, you can run an RH-SSO stand-alone instance by running the standalone.sh boot script.

[rhsso@sso rh-sso-7.6]$ bin/standalone.sh
...output omitted...
15:08:15,900 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Red Hat Single Sign-On 7.6.0.GA (WildFly Core 15.0.8.Final-redhat-00001) started in 9475ms - Started 594 of 872 services (584 services are lazy, passive or on-demand)
15:08:15,903 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/management
15:08:15,903 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990

If the boot script runs correctly, then you can access the administration console by using a web browser to navigate to the RH-SSO web UI URL at http://localhost:8080. You can choose the RH-SSO XML configuration file to start with by using the -c parameter, like the following example.

[rhsso@sso rh-sso-7.6]$ bin/standalone.sh -c standalone-ha.xml
...output omitted...

There are two ways to set the administrator account for your RH-SSO instance.

If your server is accessible from the localhost URL or the address that you manually configured, then you can use the web UI for setting the administrator password. In that case, use your web browser to navigate to the RH-SSO web UI URL (by default https://localhost:8080/auth). The first time you navigate to the RH-SSO web UI URL, it asks you to enter the initial administrator username and the password.

Figure 2.1: RH-SSO Web UI Initial Screen

If you cannot access the server from the localhost address or you want to set the administrator password from the command line, then you can use the bin/add-user-keycloak.sh script to add administrator users. This script requires you to specify the username and the password for the admin user.

[rhsso@sso rh-sso-7.6]$ bin/add-user-keycloak.sh -u <username> -p <password>

If you use RH-SSO on bare metal or virtualized infrastructures, then Red Hat recommends to install the RH-SSO instances as UNIX system daemons, or Windows services, depending on the operating system family. This lecture explains only how to configure the system service on RHEL.

Similar to a JBoss EAP server instance, you can configure RH-SSO as a service that starts on boot.

For this purpose, you need to customize the start options in the JBoss configuration file. You can find the JBoss configuration file and the start script in the bin/init.d directory.

First, modify the JBoss configuration file with the parameters that apply to your RH-SSO deployment. At least you must provide the values for the JBOSS_HOME and the JBOSS_USER variables.

[rhsso@sso rh-sso-7.6]$ cat bin/init.d/jboss-eap.conf
# General configuration for the init.d scripts,
# not necessarily for JBoss EAP itself.
# default location: /etc/default/jboss-eap

## Location of JDK
# JAVA_HOME="/usr/lib/jvm/default-java"

## Location of JBoss EAP
# JBOSS_HOME="/opt/jboss-eap"

## The username who should own the process.
# JBOSS_USER=jboss-eap

## The mode JBoss EAP should start, standalone or domain
# JBOSS_MODE=standalone

## Configuration for standalone mode
# JBOSS_CONFIG=standalone.xml

## Configuration for domain mode
# JBOSS_DOMAIN_CONFIG=domain.xml
# JBOSS_HOST_CONFIG=host-master.xml

## The amount of time to wait for startup
# STARTUP_WAIT=60

## The amount of time to wait for shutdown
# SHUTDOWN_WAIT=60

## Location to keep the console log
# JBOSS_CONSOLE_LOG="/var/log/jboss-eap/console.log"

## Additionals args to include in startup
# JBOSS_OPTS="--admin-only -b 127.0.0.1"

After editing the JBoss configuration file, copy it to the /etc/default directory.

[rhsso@sso rh-sso-7.6]$ sudo cp EAP_HOME/bin/init.d/jboss-eap.conf /etc/default

Then, copy the service start script to the /etc/init.d directory, give it execute permissions, and restore its SELinux context.

[rhsso@sso rh-sso-7.6]$ sudo cp EAP_HOME/bin/init.d/jboss-eap-rhel.sh /etc/init.d
[rhsso@sso rh-sso-7.6]$ sudo chmod +x /etc/init.d/jboss-eap-rhel.sh
[rhsso@sso rh-sso-7.6]$ sudo restorecon /etc/init.d/jboss-eap-rhel.sh

Use the service management command to add the jboss-eap-rhel.sh service to the list of automatically started services, and reload the systemd daemon. Then, verify that the service starts correctly by starting it.

[rhsso@sso rh-sso-7.6]$ sudo chkconfig --add jboss-eap-rhel.sh
[rhsso@sso rh-sso-7.6]$ sudo systemctl daemon-reload
[rhsso@sso rh-sso-7.6]$ sudo service jboss-eap-rhel start
Redirecting to /bin/systemctl start jboss-eap-rhel.service

Finally, make the service start automatically on boot.

[rhsso@sso rh-sso-7.6]$ sudo chkconfig jboss-eap-rhel.sh on