Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
    2. history
×

Red Hat Single Sign-On (SSO) xPaaS Image

Overview

Red Hat Single Sign-On (SSO) is an integrated sign-on solution available as a containerized xPaaS image designed for use with OpenShift. This image provides an authentication server for users to centrally log in, log out, register, and manage user accounts for web applications, mobile applications, and RESTful web services.

Red Hat offers five SSO application templates:

  • sso70-basic: SSO backed by a H2 database on the same pod

  • sso70-mysql: SSO backed by a MySQL database on a separate pod

  • sso70-mysql-persistent: SSO backed by a persistent PostgreSQL database on a separate pod

  • sso70-postgresql: SSO backed by a MySQL database on a separate pod

  • sso70-postgresql-persistent: SSO backed by a persistent PostgreSQL database on a separate pod

An SSO-enabled Red Hat JBoss Enterprise Application Platform (JBoss EAP) Image is also offered, which enables users to deploy a JBoss EAP instance that can be used with SSO for authentication:

  • eap64-sso-s2i: SSO-enabled JBoss EAP

Differences Between the SSO xPaaS Application and Keycloak

The SSO xPaaS application is based on Keycloak, a JBoss community project. There are some differences in functionality between the Red Hat Single Sign-On xPaaS Application and Keycloak:

  • This image is currently available as a Technical Preview for use only with SSO-enabled Red Hat JBoss Enterprise Application Platform (JBoss EAP) applications.

  • The SSO xPaaS Technical Preview Application includes all of the functionality of Keycloak 1.8.1. In addition, the SSO-enabled JBoss EAP image automatically handles OpenID Connect or SAML client registration and configuration for .war deployments that contain <auth-method>KEYCLOAK</auth-method> or <auth-method>KEYCLOAK-SAML</auth-method> in their respective web.xml files.

Versioning for xPaaS Images

See the xPaaS part of the OpenShift and Atomic Platform Tested Integrations page for details about OpenShift image version compatibility.

Prerequisites for Deploying the SSO xPaaS Image

The following is a list of prerequisites for using the SSO xPaaS image:

  1. Acquire Red Hat Subscriptions: Ensure that you have the relevant OpenShift subscriptions as well as a subscription for xPaaS Middleware.

  2. Install OpenShift: Before using the OpenShift xPaaS images, you must have an OpenShift environment installed and configured:

    1. The Quick Installation method allows you to install OpenShift using an interactive CLI utility.

    2. The Advanced Installation method allows you to install OpenShift using a reference configuration. This method is best suited for production environments.

  3. Ensure the DNS has been configured. This is required for communication between JBoss EAP and SSO, and for the requisite redirection. See DNS for more information.

  4. Install and Deploy Docker Registry: Install the Docker Registry and then ensure that the Docker Registry is deployed to locally manage images:

    $ oadm registry --config=/etc/origin/master/admin.kubeconfig \
    --credentials=/etc/origin/master/openshift-registry.kubeconfig

    For more information, see Deploying a Docker Registry

  5. Deploy a Router. For more information, see Deploying a Router.

  6. Ensure that you can run the oc create command with cluster-admin privileges.

Using the SSO Image Streams and Application Templates

The Red Hat xPaaS middleware images were automatically created during the installation of OpenShift along with the other default image streams and templates.

Preparing and Deploying the SSO xPaaS Application Templates

Using the OpenShift CLI

  1. Prepare the JBoss EAP and SSO application service accounts and their associated secrets.

    $ oc create -n <project-name> -f <application-templates_file_path>/secrets/eap-app-secret.json
    $ oc create -n <project-name> -f <application-templates_file_path>/secrets/sso-app-secret.json

  2. Deploy one of the SSO application templates. This example deploys the sso70-postgresql template, which deploys an SSO pod backed by a PostgreSQL database on a separate pod.

    $ oc process -f <application-templates_file_path>/sso/sso70-postgresql.json | oc create -n <project-name> -f -

    Or, if the template has been imported into common namespace:

    $ oc new-app --template=sso70-postgresql -n <project-name>

Using the OpenShift Web Console

Log in to the OpenShift web console:

  1. Click Add to project to list all of the default image streams and templates.

  2. Use the Filter by keyword search bar to limit the list to those that match sso. You may need to click See all to show the desired application template.

  3. Click an application template to list all of the deployment parameters. These parameters can be configured manually, or can be left as default.

  4. Click Create to deploy the application template.

Deployment Process

Once deployed, two pods will be created: one for the SSO web servers and one for the database. After the SSO web server pod has started, the web servers can be accessed at their custom configured hostnames, or at the default hostnames:

The default login username/password credentials are admin/admin.

Quickstart Example: Using the SSO xPaaS Image with the SSO-enabled JBoss EAP xPaaS Image

This example uses the OpenShift web console to deploy SSO xPaaS backed by a PostgreSQL database. Once deployed, an SSO realm, role, and user will be created to be used when configuring the SSO-enabled JBoss EAP xPaaS Image deployment. Once successfully deployed, the SSO user can then be used to authenticate and access JBoss EAP.

Deploy the SSO Application Template

  1. Log in to the OpenShift web console and select the <project-name> project space.

  2. Click Add to project to list all of the default image streams and templates.

  3. Use the Filter by keyword search bar to limit the list to those that match sso. You may need to click See all to show the desired application template.

  4. Click the sso70-postgresql application template to list all of the deployment parameters. These parameters will be left as default for this example.

  5. Click Create to deploy the application template and start pod deployment. This may take a couple of minutes.

