Chapter 5. Tutorials

Identify existing deployment config for RH-SSO 7.1 containers.

$ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql

Stop all RH-SSO 7.1 containers in the current namespace.

$ oc scale --replicas=0 dc/sso
deploymentconfig "sso" scaled

Update the image change trigger in the existing deployment config to reference the RH-SSO 7.2 image.

$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-sso72-openshift:1.1"}]'
"sso" patched

Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers.

$ oc rollout latest dc/sso
deploymentconfig "sso" rolled out

Deploy RH-SSO 7.2 containers using the modified deployment config.

$ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled

(Optional) Verify the database has been successfully updated.

$ oc get pods --selector=application=sso
NAME                     READY     STATUS    RESTARTS   AGE
sso-4-vg21r              1/1       Running   0          1h
sso-postgresql-1-t871r   1/1       Running   0          2h

$ oc logs sso-4-vg21r | grep 'Updating'
11:23:45,160 INFO  [org.keycloak.connections.jpa.updater.liquibase.LiquibaseJpaUpdaterProvider] (ServerService Thread Pool -- 58) Updating database. Using changelog META-INF/jpa-changelog-master.xml

Prepare template of OpenShift database migration job to generate the SQL file.

$ cat sso71-to-sso72-db-migrate-job.yaml.orig
apiVersion: batch/v1
kind: Job
metadata:
  name: sso71-to-sso72-db-migrate-job
spec:
  autoSelector: true
  parallelism: 0
  completions: 1
  template:
    metadata:
      name: sso71-to-sso72-db-migrate-job
    spec:
      containers:
      - env:
        - name: DB_SERVICE_PREFIX_MAPPING
          value: <<DB_SERVICE_PREFIX_MAPPING_VALUE>>
        - name: <<PREFIX>>_JNDI
          value: <<PREFIX_JNDI_VALUE>>
        - name: <<PREFIX>>_USERNAME
          value: <<PREFIX_USERNAME_VALUE>>
        - name: <<PREFIX>>_PASSWORD
          value: <<PREFIX_PASSWORD_VALUE>>
        - name: <<PREFIX>>_DATABASE
          value: <<PREFIX_DATABASE_VALUE>>
        - name: TX_DATABASE_PREFIX_MAPPING
          value: <<TX_DATABASE_PREFIX_MAPPING_VALUE>>
        - name: <<SERVICE_HOST>>
          value: <<SERVICE_HOST_VALUE>>
        - name: <<SERVICE_PORT>>
          value: <<SERVICE_PORT_VALUE>>
        image: <<SSO_IMAGE_VALUE>>
        imagePullPolicy: Always
        name: sso71-to-sso72-db-migrate-job
        # Keep the pod running after SQL migration file has been generated,
        # so we can retrieve it
        command: ["/bin/bash", "-c", "/opt/eap/bin/openshift-launch.sh || sleep 600"]
      restartPolicy: Never

$ cp sso71-to-sso72-db-migrate-job.yaml.orig sso71-to-sso72-db-migrate-job.yaml

Copy the datasource definition and database access credentials from RH-SSO 7.1 deployment config to appropriate places in database job migration template.

Use the following script to copy DB_SERVICE_PREFIX_MAPPING and TX_DATABASE_PREFIX_MAPPING variable values, together with values of environment variables specific to particular datasource (<PREFIX>_JNDI, <PREFIX>_USERNAME, <PREFIX>_PASSWORD, and <PREFIX>_DATABASE) from the deployment config named sso to the database job migration template named sso71-to-sso72-db-migrate-job.yaml.

$ cat mirror_sso_dc_db_vars.sh
#!/bin/bash

# IMPORTANT:
#
# If the name of the SSO deployment config differs from 'sso' or if the file name of the
# YAML definition of the migration job is different, update the following two variables
SSO_DC_NAME="sso"
JOB_MIGRATION_YAML="sso71-to-sso72-db-migrate-job.yaml"

# Get existing variables of the $SSO_DC_NAME deployment config in an array
declare -a SSO_DC_VARS=($(oc set env dc/${SSO_DC_NAME} --list | sed '/^#/d'))

