Chapter 4. Tutorials

Procedure

1. Start by performing a database level backup.

   $ oc rsh <POSTGRE-SQL-POD> pg_dump -C <DATABASE> rhsso_db.bak

2. Scale down the sso pod.

   $ oc scale dc/sso --replicas=0

3. Edit dc/sso-postgresql.

   $ oc edit dc/sso-postgresql

   Switch ImageStreamTag to :postgresql:13-el8.

   - imageChangeParams:
         automatic: true
         containerNames:
         - sso-postgresql
         from:
           kind: ImageStreamTag
           name: postgresql:13-el8
           namespace: openshift

4. Wait again for the sso-postgresql pod to be running and stable.

5. Ensure the pod sso-postgresql has the correct version.

   $ oc rsh dc/sso-postgresql /bin/bash -c "psql --version"
   psql (PostgreSQL) 13.5

6. Unset the variable POSTGRESQL_UPGRADE and let the sso-postgresql pod deploy again.

   $ oc set env dc/sso-postgresql POSTGRESQL_UPGRADE-

7. Confirm for the last time that the pod sso-posgresql is running.

8. Run the following commands to update the core set of Red Hat Single Sign-On 7.5.3 resources for OpenShift in the openshift project:

   $ for resource in sso75-image-stream.json \
     sso75-https.json \
     sso75-postgresql.json \
     sso75-postgresql-persistent.json \
     sso75-x509-https.json \
     sso75-x509-postgresql-persistent.json
   do
     oc replace -n openshift --force -f \
     https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso75-dev/templates/${resource}
   done

9. Run the following command to install the Red Hat Single Sign-On 7.5.3 OpenShift image streams in the openshift project:

   $ oc -n openshift import-image rh-sso-7/sso75-openshift-rhel8:7.5 --from=registry.redhat.io/rh-sso-7/sso75-openshift-rhel8:7.5 --confirm

10. Update the image change trigger in the existing deployment config to reference the Red Hat Single Sign-On 7.5.3 image.

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

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

    $ oc rollout latest dc/sso

12. Scale the sso pod back up to one replica.

    Note

    You might want to temporarily increase the Liveness and Readiness Probes thresholds and values in seconds from dc/sso. This step performs a Database Upgrade on the first boot, which might take a while.

    $ oc scale --replicas=1 dc/sso

    Note

    If you have more than one replica, consider scaling up to a single replica. After Red Hat Single Sign-On starts, you can scale back to the original number of replicas.

1. 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

2. Stop all pods running the previous version of the Red Hat Single Sign-On for OpenShift image in the current namespace. They cannot run concurrently against the same database.

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

3. Update the image change trigger in the existing deployment config to reference the Red Hat Single Sign-On 7.5.3 image.

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

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

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

5. Deploy Red Hat Single Sign-On 7.5.3 containers using the modified deployment config.

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

