As previously stated in this course, RH-SSO runs on bare metal or virtualized environments, and on Red Hat OpenShift.

There are two ways to install RH-SSO on Red Hat OpenShift: the Red Hat OpenShift templates, and the RH-SSO operator.

A Red Hat OpenShift template is a YAML or JSON file consisting of a set of Red Hat OpenShift resources. Templates define parameters that you can use to customize the resource configuration. Red Hat OpenShift processes templates by replacing parameter references with values and creating a customized set of resources. Red Hat provides RH-SSO application templates for deploying in Red Hat OpenShift.

The use of RH-SSO Red Hat OpenShift templates is the most mature way to deploy RH-SSO on Red Hat OpenShift. The templates allow a higher level of customization of the RH-SSO deployment, and deploy the software in different versions of Red Hat OpenShift. However, future versions of RH-SSO will deploy on Red Hat OpenShift only by using the RH-SSO operator. Thus, on this course we only cover the installation and configuration by using the RH-SSO operator.

Refer to the references section to learn more about installing RH-SSO on Red Hat OpenShift by using the Red Hat OpenShift templates.

You can create Kubernetes custom resources (CR) that automate administrative tasks by using the RH-SSO operator. You can create custom resources as YAML files that define the parameters for the administrative tasks.

In the case of RH-SSO, the custom resource definitions (CRDs) created by the RH-SSO operator include resources to create and configure instances of RH-SSO servers, realms, clients, and users. The following table summarizes the RH-SSO CRDs for Red Hat OpenShift.

The use of the RH-SSO operator to deploy RH-SSO on Red Hat OpenShift gives the following benefits to the RH-SSO administrator:

The Red Hat OpenShift operators approach allows you to configure many aspects of the RH-SSO instances declaratively, enabling you to do it in an automated way without human intervention. However, the above set of CRDs does not allow you to fully configure RH-SSO.

In some cases, such as when creating and manipulating groups, roles, and other configuration settings, you must do it by communicating directly to the RH-SSO instance, either by means of the RH-SSO Admin Console, the kcadm.sh CLI tool, or the REST API.

After you create CRs, you can manage them by using the oc command or the RH-SSO Admin Console. If you modify a CR by using the oc command, then you can see the modifications in the RH-SSO Admin Console. However, if you modify an RH-SSO resource through the RH-SSO Admin Console, then you do not see the modifications in the CR. Thus, use only one of the methods.

You can install the RH-SSO Operator by using either the Red Hat OpenShift web console or the oc command-line tools.

Install the RH-SSO operator with the Red Hat OpenShift Web Console

Log in to your Red Hat OpenShift cluster web console. Navigate to Operators → OperatorHub to display the list of operators and type Single Sign-On in the Filter by keyword field. Click Red Hat Single Sign-On Operator, and then click Install.

Figure 5.1: RH-SSO operator install

You can choose the installation options in the Install Operator wizard.

Update channel

The RH-SSO operator has alpha and stable, two update channels. Red Hat recommends to use the stable channel.

Installation mode

A specific namespace on the cluster installation mode is selected by default for the RH-SSO operator.

Installed namespace

Select a namespace to install the operator workload to the selected namespace.

Update approval

Red Hat OpenShift updates operators automatically when new versions are available. The manual approval option requires manual intervention to approve the update.

Click Install. The installation can take a few minutes to complete.

apiVersion: project.openshift.io/v1
kind: Project 
metadata:
  name: <namespace>

---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup 
metadata:
  namespace: <namespace>
  name: rhsso-operator
spec:
  targetNamespaces:
  -  <namespace>

---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription 
metadata:
  namespace: <namespace>
  name: rhsso-operator
spec: 
  channel: stable
  installPlanApproval: Automatic
  name: rhsso-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace

[user@demo ~]$ oc create -f rhsso-operator.yaml
namespace/rhsso created
operatorgroup.operators.coreos.com/rhsso-operator created
subscription.operators.coreos.com/rhsso-operator created

[user@demo ~]$ oc get csv -n rhsso
NAME                            ...   VERSION         ...   PHASE
rhsso-operator.7.6.1-opr-004    ...   7.6.1-opr-004   ...   Succeeded