Create SSO Credentials

Log in to the encrypted SSO web server at https://secure-sso-<project-name>.<hostname>/auth using the default admin/admin user name and password.

  • Create a Realm

    1. Create a new realm by hovering your cursor over the realm namespace (default is Master) at the top of the sidebar and click the Add Realm button.

    2. Enter a realm name and click Create.

  • Copy the Public Key In the newly created realm, click the Keys tab and copy the public key that has been generated. This will be needed to deploy the SSO-enabled JBoss EAP image.

  • Create a Role Create a role in SSO with a name that corresponds to the JEE role defined in the web.xml of the example application. This role will be assigned to an SSO application user to authenticate access to user applications.

    1. Click Roles in the Configure sidebar to list the roles for this realm. As this is a new realm, there should only be the default offline_access role. Click Add Role.

    2. Enter the role name and optional description and click Save.

  • Create Users and Assign Roles Create two users. The realm management user will be assigned the realm-management roles to handle automatic SSO client registration in the SSO server. The application user will be assigned the JEE role, created in the previous step, to authenticate access to user applications.

Create the realm management user:

  1. Click Users in the Manage sidebar to view the user information for the realm. Click Add User.

  2. Enter a valid Username and any additional optional information for the realm management user and click Save.

  3. Edit the user configuration. Click the Credentials tab in the user space and enter a password for the user. After the password has been confirmed you can click the Reset Password button to set the user password. A pop-up window will prompt for additional confirmation.

  4. Click Role Mappings to list the realm and client role configuration. In the Client Roles drop-down menu, select realm-management and add all of the available roles to the user. This provides the user SSO server rights that can be used by the JBoSS EAP image to create clients.

Create the application user:

  1. Click Users in the Manage sidebar to view the user information for the realm. Click Add User.

  2. Enter a valid Username and any additional optional information for the application user and click Save.

  3. Edit the user configuration. Click the Credentials tab in the user space and enter a password for the user. After the password has been confirmed you can click the Reset Password button to set the user password. A pop-up window will prompt for additional confirmation.

  4. Click Role Mappings to list the realm and client role configuration. In Available Roles, add the JEE role created earlier.

Deploy the SSO-enabled JBoss EAP Image

  1. Return to the OpenShift web console and click Add to project to list all of the default image streams and templates.

  2. Use the Filter by keyword search bar to limit the list to those that match sso. You may need to click See all to show the desired application template.

  3. Click the eap64-sso-s2i image to list all of the deployment parameters. Edit the configuration of the following SSO parameters:

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

    • SSO_REALM: The 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 SSO console.

    • SSO_BEARER_ONLY: If set to true, the OpenID Connect client will be registered as bearer-only.

    • SSO_ENABLE_CORS: If set to true, the Keycloak adapter enables Cross-Origin Resource Sharing (CORS).

  4. Click Create to deploy the JBoss EAP image.

It may take several minutes for the JBoss EAP image to deploy. When it does, it can be accessed at:

  • http://<application-name>-<project-name>.<hostname>/<app-context>: for the web server, and

  • https://secure-<application-name>-<project-name>.<hostname>/<app-context>: for the encrypted web server, where <app-context> is one of app-jee, app-profile-jee, app-profile-jee-saml, or service depending on the example application.

Alternate Deployments

You can also create the client registration in the Clients frame of the Configure sidebar. Once a client has been registered, click the Installation tab and download the configuration .xml:

  • For OpenID Connect application sources, save the Keycloak OIDC JBoss Subsystem XML to <file_path>/configuration/secure-deployments.

  • For SAML application sources, save the Keyclock SAML Wildfly/JBoss Subsystem to <file_path>/configuration/secure-saml-deployments.

You can also edit the standalone-openshift.xml of the JBoss EAP image, which will deploy the manual configuration instead of the default. For more information, see Using a Modified JBoss EAP xPaaS Image.

Log in to the JBoss EAP Server Using SSO

  1. Access the JBoss EAP application server and click Login. You will be redirected to the SSO login.

  2. Log in using the SSO user created in the example. You will be authenticated against the SSO server and returned to the JBoss EAP application server.

Known Issues

  • There is a known issue with the EAP6 Adapter HttpServletRequest.logout() in which the adapter does not log out from the application, which can create a login loop. The workaround is to call HttpSession.invalidate(); after request.logout() to clear the Keycloak token from the session. For more information, see KEYCLOAK-2665.

  • The SSO logs throw a duplication error if the SSO pod is restarted while backed by a database pod. This error can be safely ignored.

  • Setting adminUrl to a "https://…​" address in an OpenID Connect client will cause javax.net.ssl.SSLHandshakeException exceptions on the SSO server if the default secrets (sso-app-secret and eap-app-secret) are used. The application server must use either CA-signed certificates or configure the SSO trust store to trust the self-signed certificates.

  • If the client route uses a different domain suffix to the SSO service, the client registration script will erroneously configure the client on the SSO side, causing bad redirection.

  • The SSO-enabled JBoss EAP image does not properly set the adminUrl property during automatic client registration. As a workaround, log in to the SSO console after the application has started and manually modify the client registration adminUrl property to http://<application-name>-<project-name>.<hostname>/<app-context>.