Chapter 5. Tutorials

Identify the deployment config used to deploy the containers, running previous version of the Red Hat Single Sign-On for OpenShift image.

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

Stop all pods running the previous version of the Red Hat Single Sign-On for OpenShift image 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 Red Hat Single Sign-On 7.3.8.GA image.

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

Start rollout of the new Red Hat Single Sign-On 7.3.8.GA images based on the latest image defined in the image change triggers.

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

Deploy Red Hat Single Sign-On 7.3.8.GA 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 job-to-migrate-db-to-sso73.yaml.orig
apiVersion: batch/v1
kind: Job
metadata:
  name: job-to-migrate-db-to-sso73
spec:
  autoSelector: true
  parallelism: 0
  completions: 1
  template:
    metadata:
      name: job-to-migrate-db-to-sso73
    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: job-to-migrate-db-to-sso73
        # Keep the pod running after the SQL migration
        # file was generated, so we can retrieve it
        command:
          - "/bin/bash"
          - "-c"
          - "/opt/eap/bin/openshift-launch.sh || sleep 600"
      restartPolicy: Never

$ cp job-to-migrate-db-to-sso73.yaml.orig \
     job-to-migrate-db-to-sso73.yaml

From deployment config used to run the previous version of the Red Hat Single Sign-On for OpenShift image, copy the datasource definition and database access credentials to appropriate places of the template of the database migration job.

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 job-to-migrate-db-to-sso73.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="job-to-migrate-db-to-sso73.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:
# * <<PREFIX>> with actual $PREFIX value and
# * <<PREFIX with "<<$PREFIX" value
# The order in which these replacements are made is important!
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.
HOST_PATTERN="${SERVICE}_SERVICE_HOST=[^ ]"
PORT_PATTERN="${SERVICE}_SERVICE_PORT=[^ ]"
if
  grep -Pq "${HOST_PATTERN}" <<< "${SSO_DC_VARS[@]}" &&
  grep -Pq "${PORT_PATTERN}" <<< "${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:
# * <<SERVICE_HOST>> with ${SERVICE}_SERVICE_HOST and
# * <<SERVICE_HOST_VALUE>> with <<${SERVICE}_SERVICE_HOST_VALUE>>
# The order in which replacements are made is important!
# Do this for both "HOST" and "PORT"
for KEY in "HOST" "PORT"
do
  PATTERN_1="<<SERVICE_${KEY}>>"
  REPL_1="${SERVICE}_SERVICE_${KEY}"
  sed -i "s#${PATTERN_1}#${REPL_1}#g" ${JOB_MIGRATION_YAML}
  PATTERN_2="<<SERVICE_${KEY}_VALUE>>"
  REPL_2="<<${SERVICE}_SERVICE_${KEY}_VALUE>>"
  sed -i "s#${PATTERN_2}#${REPL_2}#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 Red Hat Single Sign-On 7.3.8.GA database migration image using the pre-configured source and wait for the build to finish.

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

$ oc new-build redhat-sso73-openshift:1.0~https://github.com/iankko/openshift-examples.git#KEYCLOAK-8500 \
  --context-dir=sso-manual-db-migration \
  --name=sso73-db-migration-image
--> Found image bf45ac2 (7 days old) in image stream "openshift/redhat-sso73-openshift" under tag "1.0" for "redhat-sso73-openshift:1.0"

    Red Hat SSO 7.3.8.GA
    ---------------
    Platform for running Red Hat SSO

    Tags: sso, sso7, keycloak

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

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

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

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

Instantiate database migration job from the job template.

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

Identify the deployment config used to deploy the containers, running previous version of the Red Hat Single Sign-On for OpenShift image.

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

Stop all pods running the previous version of the Red Hat Single Sign-On for OpenShift image 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
job-to-migrate-db-to-sso73   1         0            3m

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

$ oc get pods
NAME                                  READY     STATUS      RESTARTS   AGE
sso-postgresql-1-n5p16                1/1       Running     1          19h
job-to-migrate-db-to-sso73-b87bb   1/1       Running     0          1m
sso73-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 job-to-migrate-db-to-sso73-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 the image change trigger in the existing deployment config to reference the Red Hat Single Sign-On 7.3.8.GA image.

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

Start rollout of the new Red Hat Single Sign-On 7.3.8.GA images based on the latest image defined in the image change triggers.

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

Deploy the Red Hat Single Sign-On 7.3.8.GA containers using the modified deployment config.

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

Select sso73-mysql Red Hat Single Sign-On 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 Red Hat Single Sign-On web console at https://secure-sso-<sso-app-demo>.<openshift32.example.com>/auth/admin using the administrator account.

Get the Red Hat Single Sign-On 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 Red Hat Single Sign-On 7.3.8.GA server deployed on Red Hat Single Sign-On for OpenShift image to perform database export at Red Hat Single Sign-On server boot time.

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

Scale the Red Hat Single Sign-On deployment config back up. This will start the Red Hat Single Sign-On 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 Red Hat Single Sign-On 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 Red Hat Single Sign-On database into an Red Hat Single Sign-On server running in another environment.

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

Edit the user configuration:

Edit the /etc/origin/master/master-config.yaml file and find the identityProviders. For example, in the case the OpenShift master is configured with the HTPassword identity provider, the identityProviders section will look similar to the following one:

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

Add Red Hat Single Sign-On 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 Red Hat Single Sign-On parameters to configure the Red Hat Single Sign-On 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 Red Hat Single Sign-On 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 Red Hat Single Sign-On client.