After the RH-SSO operator installation, you can create the Keycloak custom resource. The Keycloak CR installs RH-SSO on Red Hat OpenShift and creates the following Kubernetes services and components:

Figure 5.2: Keycloak Services and Components

See the references section for more information about the stateful set, secret, services, and route Kubernetes components.

You can install the RH-SSO custom resource by using either the Red Hat OpenShift web console or the oc command-line tools.

kind: Keycloak
apiVersion: keycloak.org/v1alpha1
metadata:
  name: do313-keycloak 
  labels:
    app: sso
  namespace: rhsso
spec:
  externalAccess: 
    enabled: true
    host: <custom host>.apps.ocp4.example.com
  instances: 1 
  keycloakDeploymentSpec: 
    imagePullPolicy: Always
  postgresDeploymentSpec: 
    imagePullPolicy: Always

[user@demo ~]$ oc create -f do313-keycloak.yaml

[user@demo ~]$ oc get keycloak/do313-keycloak -o yaml
apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  creationTimestamp: "2023-01-17T16:53:17Z"
  generation: 1
  labels:
    app: sso
  name: do313-keycloak
  namespace: rhsso
  resourceVersion: "135473"
  uid: a52cd419-9f0d-4473-9005-bd422280dac7
spec:
  externalAccess:
    enabled: true
  instances: 1
status:
  credentialSecret: credential-do313-keycloak
  externalURL: https://keycloak-rhsso.apps.ocp4.example.com
  internalURL: https://keycloak.rhsso.svc:8443
  message: ""
  phase: reconciling
  ready: true
  secondaryResources:
    ConfigMap:
    - keycloak-probes
    Deployment:
    - keycloak-postgresql
    Ingress:
    - keycloak
    PersistentVolumeClaim:
    - keycloak-postgresql-claim
    PrometheusRule:
    - keycloak
    Route:
    - keycloak
    - keycloak-metrics-rewrite
    Secret:
    - credential-do313-keycloak
    - keycloak-db-secret
    Service:
    - keycloak-postgresql
    - keycloak
    - keycloak-discovery
    - keycloak-monitoring
    ServiceMonitor:
    - keycloak-service-monitor
    StatefulSet:
    - keycloak
  version: main

Install the RH-SSO Keycloak Custom Resource by using the Red Hat OpenShift Web Console

Navigate to Operators → Installed Operators to display the list of installed operators, and then click Red Hat Single Sign-On Operator. Click Create instance in the Keycloak block.

Figure 5.3: RH-SSO Keycloak create

On the Create Keycloak page, select YAML view to display the web console YAML editor. Update the YAML and then click Create.

Figure 5.4: RH-SSO Keycloak create YAML

The do313-keycloak custom resource shows in the Keycloak tab. Wait for the Status to update from Phase:initialising to Phase:reconciling.

The keycloak route has the RH-SSO URL for the Admin Console, and the credential-<CR> secret has the RH-SSO login credentials.

On the Keycloaks page, click do313-keycloak to display the details of the do313-keycloak custom resource. Select the Resources tab, and click the credential-do313-keycloak secret to retrieve the credentials details. On the Secret details page, scroll down to locate Data, and click Reveal values.

Figure 5.5: The RH-SSO Keycloak custom resource credentials.

The ADMIN_USERNAME value shows admin as the username. Copy the ADMIN_PASSWORD value to use in the log in step.

Navigate to Networking → Routes to display the list of routes for the rhsso project.

Click the keycloak route to display the route details. The Location field provides a link to the RH-SSO Admin Console.

Figure 5.6: RH-SSO Keycloak route

You can also retrieve the RH-SSO URL and login credentials from the command line.

[user@demo ~]$ oc get route/keycloak -n rhsso
NAME       HOST/PORT                                ...       TERMINATION   WILDCARD
keycloak   keycloak-rhsso.apps.ocp4.example.com   ...       reencrypt     None
[user@demo ~]$ oc -n rhsso extract secrets/credential-do313-keycloak --to=-
# ADMIN_PASSWORD
uSgqJTe_tHoo9A==
# ADMIN_USERNAME
admin

Click the link to access the RH-SSO Admin Console in a new tab. On the RH-SSO Admin Console, click Administration Console. Then, log in as the admin user with the password retrieved in the preceding step.