6. (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

1. Configure Red Hat Single Sign-On 7.5.3 with the correct datasource,

2. Set the following configuration options in the standalone-openshift.xml file:

   1. initializeEmpty=false,
   2. migrationStrategy=manual, and
   3. migrationExport to the location on the file system of the pod, where the output SQL migration file should be stored (for example, migrationExport="${jboss.home.dir}/keycloak-database-update.sql").

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

   $ cat job-to-migrate-db-to-sso75.yaml.orig
   apiVersion: batch/v1
   kind: Job
   metadata:
     name: job-to-migrate-db-to-sso75
   spec:
     autoSelector: true
     parallelism: 0
     completions: 1
     template:
       metadata:
         name: job-to-migrate-db-to-sso75
       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-sso75
           # 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-sso75.yaml.orig \
        job-to-migrate-db-to-sso75.yaml

2. 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-sso75.yaml.

   Note

   Although the DB_SERVICE_PREFIX_MAPPING environment variable allows a comma-separated list of <name>-<database_type>=<PREFIX> triplets as its value, this example script accepts only one datasource triplet definition for demonstration purposes. You can modify the script for handling multiple datasource definition triplets.

   $ 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-sso75.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

3. Build the Red Hat Single Sign-On 7.5.3 database migration image using the pre-configured source and wait for the build to finish.

   $ oc get is -n openshift | grep sso75 | cut -d ' ' -f1
   sso75-openshift-rhel8

   $ oc new-build sso75-openshift-rhel8:7.5~https://github.com/iankko/openshift-examples.git#KEYCLOAK-8500 \
     --context-dir=sso-manual-db-migration \
     --name=sso75-db-migration-image
   --> Found image bf45ac2 (7 days old) in image stream "openshift/sso75-openshift-rhel8" under tag "7.5" for "sso75-openshift-rhel8:7.5"
   
       Red Hat SSO 7.5.3
       ---------------
       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 "sso75-db-migration-image:latest"
         * Use 'start-build' to trigger a new build
   
   --> Creating resources with label build=sso75-db-migration-image ...
       imagestream "sso75-db-migration-image" created
       buildconfig "sso75-db-migration-image" created
   --> Success
       Build configuration "sso75-db-migration-image" created and build triggered.
       Run 'oc logs -f bc/sso75-db-migration-image' to stream the build progress.

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

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

   1. Get the docker pull reference for the image.

      $ PULL_REF=$(oc get istag -n $(oc project -q) --no-headers | grep sso75-db-migration-image | tr -s ' ' | cut -d ' ' -f 2)

   2. Replace the <<SSO_IMAGE_VALUE>> field in the job template with the pull specification.

      $ sed -i "s#<<SSO_IMAGE_VALUE>>#$PULL_REF#g" job-to-migrate-db-to-sso75.yaml

   3. Verify that the field is updated.

5. Instantiate database migration job from the job template.

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

   Important

   The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all pods running the previous version of the Red Hat Single Sign-On for OpenShift image before dynamic generation of the SQL migration file.

6. 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

7. 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

8. 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-sso75   1         0            3m

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

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

   Note

   By default, the database migration job terminates automatically after 600 seconds after the migration file is generated. You can adjust this time period.

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

   $ mkdir -p ./db-update
   $ oc rsync job-to-migrate-db-to-sso75-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

10. Inspect the keycloak-database-update.sql file for changes to be performed within manual database update to Red Hat Single Sign-On 7.5.3 version.

11. Apply the database update manually.

    • Run the following commands if running some previous version of the Red Hat Single Sign-On for OpenShift image, backed by the PostgreSQL database deployed in ephemeral or persistent mode, running on a separate pod:

      1. Copy the generated SQL migration file to the PostgreSQL pod.

         $ oc rsync --no-perms=true ./db-update/ sso-postgresql-1-n5p16:/tmp
         sending incremental file list
         
         sent 77 bytes  received 11 bytes  176.00 bytes/sec
         total size is 26,333  speedup is 299.24

      2. Start a shell session to the PostgreSQL pod.

         $ oc rsh sso-postgresql-1-n5p16
         sh-4.2$

      3. Use the psql tool to apply database update manually.

         sh-4.2$ alias psql="/opt/rh/rh-postgresql95/root/bin/psql"
         sh-4.2$ psql --version
         psql (PostgreSQL) 9.5.4
         sh-4.2$ psql -U <PREFIX>_USERNAME -d <PREFIX>_DATABASE -W -f /tmp/keycloak-database-update.sql
         Password for user <PREFIX>_USERNAME:
         INSERT 0 1
         INSERT 0 1
         ...

         Important

         Replace <PREFIX>_USERNAME and <PREFIX>_DATABASE with the actual database credentials retrieved in previous section. Also use value of <PREFIX>_PASSWORD as the password for the database, when prompted.

      4. Close the shell session to the PostgreSQL pod. Continue with updating image change trigger step.

12. Update the image change trigger in the existing deployment config to reference the Red Hat Single Sign-On 7.5.3 image.

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

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

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

14. Deploy the Red Hat Single Sign-On 7.5.3 containers using the modified deployment config.

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

Procedure

1. Log in to the OpenShift web console and select the sso-app-demo project space.
2. Click Add to project to list 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. Select sso75-postgresql Red Hat Single Sign-On application template. When deploying the template ensure to keep the SSO_REALM variable unset (default value).

   Warning

   When the SSO_REALM configuration variable is set on the Red Hat Single Sign-On for OpenShift image, a database import is performed in order to create the Red Hat Single Sign-On server realm requested in the variable. For the database export to be performed correctly, the SSO_REALM configuration variable cannot be simultaneously defined on such image.

5. 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.

   Note

   This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. Accessing the Red Hat Single Sign-On web console will prompt an insecure connection warning.
   For production environments, Red Hat recommends that you use an SSL certificate purchased from a verified Certificate Authority.

1. Create a realm
2. Create a user

Procedure

1. Get the Red Hat Single Sign-On deployment config and scale it down to zero.

   $ oc get dc -o name
   deploymentconfig/sso
   deploymentconfig/sso-postgresql
   
   $ oc scale --replicas=0 dc sso
   deploymentconfig "sso" scaled

2. Instruct the Red Hat Single Sign-On 7.5.3 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"

3. 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

4. (Optional) Verify that the export was successful.

   $ oc get pods
   NAME                     READY     STATUS    RESTARTS   AGE
   sso-4-ejr0k              1/1       Running   0          27m
   sso-postgresql-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

Procedure

1. 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-postgresql-1-ozzl0   1/1       Running   0          4h
   
   $ oc rsync sso-4-ejr0k:/tmp/demorealm-export.json .

2. (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.

   Note

   For importing into an Red Hat Single Sign-On server not running on OpenShift, see the Importing and exporting the database.

   When the Red Hat Single Sign-On server is running as a Red Hat Single Sign-On 7.5.3 container on OpenShift, use the Admin Console Export/Import function to import the resources from a previously exported JSON file into the Red Hat Single Sign-On server’s database.

   1. Log into the master realm’s Admin Console of the Red Hat Single Sign-On server using the credentials used to create the administrator user. In the browser, navigate to http://sso-<project-name>.<hostname>/auth/admin for the Red Hat Single Sign-On web server, or to https://secure-sso-<project-name>.<hostname>/auth/admin for the encrypted Red Hat Single Sign-On web server.
   2. At the top of the sidebar choose the name of the Red Hat Single Sign-On realm, the users, clients, realm roles, and client roles should be imported to. This example uses master realm.
   3. Click the Import link under Manage section at the bottom of the sidebar.
   4. In the page that opens, click Select file and then specify the location of the exported demorealm-export.json JSON file on the local file system.
   5. From the Import from realm drop-down menu, select the name of the Red Hat Single Sign-On realm from which the data should be imported. This example uses master realm.
   6. Choose which of users, clients, realm roles, and client roles should be imported (all of them are imported by default).

   7. Choose a strategy to perform, when a resource already exists (one of Fail, Skip, or Overwrite).

      Note

      The attempt to import an object (user, client, realm role, or client role) fails if object with the same identifier already exists in the current database. Use Skip strategy to import the objects that are present in the demorealm-export.json file, but do not exist in current database.

   8. Click Import to perform the import.

      When importing objects from a non-master realm to master realm or vice versa, after clicking the Import button, it is sometimes possible to encounter an error like the following one:

      

      In such cases, it is necessary first to create the missing clients, having the Access Type set to bearer-only. These clients can be created by manual copy of their characteristics from the source Red Hat Single Sign-On server, on which the export JSON file was created, to the target Red Hat Single Sign-On server, where the JSON file is imported. After creation of the necessary clients, click the Import button again.

      To suppress the above error message, it is needed to create the missing realm-management client, of the bearer-only Access Type, and click the Import button again.

      For Skip import strategy, the newly added objects are marked as ADDED and the object which were skipped are marked as SKIPPED, in the Action column on the import result page.

      The Admin Console import allows you to overwrite resources if you choose (Overwrite strategy). On a production system use this feature with caution.

1. Hover your cursor over the realm namespace (default is Master) at the top of the sidebar and click Add Realm.
2. Enter a realm name (this example uses OpenShift) and click Create.

1. Click Users in the Manage sidebar to view the user information for the realm.
2. Click Add User.
3. Enter a valid Username (this example uses testuser) and any additional optional information and click Save.

4. Edit the user configuration:

   1. Click the Credentials tab in the user space and enter a password for the user.
   2. Ensure the Temporary Password option is set to Off so that it does not prompt for a password change later on, and click Reset Password to set the user password. A pop-up window prompts for additional confirmation.

1. Click Clients in the Manage sidebar and click Create.
2. Enter the Client ID. This example uses openshift-demo.
3. Select a Client Protocol from the drop-down menu (this example uses openid-connect) and click Save. You will be taken to the configuration Settings page of the openshift-demo client.
4. From the Access Type drop-down menu, select confidential. This is the access type for server-side applications.
5. In the Valid Redirect URIs dialog, enter the URI for the OpenShift web console, which is https://openshift.example.com:8443/* in this example.

Procedure

1. Edit the /etc/origin/master/master-config.yaml file and find the identityProviders section. 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

   1. The Red Hat Single Sign-On Secret hash for the clientSecret can be found in the Red Hat Single Sign-On web console: Clients → openshift-demo → Credentials

   2. The endpoints for the urls can be found by making a request with the Red Hat Single Sign-On application. For example:

      <curl -k https://secure-sso-sso-app-demo.openshift32.example.com/auth/realms/OpenShift/.well-known/openid-configuration | python -m json.tool>

      The response includes the authorization_endpoint, token_endpoint, and userinfo_endpoint.

   3. This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. For this reason, the ca is provided as <ca: xpaas.crt>. This CA certificate must also be copied into the /etc/origin/master folder. This is not necessary if using a certificate purchased from a verified Certificate Authority.

2. Save the configuration and restart the OpenShift master:

   $ systemctl restart atomic-openshift-master

Procedure

1. Navigate to the OpenShift web console, which in this example is https://openshift.example.com:8443/console.

   The OpenShift login page now offers the options to log in either using htpasswd_auth or rh-sso identity providers? The former is still available because it is present in the /etc/origin/master/master-config.yaml.

2. Select rh-sso and log in to OpenShift with the testuser user created earlier in Red Hat Single Sign-On.

   No projects are visible to testuser until they are added in the OpenShift CLI. This is the only way to provide user privileges in OpenShift because it currently does not accept external role mapping.

3. To provide testuser view privileges for the sso-app-demo, use the OpenShift CLI:

   $ oc adm policy add-role-to-user view testuser -n sso-app-demo

1. Create a new project:

   $ oc new-project eap-app-demo

2. 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

3. 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.
   

   1. Generate a secure key for the SSL keystore:

      $ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks

   2. Generate a secure key for the JGroups keystore:

      $ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks

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

   $ oc create secret generic eap-ssl-secret --from-file=eapkeystore.jks
   $ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks

5. Add the EAP secret to the default service account:

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

1. Hover your cursor over the realm namespace at the top of the sidebar and click Add Realm.
2. Enter a realm name (this example uses eap-demo) and click Create.

1. Click Roles in the Configure sidebar to list the roles for this realm. This is a new realm, so there should only be the default offline_access role.
2. Click Add Role.
3. Enter the role name (this example uses the role eap-user-role) and click Save.

1. Click Users in the Manage sidebar to view the user information for the realm.
2. Click Add User.
3. Enter a valid Username (this example uses the user eap-mgmt-user) and click Save.
4. 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 Reset Password to set the user password. A pop-up window prompts for additional confirmation.
5. 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 Red Hat Single Sign-On server rights that can be used by the JBoss EAP image to create clients.

1. Click Users in the Manage sidebar to view the user information for the realm.
2. Click Add User.
3. Enter a valid Username and any additional optional information for the application user and click Save.
4. 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 Reset Password to set the user password. A pop-up window prompts for additional confirmation.
5. Click Role Mappings to list the realm and client role configuration. In Available Roles, add the role created earlier.

1. Return to the OpenShift web console and click Add to project to list 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. 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:

   Variable	Example Value
   APPLICATION_NAME	sso
   HOSTNAME_HTTPS	secure-sample-jsp.eap-app-demo.openshift32.example.com
   HOSTNAME_HTTP	sample-jsp.eap-app-demo.openshift32.example.com
   SOURCE_REPOSITORY_URL	https://repository-example.com/developer/application
   SSO_URL	https://secure-sso-sso-app-demo.openshift32.example.com/auth
   SSO_REALM	eap-demo
   SSO_USERNAME	eap-mgmt-user
   SSO_PASSWORD	password
   SSO_PUBLIC_KEY	<realm-public-key>
   HTTPS_KEYSTORE	eapkeystore.jks
   HTTPS_PASSWORD	password
   HTTPS_SECRET	eap-ssl-secret
   JGROUPS_ENCRYPT_KEYSTORE	eapjgroups.jceks
   JGROUPS_ENCRYPT_PASSWORD	password
   JGROUPS_ENCRYPT_SECRET	eap-jgroup-secret

4. Click Create to deploy the JBoss EAP image.

Procedure

1. Access the JBoss EAP application server and click Login. You are redirected to the Red Hat Single Sign-On login.
2. Log in using the Red Hat Single Sign-On user created in the example. You are authenticated against the Red Hat Single Sign-On server and returned to the JBoss EAP application server.

1. Hover your cursor over the realm namespace (default is Master) at the top of the sidebar and click Add Realm.
2. Enter a realm name (this example uses saml-demo) and click Create.

1. Click Roles in the Configure sidebar to list the roles for this realm. This is a new realm, so there should only be the default offline_access role.
2. Click Add Role.
3. Enter the role name (this example uses the role saml-user-role) and click Save.

1. Click Users in the Manage sidebar to view the user information for the realm.
2. Click Add User.
3. Enter a valid Username (this example uses the user app-mgmt-user) and click Save.
4. 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 Reset Password to set the user password. A pop-up window prompts for additional confirmation.

1. Click Users in the Manage sidebar to view the user information for the realm.
2. Click Add User.
3. Enter a valid Username and any additional optional information for the application user and click Save.
4. 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 Reset Password to set the user password. A pop-up window prompts for additional confirmation.
5. Click Role Mappings to list the realm and client role configuration. In Available Roles, add the role created earlier.

1. Click Clients in the Configure sidebar to list the clients in the realm. Click Create.
2. Enter a valid Client ID. This example uses sso-saml-demo.
3. In the Client Protocol drop-down menu, select saml.
4. Enter the Root URL for the application. This example uses https://demoapp-eap-app-demo.openshift32.example.com.
5. Click Save.

1. For the Root URL, enter the same address used when creating the client. This example uses https://demoapp-eap-app-demo.openshift32.example.com.
2. For the Valid Redirect URLs, enter an address for users to be redirected to at when they log in or out. This example uses a redirect address relative to the root https://demoapp-eap-app-demo.openshift32.example.com/*.

1. Click the SAML Keys tab in the sso-saml-demo client space and click Export.
2. For this example, leave the Archive Format as JKS. This example uses the default Key Alias of sso-saml-demo and default Realm Certificate Alias of saml-demo.
3. Enter the Key Password and the Store Password. This example uses password for both.
4. Click Download and save the keystore-saml.jks file for use later.
5. Click the sso-saml-demo client to return to the client space ready for the next step.

1. Click Installation.
2. Use the Format Option drop-down menu to select a format. This example uses Keycloak SAML Wildfly/JBoss Subsystem.
3. Click Download and save the file keycloak-saml-subsystem.xml.

Procedure

1. Create a new project:

   $ oc new-project eap-app-demo

2. 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

3. 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.
   

   1. Generate a secure key for the SSL keystore:

      $ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks

   2. Generate a secure key for the JGroups keystore:

      $ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks

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

   $ oc create secret generic eap-ssl-secret --from-file=eapkeystore.jks
   $ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks

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

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

Procedure

1. Open the /configuration/secure-saml-deployments file in a text editor.
2. Replace the YOUR-WAR.war value of the secure-deployment name tag with the application .war file. This example uses sso-saml-demo.war.
3. Replace the SPECIFY YOUR LOGOUT PAGE! value of the logout page tag with the url to redirect users when they log out of the application. This example uses /index.jsp.

4. 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.

5. 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.

6. Save and close the /configuration/secure-saml-deployments file.