Chapter 4. Advanced Concepts

These cover additional configuration topics, such as seting up keystores and a truststore for the RH-SSO server, creating an administrator account, an overview of available RH-SSO client registration methods, and guidance on configuring clustering.

4.2. Creating Administrator Account for Red Hat Single Sign-On Server

Red Hat Single Sign-On does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the master realm’s management console and perform server maintenance operations such as, creating realms or users, or registering applications intended to be secured by Red Hat Single Sign-On.

The administrator account can be created:

Note

Red Hat Single Sign-On allows an initial administrator account to be created via the Welcome Page web form, but only if the Welcome Page is accessed from localhost; this method of administrator account creation is not applicable for the RH-SSO for OpenShift image.

4.2.1. Creating RH-SSO Administrator Account via Template Parameters

When deploying RH-SSO application template, SSO_ADMIN_USERNAME and SSO_ADMIN_PASSWORD parameters denote the username and password of the RH-SSO server’s administrator account to be created for the master realm.

Note

Both of these parameters are required. If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated.

Important

The lifespan of the RH-SSO server’s administrator account depends upon the the storage type used to store the RH-SSO server’s database:

  • For an in-memory database mode (sso72-https and sso72-x509-https templates) the account exists throughout the lifecycle of the particular RH-SSO pod (stored account data is lost upon pod destruction),
  • For an ephemeral database mode (sso72-mysql and sso72-postgresql templates) the account exists throughout the lifecycle of the database pod (even if the RH-SSO pod is destructed, the stored account data is preserved under the assumption that the database pod is still running),
  • For persistent database mode (sso72-mysql-persistent, sso72-x509-mysql-persistent, sso72-postgresql-persistent, and sso72-x509-postgresql-persistent templates) the account exists throughout the lifecycle of the persistent medium used to hold the database data. This means that the stored account data is preserved even when both the RH-SSO and the database pods are destructed.

It is a common practice to deploy an RH-SSO application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new RH-SSO application needs to be instantiated).

Warning

In the case of ephemeral or persistent database mode, after creating the RH_SSO server’s administrator account, remove the SSO_ADMIN_USERNAME and SSO_ADMIN_PASSWORD variables from the deployment config before deploying new RH-SSO applications.

Important

Run the following commands to prepare the previously created deployment config of the RH-SSO application for reuse after the administrator account has been created:

  1. Identify the deployment config of the RH-SSO application.

    $ oc get dc -o name
    deploymentconfig/sso
    deploymentconfig/sso-mysql
  2. Clear the SSO_ADMIN_USERNAME and SSO_ADMIN_PASSWORD variables setting.

    $ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD=""

4.2.2. Creating RH-SSO Administrator Account via Remote Shell Session to RH-SSO Pod

Run following commands to create an administrator account for the master realm of the RH-SSO server, when deploying the RH-SSO for OpenShift image directly from the image stream (without the template), after the RH-SSO application pod has been started:

  1. Identify the RH-SSO application pod.

    $ oc get pods
    NAME                READY     STATUS    RESTARTS   AGE
    sso-12-pt93n        1/1       Running   0          1m
    sso-mysql-6-d97pf   1/1       Running   0          2m
  2. Open a remote shell session to the RH-SSO for OpenShift container.

    $ oc rsh sso-12-pt93n
    sh-4.2$
  3. Create the RH-SSO server administrator account for the master realm at the command line with the add-user-keycloak.sh script.

    sh-4.2$ cd /opt/eap/bin/
    sh-4.2$ ./add-user-keycloak.sh -r master -u sso_admin -p sso_password
    Added 'sso_admin' to '/opt/eap/standalone/configuration/keycloak-add-user.json', restart server to load user
    Note

    The sso_admin/sso_password credentials in the example above are for demonstration purposes only. Refer to the password policy applicable within your organization for guidance on how to create a secure user name and password.

  4. Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly.

    sh-4.2$ ./jboss-cli.sh --connect ':reload'
    {
        "outcome" => "success",
        "result" => undefined
    }
    Warning

    When restarting the server it is important to restart just the JBoss EAP process within the running RH-SSO container, and not the whole container. This is because restarting the whole container will recreate it from scratch, without the RH-SSO server administration account for the master realm.

  5. Log in to the master realm’s administration console of the RH-SSO server using the the credentials created in the steps above. In the browser, navigate to http://sso-<project-name>.<hostname>/auth/admin for the RH-SSO web server, or to https://secure-sso-<project-name>.<hostname>/auth/admin for the encrypted RH-SSO web server, and specify the user name and password used to create the administrator user.

4.3. Deployment Process

Once deployed, the sso72-https and sso72-x509-https templates create a single pod that contains both the database and the RH-SSO servers. The sso72-mysql, sso72-mysql-persistent, sso72-x509-mysql-persistent, sso72-postgresql, sso72-postgresql-persistent, and sso72-x509-postgresql-persistent templates create two pods, one for the database server and one for the RH-SSO web server.