# Get the PREFIX used in the names of environment variables
PREFIX=$(grep -oP 'DB_SERVICE_PREFIX_MAPPING=[^ ]+' <<< "${SSO_DC_VARS[@]}")
PREFIX=${PREFIX##*=}

# Substitute (the order in which replacements are made is important):
# * <<PREFIX>> with actual $PREFIX value and
# * <<PREFIX with "<<$PREFIX" value
sed -i "s#<<PREFIX>>#${PREFIX}#g" ${JOB_MIGRATION_YAML}
sed -i "s#<<PREFIX#<<${PREFIX}#g" ${JOB_MIGRATION_YAML}

# Construct the array of environment variables specific to the datasource
declare -a DB_VARS=(JNDI USERNAME PASSWORD DATABASE)

# Prepend $PREFIX to each item of the datasource array
DB_VARS=( "${DB_VARS[@]/#/${PREFIX}_}" )

# Add DB_SERVICE_PREFIX_MAPPING and TX_DATABASE_PREFIX_MAPPING variables
# to datasource array
DB_VARS=( "${DB_VARS[@]}" DB_SERVICE_PREFIX_MAPPING TX_DATABASE_PREFIX_MAPPING )

# Construct the SERVICE from DB_SERVICE_PREFIX_MAPPING
SERVICE=$(grep -oP 'DB_SERVICE_PREFIX_MAPPING=[^ ]+' <<< "${SSO_DC_VARS[@]}")
SERVICE=${SERVICE#*=}
SERVICE=${SERVICE%=*}
SERVICE=${SERVICE^^}
SERVICE=${SERVICE//-/_}

# If the deployment config contains <<SERVICE>>_SERVICE_HOST and
# <<SERVICE>>_SERVICE_PORT variables, add them to the datasource array.
# Their values also need to be propagated into yaml definition of the migration job.
if grep -Pq "${SERVICE}_SERVICE_HOST=[^ ]+" <<< "${SSO_DC_VARS[@]}" &&
   grep -Pq "${SERVICE}_SERVICE_PORT=[^ ]+" <<< "${SSO_DC_VARS[@]}"
then
  DB_VARS=( "${DB_VARS[@]}" ${SERVICE}_SERVICE_HOST ${SERVICE}_SERVICE_PORT )
# If they are not defined, delete their placeholder rows in yaml definition file
# (since if not defined they are not expanded which make the yaml definition invalid).
else
  for KEY in "HOST" "PORT"
  do
    sed -i "/SERVICE_${KEY}/d" ${JOB_MIGRATION_YAML}
  done
fi

# Substitute (the order in which replacements are made is important):
# * <<SERVICE_HOST>> with ${SERVICE}_SERVICE_HOST and
# * <<SERVICE_HOST_VALUE>> with "<<${SERVICE}_SERVICE_HOST_VALUE>>"
# Do this for both "HOST" and "PORT"
for KEY in "HOST" "PORT"
do
  sed -i "s#<<SERVICE_${KEY}>>#${SERVICE}_SERVICE_${KEY}#g" ${JOB_MIGRATION_YAML}
  sed -i "s#<<SERVICE_${KEY}_VALUE>>#<<${SERVICE}_SERVICE_${KEY}_VALUE>>#g" \
    ${JOB_MIGRATION_YAML}
done

# Propagate the values of the datasource array items into yaml definition of the
# migration job
for VAR in "${SSO_DC_VARS[@]}"
do
  IFS=$'=' read KEY VALUE <<< $VAR
  if grep -q $KEY <<< ${DB_VARS[@]}
  then
    KEY+="_VALUE"
    # Enwrap integer port value with double quotes
    if [[ ${KEY} =~ ${SERVICE}_SERVICE_PORT_VALUE ]]
    then
      sed -i "s#<<${KEY}>>#\"${VALUE}\"#g" ${JOB_MIGRATION_YAML}
    # Character values do not need quotes
    else
      sed -i "s#<<${KEY}>>#${VALUE}#g" ${JOB_MIGRATION_YAML}
    fi
    # Verify that the value has been successfully propagated.
    if grep -q '(JNDI|USERNAME|PASSWORD|DATABASE)' <<< "${KEY}" &&
       grep -q "<<PREFIX${KEY#${PREFIX}}" ${JOB_MIGRATION_YAML} ||
       grep -q "<<${KEY}>>" ${JOB_MIGRATION_YAML}
    then
      echo "Failed to update value of ${KEY%_VALUE}! Aborting."
      exit 1
    else
      printf '%-60s%-40s\n' "Successfully updated ${KEY%_VALUE} to:" "$VALUE"
    fi
  fi
done

Run the script.

$ chmod +x ./mirror_sso_dc_db_vars.sh
$ ./mirror_sso_dc_db_vars.sh
Successfully updated DB_SERVICE_PREFIX_MAPPING to:          sso-postgresql=DB
Successfully updated DB_JNDI to:                            java:jboss/datasources/KeycloakDS
Successfully updated DB_USERNAME to:                        userxOp
Successfully updated DB_PASSWORD to:                        tsWNhQHK
Successfully updated DB_DATABASE to:                        root
Successfully updated TX_DATABASE_PREFIX_MAPPING to:         sso-postgresql=DB

Build the RH-SSO 7.2 database migration image using the pre-configured source and wait for the build to finish.

$ oc get is -n openshift | grep sso72 | cut -d ' ' -f1
redhat-sso72-openshift

$ oc new-build redhat-sso72-openshift:1.1~https://github.com/jboss-openshift/openshift-examples --context-dir=sso-manual-db-migration --name=sso72-db-migration-image
--> Found image bf45ac2 (7 days old) in image stream "openshift/redhat-sso72-openshift" under tag "1.1" for "redhat-sso72-openshift:1.1"

    Red Hat SSO 7.2
    ---------------
    Platform for running Red Hat SSO

    Tags: sso, sso7, keycloak

    * A source build using source code from https://github.com/jboss-openshift/openshift-examples will be created
      * The resulting image will be pushed to image stream "sso72-db-migration-image:latest"
      * Use 'start-build' to trigger a new build

--> Creating resources with label build=sso72-db-migration-image ...
    imagestream "sso72-db-migration-image" created
    buildconfig "sso72-db-migration-image" created
--> Success
    Build configuration "sso72-db-migration-image" created and build triggered.
    Run 'oc logs -f bc/sso72-db-migration-image' to stream the build progress.

$ oc logs -f bc/sso72-db-migration-image --follow
Cloning "https://github.com/iankko/openshift-examples.git" ...
...
Push successful

Update the template of the database migration job (sso71-to-sso72-db-migrate-job.yaml) with reference to the built sso72-db-migration-image image.

Instantiate database migration job from the job template.

$ oc create -f sso71-to-sso72-db-migrate-job.yaml
job "sso71-to-sso72-db-migrate-job" created

Identify existing deployment config for RH-SSO 7.1 containers.

$ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql

Stop all RH-SSO 7.1 containers in the current namespace.

$ oc scale --replicas=0 dc/sso
deploymentconfig "sso" scaled

Run the database migration job and wait for the pod to be running correctly.

$ oc get jobs
NAME                            DESIRED   SUCCESSFUL   AGE
sso71-to-sso72-db-migrate-job   1         0            3m

$ oc scale --replicas=1 job/sso71-to-sso72-db-migrate-job
job "sso71-to-sso72-db-migrate-job" scaled

$ oc get pods
NAME                                  READY     STATUS      RESTARTS   AGE
sso-postgresql-1-n5p16                1/1       Running     1          19h
sso71-to-sso72-db-migrate-job-b87bb   1/1       Running     0          1m
sso72-db-migration-image-1-build      0/1       Completed   0          27m

Get the dynamically generated SQL database migration file from the pod.

$ mkdir -p ./db-update
$ oc rsync sso71-to-sso72-db-migrate-job-b87bb:/opt/eap/keycloak-database-update.sql ./db-update
receiving incremental file list
keycloak-database-update.sql

sent 30 bytes  received 29,726 bytes  59,512.00 bytes/sec
total size is 29,621  speedup is 1.00

Apply the database update manually.

Update image change trigger in the existing deployment config of RH-SSO 7.1 to reference the RH-SSO 7.2 image.

$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-sso72-openshift:1.1"}]'
"sso" patched

Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers.

$ oc rollout latest dc/sso
deploymentconfig "sso" rolled out

Deploy RH-SSO 7.2 containers using the modified deployment config.

$ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled

Select sso72-mysql RH-SSO application template. When deploying the template ensure to keep the SSO_REALM variable unset (default value).

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

Then access the RH-SSO web console at https://secure-sso-<sso-app-demo>.<openshift32.example.com>/auth/admin using the administrator account.

Get the RH-SSO deployment config and scale it down to zero.

$ oc get dc -o name
deploymentconfig/sso
deploymentconfig/sso-mysql

$ oc scale --replicas=0 dc sso
deploymentconfig "sso" scaled

Instruct the RH-SSO 7.2 server deployed on RH-SSO for OpenShift image to perform database export at RH-SSO server boot time.

oc env dc/sso -e "JAVA_OPTS_APPEND=-Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=/tmp/demorealm-export.json"

Scale the RH-SSO deployment config back up. This will start the RH-SSO server and export its database.

$ oc scale --replicas=1 dc sso
deploymentconfig "sso" scaled

(Optional) Verify that the export was successful.

$ oc get pods
NAME                READY     STATUS    RESTARTS   AGE
sso-4-ejr0k         1/1       Running   0          27m
sso-mysql-1-ozzl0   1/1       Running   0          4h

$ oc logs sso-4-ejr0k | grep 'Export'
09:24:59,503 INFO  [org.keycloak.exportimport.singlefile.SingleFileExportProvider] (ServerService Thread Pool -- 57) Exporting model into file /tmp/demorealm-export.json
09:24:59,998 INFO  [org.keycloak.services] (ServerService Thread Pool -- 57) KC-SERVICES0035: Export finished successfully

Retrieve the JSON file of the RH-SSO database from the pod.

$ oc get pods
NAME                READY     STATUS    RESTARTS   AGE
sso-4-ejr0k         1/1       Running   0          2m
sso-mysql-1-ozzl0   1/1       Running   0          4h

$ oc rsync sso-4-ejr0k:/tmp/demorealm-export.json .

(Optional) Import the JSON file of the RH-SSO database into an RH-SSO server running in another environment.

Use the administration console of the RH-SSO server to import the resources from previously exported JSON file into the RH-SSO server’s database, when the RH-SSO server is running as a Red Hat Single Sign-On 7.2 container on OpenShift:

Edit the user configuration:

Edit the /etc/origin/master/master-config.yaml file and find the identityProviders. The OpenShift master, which was deployed using the OpenShift Primer, is configured with HTPassword and shows the following:

identityProviders:
- challenge: true
  login: true
  name: htpasswd_auth
  provider:
    apiVersion: v1
    file: /etc/origin/openshift-passwd
    kind: HTPasswdPasswordIdentityProvider

Add RH-SSO as a secondary identity provider with content similar to the following snippet:

- name: rh_sso
  challenge: false
  login: true
  mappingMethod: add
  provider:
    apiVersion: v1
    kind: OpenIDIdentityProvider
    clientID: openshift-demo
    clientSecret: 7b0384a2-b832-16c5-9d73-2957842e89h7
    ca: xpaas.crt
    urls:
      authorize: https://secure-sso-sso-app-demo.openshift32.example.com/auth/realms/OpenShift/protocol/openid-connect/auth
      token: https://secure-sso-sso-app-demo.openshift32.example.com/auth/realms/OpenShift/protocol/openid-connect/token
      userInfo: https://secure-sso-sso-app-demo.openshift32.example.com/auth/realms/OpenShift/protocol/openid-connect/userinfo
    claims:
      id:
      - sub
      preferredUsername:
      - preferred_username
      name:
      - name
      email:
      - email

Save the configuration and restart the OpenShift master:

$ systemctl restart atomic-openshift-master

Create a new project:

$ oc new-project eap-app-demo

Add the view role to the default service account. This enables the service account to view all the resources in the eap-app-demo namespace, which is necessary for managing the cluster.

$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default

The EAP template requires an SSL keystore and a JGroups keystore.
This example uses keytool, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. The following commands will prompt for passwords.

Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files:

$ oc secret new eap-ssl-secret eapkeystore.jks
$ oc secret new eap-jgroup-secret eapjgroups.jceks

Add the EAP secret to the default service account:

$ oc secrets link default eap-ssl-secret eap-jgroup-secret

Select the eap71-sso-s2i image to list all of the deployment parameters. Include the following RH-SSO parameters to configure the RH-SSO credentials during the EAP build:

Create a new project:

$ oc new-project eap-app-demo

Add the view role to the default service account. This enables the service account to view all the resources in the eap-app-demo namespace, which is necessary for managing the cluster.

$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default

The EAP template requires an SSL keystore and a JGroups keystore.
This example uses keytool, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. The following commands will prompt for passwords.

Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files:

$ oc secret new eap-ssl-secret eapkeystore.jks
$ oc secret new eap-jgroup-secret eapjgroups.jceks

Add the EAP application secret to the EAP service account created earlier:

$ oc secrets link default eap-ssl-secret eap-jgroup-secret

Delete the <PrivateKeyPem> and <CertificatePem> tags and keys and replace it with keystore information:

...
<Keys>
  <Key signing="true">
    <KeyStore file= "/etc/eap-secret-volume/keystore-saml.jks" password="password">
      <PrivateKey alias="sso-saml-demo" password="password"/>
      <Certificate alias="sso-saml-demo"/>
    </KeyStore>
  </Key>
</Keys>

The mount path of the keystore-saml.jks (in this example /etc/eap-secret-volume/keystore-saml.jks) can be specified in the application template with the parameter EAP_HTTPS_KEYSTORE_DIR.
The aliases and passwords for the PrivateKey and the Certificate were configured when the SAML Keys were exported from the RH-SSO client.

Delete the second <CertificatePem> tag and key and replace it with the the realm certificate information:

...
<Keys>
  <Key signing="true">
    <KeyStore file="/etc/eap-secret-volume/keystore-saml.jks" password="password">
      <Certificate alias="saml-demo"/>
    </KeyStore>
  </Key>
</Keys>
...

The certificate alias and password were configured when the SAML Keys were exported from the RH-SSO client.