After the RH-SSO web server pod has started, it can be accessed from its custom configured hostnames, or from the default hostnames:

  • http://sso-<project-name>.<hostname>/auth/admin: for the RH-SSO web server, and
  • https://secure-sso-<project-name>.<hostname>/auth/admin: for the encrypted RH-SSO web server.

Use the administrator user credentials to log in into the master realm’s administration console.

4.4. RH-SSO Clients

Clients are RH-SSO entities that request user authentication. A client can be an application requesting RH-SSO to provide user authentication, or it can make requests for access tokens to start services on behalf of an authenticated user. See the Managing Clients chapter of the Red Hat Single Sign-On documentation for more information.

RH-SSO provides OpenID-Connect and SAML client protocols.
OpenID-Connect is the preferred protocol and utilizes three different access types:

  • public: Useful for JavaScript applications that run directly in the browser and require no server configuration.
  • confidential: Useful for server-side clients, such as EAP web applications, that need to perform a browser login.
  • bearer-only: Useful for back-end services that allow bearer token requests.

It is required to specify the client type in the <auth-method> key of the application web.xml file. This file is read by the image at deployment. Set the value of <auth-method> element to:

  • KEYCLOAK for the OpenID Connect client.
  • KEYCLOAK-SAML for the SAML client.

The following is an example snippet for the application web.xml to configure an OIDC client:

...
<login-config>
        <auth-method>KEYCLOAK</auth-method>
</login-config>
...

4.4.1. Automatic and Manual RH-SSO Client Registration Methods

A client application can be automatically registered to an RH-SSO realm by using credentials passed in variables specific to the eap64-sso-s2i, eap70-sso-s2i, eap71-sso-s2i, and datavirt63-secure-s2i templates.

Alternatively, you can manually register the client application by configuring and exporting the RH-SSO client adapter and including it in the client application configuration.

4.4.1.1. Automatic RH-SSO Client Registration

Automatic RH-SSO client registration is determined by RH-SSO environment variables specific to the eap64-sso-s2i, eap70-sso-s2i, eap71-sso-s2i, and datavirt63-secure-s2i templates. The RH-SSO credentials supplied in the template are then used to register the client to the RH-SSO realm during deployment of the client application.

The RH-SSO environment variables included in the eap64-sso-s2i, eap70-sso-s2i, eap71-sso-s2i, and datavirt63-secure-s2i templates are:

VariableDescription

HOSTNAME_HTTP

Custom hostname for http service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>

HOSTNAME_HTTPS

Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>

SSO_URL

The RH-SSO web server authentication address: https://secure-sso-<project-name>.<hostname>/auth

SSO_REALM

The RH-SSO realm created for this procedure.

SSO_USERNAME

The name of the realm management user.

SSO_PASSWORD

The password of the user.

SSO_PUBLIC_KEY

The public key generated by the realm. It is located in the Keys tab of the Realm Settings in the RH-SSO console.

SSO_BEARER_ONLY

If set to true, the OpenID Connect client is registered as bearer-only.

SSO_ENABLE_CORS

If set to true, the RH-SSO adapter enables Cross-Origin Resource Sharing (CORS).

If the RH-SSO client uses the SAML protocol, the following additional variables need to be configured:

VariableDescription

SSO_SAML_KEYSTORE_SECRET

Secret to use for access to SAML keystore. The default is sso-app-secret.

SSO_SAML_KEYSTORE

Keystore filename in the SAML keystore secret. The default is keystore.jks.

SSO_SAML_KEYSTORE_PASSWORD

Keystore password for SAML. The default is mykeystorepass.

SSO_SAML_CERTIFICATE_NAME

Alias for keys/certificate to use for SAML. The default is jboss.

See Example Workflow: Automatically Registering EAP Application in RH-SSO with OpenID-Connect Client for an end-to-end example of the automatic client registration method using an OpenID-Connect client.

4.4.1.2. Manual RH-SSO Client Registration

Manual RH-SSO client registration is determined by the presence of a deployment file in the client application’s ../configuration/ directory. These files are exported from the client adapter in the RH-SSO web console. The name of this file is different for OpenID-Connect and SAML clients:

OpenID-Connect

../configuration/secure-deployments

SAML

../configuration/secure-saml-deployments

These files are copied to the RH-SSO adapter configuration section in the standalone-openshift.xml at when the application is deployed.

There are two methods for passing the RH-SSO adapter configuration to the client application:

  • Modify the deployment file to contain the RH-SSO adapter configuration so that it is included in the standalone-openshift.xml file at deployment, or
  • Manually include the OpenID-Connect keycloak.json file, or the SAML keycloak-saml.xml file in the client application’s ../WEB-INF directory.

See Example Workflow: Manually Configure an Application to Use RH-SSO Authentication, Using SAML Client for an end-to-end example of the manual RH-SSO client registration method using a SAML client.

4.5. Limitations

OpenShift does not currently accept OpenShift role mapping from external providers. If RH-SSO is used as an authentication gateway for OpenShift, users created in RH-SSO must have the roles added using the OpenShift Administrator oadm policy command.

For example, to allow an RH-SSO-created user to view a project namespace in OpenShift:

oadm policy add-role-to-user view <user-name> -n <project-name>