== Tutorials

[role="_abstract"]
The tutorials in this chapter assume that you have an OpenShift instance similar to the one created by performing link:{ocpdocs_install_cluster_link}[the installation of the OpenShift Container Platform cluster].

[[upgrading-sso-db-from-previous-version]]
=== Updating a database for a new {project_openshift_product_name} image version

Note the following points related to the update:

* Rolling updates from a previous versions of {project_openshift_product_name} to version {project_version} are not supported as databases and caches are not backward compatible.
* Instances from versions of the {project_openshift_product_name} cannot be runnng before upgrade. They cannot run concurrently against the same database.
* Pre-generated scripts are not available. They are generated dynamically depending on the database.

You have two choices for updating the database:

* Allow {project_name} {project_version} to xref:automatic-db-migration[automatically migrate the database schema]
* Update the database xref:manual-db-migration[manually]

[NOTE]
====
By default the database is automatically migrated when you start {project_name} {project_version} for the first time.
====

[[automatic-db-migration]]
==== Automatic database migration
This process assumes that you are running a previous version of the {project_openshift_product_name} image, backed by a PostgreSQL database (deployed in ephemeral or persistent mode) that is running in a separate pod.

.Prerequisites

* Perform the steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment].

.Procedure
Use the following steps to automatically migrate the database schema:

. Identify the deployment config used to deploy the containers, running previous version of the {project_openshift_product_name} image.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql
----
. Stop all pods running the previous version of the {project_openshift_product_name} image in the current namespace. They cannot run concurrently against the same database.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale --replicas=0 dc/sso
deploymentconfig "sso" scaled
----
. Update the image change trigger in the existing deployment config to reference the {project_name} {project_version} image.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "{openshift_image_stream}:{project_latest_image_tag}"}]'
"sso" patched
----
. Start rollout of the new {project_name} {project_version} images based on the latest image defined in the image change triggers.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc rollout latest dc/sso
deploymentconfig "sso" rolled out
----
. Deploy {project_name} {project_version} containers using the modified deployment config.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled
----
. (Optional) Verify the database has been successfully updated.
+
[source,bash,subs="attributes+,macros+"]
----
$ 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
----
+
[source,bash,subs="attributes+,macros+"]
----
$ 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
----

[[manual-db-migration]]
==== Manual database migration

The database migration process updates the data schema and performs manipulation of the data. This process also stops all pods running the previous version of the {project_openshift_product_name} image before dynamic generation of the SQL migration file.

[NOTE]
====
This process assumes that you are running a previous version of the {project_openshift_product_name} image that is backed by a PostgreSQL database (deployed in ephemeral or persistent mode) and is running on a separate pod.
====

.Procedure
Prepare your environment for script generation.

. Configure {project_name} {project_version} with the correct datasource,
. Set the following configuration options in the `standalone-openshift.xml` file:
.. `initializeEmpty=false`,
.. `migrationStrategy=manual`, and
.. `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"`).


[role="_additional-resources"]
.Additional resources

* link:{project_doc_base_url}/server_installation_and_configuration_guide/database-1#database_configuration[Database configuration]

.Procedure
Perform the following to generate the SQL migration file for the database:

. Prepare template of OpenShift link:{ocpdocs_jobs_link}[database migration job] to generate the SQL file.
+
[source,yaml,subs="verbatim,macros,attributes"]
----
$ cat job-to-migrate-db-to-{project_templates_version}.yaml.orig
apiVersion: batch/v1
kind: Job
metadata:
  name: job-to-migrate-db-to-{project_templates_version}
spec:
  autoSelector: true
  parallelism: 0
  completions: 1
  template:
    metadata:
      name: job-to-migrate-db-to-{project_templates_version}
    spec:
      containers:
      - env:
        - name: DB_SERVICE_PREFIX_MAPPING
          value: pass:[&lt;&lt;DB_SERVICE_PREFIX_MAPPING_VALUE&gt;&gt;]
        - name: pass:[&lt;&lt;PREFIX&gt;&gt;]_JNDI
          value: pass:[&lt;&lt;PREFIX_JNDI_VALUE&gt;&gt;]
        - name: pass:[&lt;&lt;PREFIX&gt;&gt;]_USERNAME
          value: pass:[&lt;&lt;PREFIX_USERNAME_VALUE&gt;&gt;]
        - name: pass:[&lt;&lt;PREFIX&gt;&gt;]_PASSWORD
          value: pass:[&lt;&lt;PREFIX_PASSWORD_VALUE&gt;&gt;]
        - name: pass:[&lt;&lt;PREFIX&gt;&gt;]_DATABASE
          value: pass:[&lt;&lt;PREFIX_DATABASE_VALUE&gt;&gt;]
        - name: TX_DATABASE_PREFIX_MAPPING
          value: pass:[&lt;&lt;TX_DATABASE_PREFIX_MAPPING_VALUE&gt;&gt;]
        - name: pass:[&lt;&lt;SERVICE_HOST&gt;&gt;]
          value: pass:[&lt;&lt;SERVICE_HOST_VALUE&gt;&gt;]
        - name: pass:[&lt;&lt;SERVICE_PORT&gt;&gt;]
          value: pass:[&lt;&lt;SERVICE_PORT_VALUE&gt;&gt;]
        image: pass:[&lt;&lt;SSO_IMAGE_VALUE&gt;&gt;]
        imagePullPolicy: Always
        name: job-to-migrate-db-to-{project_templates_version}
        # 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
----
+
[source,bash,subs="attributes+,macros+"]
----
$ cp job-to-migrate-db-to-{project_templates_version}.yaml.orig \
     job-to-migrate-db-to-{project_templates_version}.yaml
----
. From deployment config used to run the previous version of the {project_openshift_product_name} 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-{project_templates_version}.yaml`.
+
[NOTE]
====
Although the `DB_SERVICE_PREFIX_MAPPING` environment variable allows a link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.1/html-single/red_hat_jboss_enterprise_application_platform_for_openshift/index#datasources[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.
====
+
[source,bash,subs="verbatim,macros,attributes"]
----
$ 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-{project_templates_version}.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 pass:[&lt;&lt;SERVICE&gt;&gt;]_SERVICE_HOST
# and pass:[&lt;&lt;SERVICE&gt;&gt;]_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:
# * pass:[&lt;&lt;SERVICE_HOST&gt;&gt;] with ${SERVICE}_SERVICE_HOST and
# * pass:[&lt;&lt;SERVICE_HOST_VALUE&gt;&gt;] with pass:[&lt;&lt;${SERVICE}_SERVICE_HOST_VALUE&gt;&gt;]
# The order in which replacements are made is important!
# Do this for both "HOST" and "PORT"
for KEY in "HOST" "PORT"
do
  PATTERN_1=pass:["&lt;&lt;SERVICE_${KEY}&gt;&gt;"]
  REPL_1="${SERVICE}_SERVICE_${KEY}"
  sed -i "s#${PATTERN_1}#${REPL_1}#g" ${JOB_MIGRATION_YAML}
  PATTERN_2=pass:["&lt;&lt;SERVICE_${KEY}_VALUE&gt;&gt;"]
  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}" &&
      pass:[grep -q "&lt;&lt;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
----
+
[[get-db-credentials]]
Run the script.
+
[source,bash,subs="attributes+,macros+"]
----
$ 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 {project_name} {project_version} database migration image using the link:https://github.com/iankko/openshift-examples/tree/KEYCLOAK-8500/sso-manual-db-migration[pre-configured source] and wait for the build to finish.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get is -n openshift | grep {project_templates_version} | cut -d ' ' -f1
{openshift_image_stream}
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc new-build {openshift_image_stream}:{project_latest_image_tag}~https://github.com/iankko/openshift-examples.git#KEYCLOAK-8500 \
  --context-dir=sso-manual-db-migration \
  --name={project_templates_version}-db-migration-image
--> Found image bf45ac2 (7 days old) in image stream "openshift/{openshift_image_stream}" under tag "{project_latest_image_tag}" for "{openshift_image_stream}:{project_latest_image_tag}"

    Red Hat SSO {project_version}
    ---------------
    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 "{project_templates_version}-db-migration-image:latest"
      * Use 'start-build' to trigger a new build

--> Creating resources with label build={project_templates_version}-db-migration-image ...
    imagestream "{project_templates_version}-db-migration-image" created
    buildconfig "{project_templates_version}-db-migration-image" created
--> Success
    Build configuration "{project_templates_version}-db-migration-image" created and build triggered.
    Run 'oc logs -f bc/{project_templates_version}-db-migration-image' to stream the build progress.
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc logs -f bc/{project_templates_version}-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-{project_templates_version}.yaml`) with reference to the built `{project_templates_version}-db-migration-image` image.
.. Get the docker pull reference for the image.
+
[source,bash,subs="attributes+,macros+"]
----
$ PULL_REF=$(oc get istag -n $(oc project -q) --no-headers | grep {project_templates_version}-db-migration-image | tr -s ' ' | cut -d ' ' -f 2)
----
.. Replace the pass:[&lt;&lt;SSO_IMAGE_VALUE&gt;&gt;] field in the job template with the pull specification.
+
[source,bash,subs="attributes+,macros+"]
----
$ sed -i "s#pass:[&lt;&lt;SSO_IMAGE_VALUE&gt;&gt;]#$PULL_REF#g" job-to-migrate-db-to-{project_templates_version}.yaml
----
.. Verify that the field is updated.
. Instantiate database migration job from the job template.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc create -f job-to-migrate-db-to-{project_templates_version}.yaml
job "job-to-migrate-db-to-{project_templates_version}" 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 {project_openshift_product_name} image before dynamic generation of the SQL migration file.
====
+
. Identify the deployment config used to deploy the containers, running previous version of the {project_openshift_product_name} image.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql
----
. Stop all pods running the previous version of the {project_openshift_product_name} image in the current namespace.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale --replicas=0 dc/sso
deploymentconfig "sso" scaled
----
. Run the database migration job and wait for the pod to be running correctly.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get jobs
NAME                            DESIRED   SUCCESSFUL   AGE
job-to-migrate-db-to-{project_templates_version}   1         0            3m
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale --replicas=1 job/job-to-migrate-db-to-{project_templates_version}
job "job-to-migrate-db-to-{project_templates_version}" scaled
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get pods
NAME                                  READY     STATUS      RESTARTS   AGE
sso-postgresql-1-n5p16                1/1       Running     1          19h
job-to-migrate-db-to-{project_templates_version}-b87bb   1/1       Running     0          1m
{project_templates_version}-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.
====
. Get the dynamically generated SQL database migration file from the pod.
+
[source,bash,subs="attributes+,macros+"]
----
$ mkdir -p ./db-update
$ oc rsync job-to-migrate-db-to-{project_templates_version}-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
----
. Inspect the `keycloak-database-update.sql` file for changes to be performed within manual database update to {project_name} {project_version} version.
. Apply the database update manually.
* Run the following commands if running some previous version of the {project_openshift_product_name} image, backed by the PostgreSQL database deployed in ephemeral or persistent mode, running on a separate pod:
... Copy the generated SQL migration file to the PostgreSQL pod.
+
[source,bash,subs="attributes+,macros+"]
----
$ 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
----
... Start a shell session to the PostgreSQL pod.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc rsh sso-postgresql-1-n5p16
sh-4.2$
----
... Use the `psql` tool to apply database update manually.
+
[source,bash,subs="attributes+,macros+"]
----
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 xref:get-db-credentials[in previous section]. Also use value of `<PREFIX>_PASSWORD` as the password for the database, when prompted.
====
... Close the shell session to the PostgreSQL pod. Continue with xref:image-change-trigger-update-step[updating image change trigger step].

[[image-change-trigger-update-step]]
[start=12]
. Update the image change trigger in the existing deployment config to reference the {project_name} {project_version} image.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "{openshift_image_stream}:{project_latest_image_tag}"}]'
"sso" patched
----
. Start rollout of the new {project_name} {project_version} images based on the latest image defined in the image change triggers.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc rollout latest dc/sso
deploymentconfig "sso" rolled out
----
. Deploy the {project_name} {project_version} containers using the modified deployment config.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled
----

=== Migrating the {project_name} server's database across environments
This tutorial focuses on migrating the {project_name} server database from one environment to another or migrating to a different database.

Export and import of {project_name} {project_version} database is triggered at {project_name} server boot time and its parameters are passed in via Java system properties. This means during one {project_name} server boot, only one of the possible migration actions, *_export_* or *_import_*, is performed.

==== Deploying the {project_name} PostgreSQL application template

.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.

.Procedure
. Log in to the OpenShift web console and select the *sso-app-demo* project space.
. Click *Add to project* to list the default image streams and templates.
. 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.
. Select *_{project_templates_version}-postgresql_* {project_name} 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 {project_openshift_product_name} image, a database import is performed in order to create the {project_name} 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.
====
+
. Click *Create* to deploy the application template and start pod deployment. This may take a couple of minutes.
+
Then access the {project_name} web console at *$$https://secure-sso-$$_<sso-app-demo>_._<openshift32.example.com>_/auth/admin* using the xref:sso-administrator-setup[administrator account].
+
[NOTE]
====
This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. Accessing the {project_name} 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.
====

[role="_additional-resources"]
.Additional resources
* link:{project_doc_base_url}/server_administration_guide/#assembly-exporting-importing_server_administration_guide[Importing and exporting the database]

==== (Optional) Creating additional realms and users to be exported

When performing {project_name} {project_version} server database export, only realms and users currently in the database are exported. If the exported JSON file should include also additional {project_name} realms and users, these need to be created. Use these procedures.

. link:{project_doc_base_url}//server_administration_guide/index#proc-creating-a-realm_server_administration_guide[Create a realm]
. link:{project_doc_base_url}//server_administration_guide/index#proc-creating-user_server_administration_guide[Create a user]

Upon their creation, the database can be exported.

[role="_additional-resources"]
.Additional resources
* link:{project_doc_base_url}//server_administration_guide/#assembly-exporting-importing_server_administration_guide[Importing and exporting the database]

[[sso-export-the-database]]
==== Export the {project_name} database as a JSON file on the OpenShift pod

.Prerequisites

* New realms and users are created.

.Procedure
. Get the {project_name} deployment config and scale it down to zero.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get dc -o name
deploymentconfig/sso
deploymentconfig/sso-postgresql

$ oc scale --replicas=0 dc sso
deploymentconfig "sso" scaled
----
. Instruct the {project_name} {project_version} server deployed on {project_openshift_product_name} image to perform database export at {project_name} server boot time.
+
[source,bash,subs="attributes+,macros+"]
----
$ 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 {project_name} deployment config back up. This will start the {project_name} server and export its database.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale --replicas=1 dc sso
deploymentconfig "sso" scaled
----
. (Optional) Verify that the export was successful.
+
[source,bash,subs="attributes+,macros+"]
----
$ 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
----

==== Retrieve and import the exported JSON file

.Procedure

. Retrieve the JSON file of the {project_name} database from the pod.
+
[source,bash,subs="attributes+,macros+"]
----
$ 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 .
----

. (Optional) Import the JSON file of the {project_name} database into an {project_name} server running in another environment.
+
[NOTE]
====
For importing into an {project_name} server not running on OpenShift, see the link:{project_doc_base_url}/server_administration_guide/#assembly-exporting-importing_server_administration_guide[Importing and exporting the database].
====
+
When the {project_name} server is running as a {project_name} {project_version} container on OpenShift, use the
link:{project_doc_base_url}/server_administration_guide/#assembly-exporting-importing_server_administration_guide[Admin Console Export/Import] function to import the resources from a previously exported JSON file into the {project_name} server's database.

.. Log into the `master` realm's Admin Console of the {project_name} server using the credentials used to create the administrator user. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin*  for the {project_name} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server.
.. At the top of the sidebar choose the name of the {project_name} realm, the users, clients, realm roles, and client roles should be imported to. This example uses `master` realm.
.. Click the *Import* link under *Manage* section at the bottom of the sidebar.
.. 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.
.. From the *Import from realm* drop-down menu, select the name of the {project_name} realm from which the data should be imported. This example uses `master` realm.
.. Choose which of users, clients, realm roles, and client roles should be imported (all of them are imported by default).
.. 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.
====
.. 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:
+
[[realm-import-error-message]]
[.text-center]
image:images/import_realm_error.png[Example of Possible Error Message when Performing Partial Import from Previously Exported JSON File]
+
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 {project_name} server, on which the export JSON file was created, to the target {project_name} server, where the JSON file is imported. After creation of the necessary clients, click the *Import* button again.
+
To suppress the xref:realm-import-error-message[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.


[[OSE-SSO-AUTH-TUTE]]
=== Configuring OpenShift 3.11 to use {project_name} for Authentication
Configure OpenShift 3.11 to use the {project_name} deployment as the authorization gateway for OpenShift. 

This example adds {project_name} as an authentication method alongside the identity providers configured during the installation of the OpenShift Container Platform cluster. Once configured, the {project_name} method will be also available (together with the configured identity providers) for the user login to your OpenShift web console.

[role="additional-resources"]
.Additional resources
* link:{ocpdocs_idp_config_link}[Identity providers]
* link:{ocpdocs_install_cluster_link}[Installation of the OpenShift Container Platform cluster]

==== Configuring {project_name} Credentials

.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.

.Procedure
Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_sso-app-demo_._openshift32.example.com_/auth/admin* using the xref:sso-administrator-setup[administrator account created during the {project_name} deployment.

*Create a Realm*

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

*Create a User*

Create a test user that can be used to demonstrate the {project_name}-enabled OpenShift login:

. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*.
. Enter a valid *Username* (this example uses _testuser_) and any additional optional information and click *Save*.
. Edit the user configuration:
.. Click the *Credentials* tab in the user space and enter a password for the user.
.. 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.

*Create and Configure an OpenID-Connect Client*

. Click *Clients* in the *Manage* sidebar and click *Create*.
. Enter the *Client ID*. This example uses _openshift-demo_.
. 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.
. From the *Access Type* drop-down menu, select *confidential*. This is the access type for server-side applications.
. In the *Valid Redirect URIs* dialog, enter the URI for the OpenShift web console, which is _$$https://openshift$$.example.com:8443/*_ in this example.

The client *Secret* is needed to configure OpenID-Connect on the OpenShift master in the next section. You can copy it now from under the *Credentials* tab. The secret is <pass:quotes[_7b0384a2-b832-16c5-9d73-2957842e89h7_]> for this example.

[role="additional-resources"]
.Additional resources
* link:{project_doc_base_url}//server_administration_guide/index#assembly-managing-clients_server_administration_guide[Managing OpenID Connect and SAML Clients]

==== Configuring OpenShift Master for {project_name} authentication
Log in to the OpenShift master CLI. 

.Prerequisites
You must have the permissions to edit the */etc/origin/master/master-config.yaml* file.

.Procedure

. 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 link:{ocpdocs_htpasswd_idp_link}[HTPassword identity provider], the *identityProviders* section will look similar to the following one:
+
[source,bash,subs="attributes+,macros+"]
----
identityProviders:
- challenge: true
  login: true
  name: htpasswd_auth
  provider:
    apiVersion: v1
    file: /etc/origin/openshift-passwd
    kind: HTPasswdPasswordIdentityProvider
----
+
Add {project_name} as a secondary identity provider with content similar to the following snippet:
+
[source,bash,subs="attributes+,macros+"]
----
- name: rh_sso
  challenge: false
  login: true
  mappingMethod: add
  provider:
    apiVersion: v1
    kind: OpenIDIdentityProvider
    clientID: pass:quotes[_openshift-demo_]
    clientSecret: pass:quotes[_7b0384a2-b832-16c5-9d73-2957842e89h7_]
    pass:quotes[_ca: xpaas.crt_]
    urls:
      authorize: pass:quotes[_https://secure-sso-sso-app-demo.openshift32.example.com/auth/realms/OpenShift/protocol/openid-connect/auth_]
      token: pass:quotes[_https://secure-sso-sso-app-demo.openshift32.example.com/auth/realms/OpenShift/protocol/openid-connect/token_]
      userInfo: pass:quotes[_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
----
.. The {project_name} *Secret* hash for the *clientSecret* can be found in the {project_name} web console: *Clients* -> *_openshift-demo_* -> *Credentials*
.. The endpoints for the *urls* can be found by making a request with the {project_name} application. For example:
+
[source,bash,subs="attributes+,macros+"]
----
<pass:quotes[_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*.
+
.. 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 <pass:quotes[_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.
. Save the configuration and restart the OpenShift master:
+
[source,bash,subs="attributes+,macros+"]
----
$ systemctl restart atomic-openshift-master
----

==== Logging in to OpenShift

.Procedure

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

.  Select *rh-sso* and log in to OpenShift with the _testuser_ user created earlier in {project_name}.
+
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.

. To provide _testuser_ `view` privileges for the *sso-app-demo*, use the OpenShift CLI:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc adm policy add-role-to-user view testuser -n sso-app-demo
----

[[binary-builds]]
=== Creating an OpenShift application from  maven binaries and securing it using {project_name}

To deploy existing applications on OpenShift, you can use the binary source capability.

==== Deploy Binary Build of EAP 6.4 / 7.1 JSP Service Invocation Application and Secure it Using {project_name}

The following example uses both link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstarts to deploy EAP 6.4 / 7.1 JSP service application that authenticates using the {project_name}.

.Prerequisites

* The {project_openshift_product_name} image has been previously deployed using one of the following templates:

* *_{project_templates_version}-postgresql_*
* *_{project_templates_version}-postgresql-persistent_*
* *_{project_templates_version}-x509-postgresql-persistent_*

===== Create {project_name} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application

The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name} realm, username, and password to be able to authenticate using {project_name}. Perform the following steps after the {project_openshift_product_name} image has been deployed:

*Create the {project_name} Realm*

. Login to the Admin Console of the {project_name} server.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
+
Use the xref:sso-administrator-setup[credentials of the {project_name} administrator user].

. Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*.

. Enter a realm name (this example uses `demo`) and click *Create*.

[[copy-rsa-public-key]]
*Copy the Public Key*

In the newly created `demo` realm, click the *Keys* tab, then select *Active* tab, and copy the public key of type *RSA* that has been generated.

[NOTE]
====
The {project_openshift_product_name} image version {project_version} generates multiple keys by default, for example *HS256*, *RS256*, or *AES*. To copy the public key information for the {project_openshift_product_name} {project_version} image, click the *Keys* tab, then select *Active* tab, and click the *Public key* button of that row in the keys table, where type of the key matches *RSA*. Then select and copy the content of the pop-up window that appears.
====

The information about the public key is necessary xref:sso-public-key-details[later to deploy] the {project_name}-enabled EAP 6.4 / 7.1 JSP application.

*Create {project_name} Roles*

The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstart exposes three endpoints by the service:

* `public` - Requires no authentication.
* `secured` - Can be invoked by users with the `user` role.
* `admin` - Can be invoked by users with the `admin` role.

Create `user` and `admin` roles in {project_name}. These roles will be assigned to an {project_name} application user to authenticate access to user applications.

. Click *Roles* in the *Configure* sidebar to list the roles for this realm.
+
[NOTE]
====
This is a new realm, so there should only be the default (`offline_access` and `uma_authorization`) roles.
====
. Click *Add Role*.
. Enter the role name (`user`) and click *Save*.

Repeat these steps for the `admin` role.

*Create the {project_name} Realm Management User*

. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User.*
. Enter a valid *Username* (this example uses the user `appuser`) and click *Save*.
. Edit the user configuration:
.. Click the *Credentials* tab in the user space and enter a password for the user (this example uses the password `apppassword`).
.. 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 will prompt you to confirm.

===== Assign the user role to the realm management user

Perform the following steps to tie the previously created `appuser` with the `user` {project_name} role:

. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, select the `user` role created earlier, and click *Add selected>*.
. Click *Client Roles*, select *realm-management* entry from the list, select each record in the *Available Roles* list.
+
[NOTE]
====
You can select multiple items at once by holding the *Ctrl* key and simultaneously clicking the first `impersonation` entry. While keeping the *Ctrl* key and the left mouse button pressed, move to the end of the list to the `view-clients` entry and ensure each record is selected.
====
. Click *Add selected>* to assign the roles to the client.

===== Prepare {project_name} Authentication for OpenShift Deployment of the EAP 6.4 / 7.1 JSP Application

.Procedure

. Create a new project for the EAP 6.4 / 7.1 JSP application.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc new-project eap-app-demo
----
. Add the `view` role to the link:{ocpdocs_default_service_accounts_link}[`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.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
----
. The EAP template requires an link:{openshift_link}#Configuring-Keystores[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.
.. Generate a secure key for the SSL keystore (this example uses `password` as password for the keystore).
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -genkeypair \
-dname "CN=secure-eap-app-eap-app-demo.openshift.example.com" \
-alias https \
-storetype JKS \
-keystore eapkeystore.jks
----
.. Generate a secure key for the JGroups keystore (this example uses `password` as password for the keystore).
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -genseckey \
-alias jgroups \
-storetype JCEKS \
-keystore eapjgroups.jceks
----
.. Generate the EAP 6.4 / 7.1 for OpenShift secrets with the SSL and JGroup keystore files.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc create secret generic eap-ssl-secret --from-file=eapkeystore.jks
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks
----
.. Add the EAP application secret to the link:{ocpdocs_default_service_accounts_link}[`default`] service account.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc secrets link default eap-ssl-secret eap-jgroup-secret
----

===== Deploy binary build of the EAP 6.4 / 7.1 JSP application

.Procedure

. Clone the source code.
+
[source,bash,subs="attributes+,macros+"]
----
$ git clone \https://github.com/keycloak/keycloak-quickstarts.git
----
link:{appserver_doc_base_url}/html-single/development_guide/index#use_the_maven_repository[Configure] the link:https://access.redhat.com/maven-repository[Red Hat JBoss Middleware Maven repository]

. Build both the link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] applications.
.. Build the `service-jee-jaxrs` application.
+
[source,bash,subs="attributes+,macros+"]
----
$ cd keycloak-quickstarts/service-jee-jaxrs/
----
+
[source,bash,subs="attributes+,macros+"]
----
$ mvn clean package -DskipTests
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Keycloak Quickstart: service-jee-jaxrs 3.1.0.Final
[INFO] ------------------------------------------------------------------------
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.153 s
[INFO] Finished at: 2017-06-26T12:06:12+02:00
[INFO] Final Memory: 25M/241M
[INFO] ------------------------------------------------------------------------
----
.. *Comment out* the `app-jee-jsp/config/keycloak.json` requirement of the `maven-enforcer-plugin` plugin and build the `app-jee-jsp` application.
+
[source,bash,subs="attributes+,macros+"]
----
service-jee-jaxrs]$ cd ../app-jee-jsp/
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ sed -i /\<executions\>/s/^/\<\!--/ pom.xml
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ sed -i '/\(<\/executions>\)/a\-->' pom.xml
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ mvn clean package -DskipTests
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Keycloak Quickstart: app-jee-jsp 3.1.0.Final
[INFO] ------------------------------------------------------------------------
...
[INFO] Building war: /tmp/github/keycloak-quickstarts/app-jee-jsp/target/app-jsp.war
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.018 s
[INFO] Finished at: 2017-06-26T12:22:25+02:00
[INFO] Final Memory: 35M/310M
[INFO] ------------------------------------------------------------------------
----
+
[IMPORTANT]
====
The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] quickstart requires you to configure the adapter, and that the adapter configuration file (`keycloak.json`) is present in the `config/` directory in the root of the quickstart to successfully build the quickstart. But since this example configures the adapter later via selected environment variables available for the EAP 6.4 / 7.1 for OpenShift image, it is not necessary to specify the form of `keycloak.json` adapter configuration file at this moment.
====

[[directory-structure-binary-builds]]
[start=4]
. Prepare the directory structure on the local file system.
+
Application archives in the *deployments/* subdirectory of the main binary build directory are copied directly to the xref:standard-deployments-directory[standard deployments directory] of the image being built on OpenShift. For the application to deploy, the directory hierarchy containing the web application data must be correctly structured.
+
Create the main directory for the binary build on the local file system and *deployments/* subdirectory within it. Copy the previously built WAR archives of both the *service-jee-jaxrs* and *app-jee-jsp* quickstarts to the *deployments/* subdirectory:
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ ls
config  pom.xml  README.md  src  target
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ mkdir -p sso-eap7-bin-demo/deployments
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ cp target/app-jsp.war sso-eap7-bin-demo/deployments/
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ cp ../service-jee-jaxrs/target/service.war sso-eap7-bin-demo/deployments/
----
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ tree sso-eap7-bin-demo/
sso-eap7-bin-demo/
|__ deployments
    |__ app-jsp.war
    |__ service.war

1 directory, 2 files

----
+
[[standard-deployments-directory]]
[NOTE]
====
The location of the standard deployments directory depends on the underlying base image, that was used to deploy the application. See the following table:

.Standard Location of the Deployments Directory
[cols="2", options="header"]
|===
| Name of the Underlying Base Image(s) | Standard Location of the Deployments Directory

| EAP for OpenShift 6.4 and 7.1 | *_$JBOSS_HOME/standalone/deployments_*

| Java S2I for OpenShift | *_/deployments_*

| JWS for OpenShift | *_$JWS_HOME/webapps_*

|===
====
. Identify the image stream for EAP 6.4 / 7.1 image.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get is -n openshift | grep eap | cut -d ' ' -f 1
jboss-eap64-openshift
jboss-eap71-openshift
----

[[eap-new-binary-build]]
[start=6]
. Create new binary build, specifying image stream and application name.
+
[NOTE]
====
Replace `--image-stream=jboss-eap71-openshift` parameter with the `--image-stream=jboss-eap64-openshift` one in the following oc command to deploy the JSP application on top of {appserver_name} 6.4 for OpenShift image.
====
+
[source,bash,subs="attributes+,macros+"]
----
$ oc new-build --binary=true \
--image-stream=jboss-eap71-openshift \
--name=eap-app
--> Found image 31895a4 (3 months old) in image stream "openshift/jboss-eap71-openshift" under tag "latest" for "jboss-eap71-openshift"

    {appserver_name} {appserver_version}
    -------------
    Platform for building and running Jakarta EE applications on {appserver_name} {appserver_version}

    Tags: builder, javaee, eap, eap7

    * A source build using binary input will be created
      * The resulting image will be pushed to image stream "eap-app:latest"
      * A binary build was created, use 'start-build --from-dir' to trigger a new build

--> Creating resources with label build=eap-app ...
    imagestream "eap-app" created
    buildconfig "eap-app" created
--> Success
----
. Start the binary build. Instruct `oc` executable to use main directory of the binary build we created xref:directory-structure-binary-builds[in previous step] as the directory containing binary input for the OpenShift build. In the working directory of *app-jee-jsp* issue the following command.
+
[source,bash,subs="attributes+,macros+"]
----
app-jee-jsp]$ oc start-build eap-app \
--from-dir=./sso-eap7-bin-demo/ \
--follow
Uploading directory "sso-eap7-bin-demo" as binary input for the build ...
build "eap-app-1" started
Receiving source from STDIN as archive ...
Copying all war artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all ear artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all rar artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all jar artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all war artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
'/home/jboss/source/deployments/app-jsp.war' -> '/opt/eap/standalone/deployments/app-jsp.war'
'/home/jboss/source/deployments/service.war' -> '/opt/eap/standalone/deployments/service.war'
Copying all ear artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
Copying all rar artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
Copying all jar artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
Pushing image 172.30.82.129:5000/eap-app-demo/eap-app:latest ...
Pushed 6/7 layers, 86% complete
Pushed 7/7 layers, 100% complete
Push successful
----
. Create a new OpenShift application based on the build.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc new-app eap-app
--> Found image 6b13d36 (2 minutes old) in image stream "eap-app-demo/eap-app" under tag "latest" for "eap-app"

    eap-app-demo/eap-app-1:aa2574d9
    -------------------------------
    Platform for building and running Jakarta EE applications on {appserver_name} {appserver_version}

    Tags: builder, javaee, eap, eap7

    * This image will be deployed in deployment config "eap-app"
    * Ports 8080/tcp, 8443/tcp, 8778/tcp will be load balanced by service "eap-app"
      * Other containers can access this service through the hostname "eap-app"

--> Creating resources ...
    deploymentconfig "eap-app" created
    service "eap-app" created
--> Success
    Run 'oc status' to view your app.
----
. Stop all running containers of the EAP 6.4 / 7.1 JSP application in the current namespace.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get dc -o name
deploymentconfig/eap-app
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale dc/eap-app --replicas=0
deploymentconfig "eap-app" scaled
----
. Further configure the EAP 6.4 / 7.1 JSP application prior the deployment.
[[sso-public-key-details]]
.. Configure the application with proper details about the {project_name} server instance.
+
[WARNING]
====
Ensure to replace the value of *_SSO_PUBLIC_KEY_* variable below with the actual content of the RSA public key for the `demo` realm, that has been xref:copy-rsa-public-key[copied].
====
+
[source,bash,subs="attributes+,macros+"]
----
$ oc set env dc/eap-app \
-e HOSTNAME_HTTP="eap-app-eap-app-demo.openshift.example.com" \
-e HOSTNAME_HTTPS="secure-eap-app-eap-app-demo.openshift.example.com" \
-e SSO_DISABLE_SSL_CERTIFICATE_VALIDATION="true" \
-e SSO_USERNAME="appuser" \
-e SSO_PASSWORD="apppassword" \
-e SSO_REALM="demo" \
-e SSO_URL="https://secure-sso-sso-app-demo.openshift.example.com/auth" \
-e SSO_PUBLIC_KEY="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkdhXyKx97oIoO6HwnV/MiX2EHO55Sn+ydsPzbjJevI5F31UvUco9uA8dGl6oM8HrnaWWv+i8PvmlaRMhhl6Xs68vJTEc6d0soP+6A+aExw0coNRp2PDwvzsXVWPvPQg3+iytStxu3Icndx+gC0ZYnxoRqL7rY7zKcQBScGEr78Nw6vZDwfe6d/PQ6W4xVErNytX9KyLFVAE1VvhXALyqEM/EqYGLmpjw5bMGVKRXnhmVo9E88CkFDH8E+aPiApb/gFul1GJOv+G8ySLoR1c8Y3L29F7C81odkVBp2yMm3RVFIGSPTjHqjO/nOtqYIfY4Wyw9mRIoY5SyW7044dZXRwIDAQAB" \
-e SSO_SECRET="0bb8c399-2501-4fcd-a183-68ac5132868d"
deploymentconfig "eap-app" updated
----
.. Configure the application with details about both the SSL and JGroups keystore.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc set env dc/eap-app \
-e HTTPS_KEYSTORE_DIR="/etc/eap-secret-volume" \
-e HTTPS_KEYSTORE="eapkeystore.jks" \
-e HTTPS_PASSWORD="password" \
-e JGROUPS_ENCRYPT_SECRET="eap-jgroup-secret" \
-e JGROUPS_ENCRYPT_KEYSTORE_DIR="/etc/jgroups-encrypt-secret-volume" \
-e JGROUPS_ENCRYPT_KEYSTORE="eapjgroups.jceks" \
-e JGROUPS_ENCRYPT_PASSWORD="password"
deploymentconfig "eap-app" updated
----
.. Define OpenShift volumes for both the SSL and JGroups secrets created earlier.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc volume dc/eap-app --add \
--name="eap-keystore-volume" \
--type=secret \
--secret-name="eap-ssl-secret" \
--mount-path="/etc/eap-secret-volume"
deploymentconfig "eap-app" updated
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc volume dc/eap-app --add \
--name="eap-jgroups-keystore-volume" \
--type=secret \
--secret-name="eap-jgroup-secret" \
--mount-path="/etc/jgroups-encrypt-secret-volume"
deploymentconfig "eap-app" updated
----
.. Configure the deployment config of the application to run application pods under the `default` OpenShift service account (default setting).
+
[source,bash,subs="attributes+,macros+"]
----
$ oc patch dc/eap-app --type=json \
-p '[{"op": "add", "path": "/spec/template/spec/serviceAccountName", "value": "default"}]'
"eap-app" patched
----
. Deploy container of the EAP 6.4 / 7.1 JSP application using the modified deployment config.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc scale dc/eap-app --replicas=1
deploymentconfig "eap-app" scaled
----
. Expose the service as route.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get svc -o name
service/eap-app
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get route
No resources found.
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc expose svc/eap-app
route "eap-app" exposed
----
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get route
NAME      HOST/PORT                                    PATH      SERVICES   PORT       TERMINATION   WILDCARD
eap-app   eap-app-eap-app-demo.openshift.example.com             eap-app    8080-tcp                 None
----

===== Access the application

Access the application in your browser using the URL *\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*. You should see output like on the following image:

[.text-center]
image:images/sso_app_jee_jsp.png[{project_name} Example JSP Application]

.Procedure
Perform the following to test the application:

. Click the *INVOKE PUBLIC* button to access the `public` endpoint that doesn't require authentication.
+
You should see the *Message: public* output.
. Click the *LOGIN* button to be redirected for user authentication to the {project_name} server instance against the `demo` realm.
+
Specify the username and password of the {project_name} user configured earlier (`appuser` / `apppassword`). Click *Log in*. The look of the application changes as detailed in the following image:
+
[.text-center]
image:images/sso_app_jee_jsp_logged_in.png[]

. Click the *INVOKE SECURED* button to access the `secured` endpoint.
+
You should see the *Message: secured* output.
. Click the *INVOKE ADMIN* button to access the `admin` endpoint.
+
You should see *403 Forbidden* output.
+
[NOTE]
====
The `admin` endpoint requires users with `admin` {project_name} role to invoke properly. Access for the `appuser` is forbidden because they only have `user` role privilege, which allows them to access the `secured` endpoint.
====

.Procedure

Perform the following steps to add the `appuser` to the `admin` {project_name} role:

. Access the Admin Console of the {project_name} server's instance.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*.
+
Use the xref:sso-administrator-setup[credentials of the {project_name} administrator user].
. Click *Users* in the *Manage* sidebar to view the user information for the `demo` realm.
. Click *View all users* button.
. Click the ID link for the *appuser* or alternatively click the *Edit* button in the *Actions* column.
. Click the *Role Mappings* tab.
. Select `admin` entry from the *Available Roles* list in the *Realm Roles* row.
. Click *Add selected>* button to add the `admin` role to the user.
. Return to EAP 6.4 / 7.1 JSP service application.
+
*\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*.
. Click the *LOGOUT* button to reload role mappings for the `appuser`.
. Click the *LOGIN* button again and provider `appuser` credentials.
. Click the *INVOKE ADMIN* button again.
+
You should see the *Message: admin* output already.

[[Example-EAP-Auto]]
=== Automatically registering an EAP application in {project_name} with an OpenID-Connect client
This example prepares {project_name} realm, role, and user credentials for an EAP project using an OpenID-Connect client adapter. These credentials are then provided in the EAP for OpenShift template for automatic {project_name} client registration. Once deployed, the {project_name} user can be used to authenticate and access {appserver_name}.

[NOTE]
====
This example uses a OpenID-Connect client but an SAML client could also be used. See xref:../advanced_concepts/advanced_concepts.adoc#SSO-Clients[{project_name} Clients] and xref:../advanced_concepts/advanced_concepts.adoc#Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients.
====

.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.


==== Preparing {project_name} authentication for OpenShift deployment

Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.

. Create a new project:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc new-project eap-app-demo
----
//. Create a service account to be used for the {project_name} deployment:
//+
//[source,bash,subs="attributes+,macros+"]
//----
//$ oc create serviceaccount eap-service-account
//----
. Add the `view` role to the link:{ocpdocs_default_service_accounts_link}[`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.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
----
. The EAP template requires an xref:Configuring-Keystores[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 a secure key for the SSL keystore:
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks
----
.. Generate a secure key for the JGroups keystore:
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks
----
. Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc create secret generic eap-ssl-secret --from-file=eapkeystore.jks
$ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks
----
. Add the EAP secret to the `default` service account:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc secrets link default eap-ssl-secret eap-jgroup-secret
----

==== Preparing the {project_name} credentials
Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:sso-administrator-setup[administrator account] created during the {project_name} deployment.

.Procedure

*Create a Realm*

. Hover your cursor over the realm namespace at the top of the sidebar and click *Add Realm*.
. Enter a realm name (this example uses _eap-demo_) and click *Create*.

*Copy the Public Key*

In the newly created _eap-demo_ realm, click the *Keys* tab and copy the generated public key. This example uses the variable _<realm-public-key>_ for brevity. This is used later to deploy the {project_name}-enabled {appserver_name} image.

*Create a Role*

Create a role in {project_name} with a name that corresponds to the JEE role defined in the *web.xml* of the example EAP application. This role is assigned to an {project_name} _application user_ to authenticate access to user applications.

. 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.
. Click *Add Role*.
. Enter the role name (this example uses the role _eap-user-role_) and click *Save*.

*Create Users and Assign Roles*

Create two users:
- Assign the _realm management user_ the *realm-management* roles to handle automatic {project_name} client registration in the {project_name} server.
- Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications.

Create the _realm management user_:

. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*.
. Enter a valid *Username* (this example uses the user _eap-mgmt-user_) and click *Save*.
. 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.
. 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 {project_name} server rights that can be used by the {appserver_name} image to create clients.

Create the _application user_:

. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*.
. Enter a valid *Username* and any additional optional information for the _application user_ and click *Save*.
. 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.
. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, add the role created earlier.

==== Deploy the {project_name}-enabled {appserver_name} image

,Procedure

. Return to the OpenShift web console and click *Add to project* to list the default image streams and templates.
. 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.
. Select the *_eap71-sso-s2i_* image to list all of the deployment parameters. Include the following {project_name} parameters to configure the {project_name} credentials during the EAP build:
+
[cols="2*", options="header"]
|===
|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_
|===
. Click *Create* to deploy the {appserver_name} image.

It may take several minutes for the {appserver_name} image to deploy.

==== Log in to the {appserver_name} Server using {project_name}

.Procedure

. Access the {appserver_name} application server and click *Login*. You are redirected to the {project_name} login.
. Log in using the {project_name} user created in the example. You are authenticated against the {project_name} server and returned to the {appserver_name} application server.


[[Example-EAP-Manual]]
=== Manually registering EAP application in {project_name} with SAML client

This example prepares {project_name} realm, role, and user credentials for an EAP project and configures an EAP for OpenShift deployment. Once deployed, the {project_name} user can be used to authenticate and access {appserver_name}.

[NOTE]
====
This example uses a SAML client but an OpenID-Connect client could also be used. See xref:../advanced_concepts/advanced_concepts.adoc#SSO-Clients[{project_name} Clients] and xref:../advanced_concepts/advanced_concepts.adoc#Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients.
====

.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.


==== Preparing the {project_name} credentials

.Procedure

Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:sso-administrator-setup[administrator account] created during the {project_name} deployment.

*Create a Realm*

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

*Copy the Public Key*

In the newly created _saml-demo_ realm, click the *Keys* tab and copy the generated public key. This example uses the variable _realm-public-key_ for brevity. This is needed later to deploy the {project_name}-enabled {appserver_name} image.

*Create a Role*

Create a role in {project_name} with a name that corresponds to the JEE role defined in the *web.xml* of the example EAP application. This role will be assigned to an {project_name} _application user_ to authenticate access to user applications.

. 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.
. Click *Add Role*.
. Enter the role name (this example uses the role _saml-user-role_) and click *Save*.

*Create Users and Assign Roles*

Create two users:
- Assign the _realm management user_ the *realm-management* roles to handle automatic {project_name} client registration in the {project_name} server.
- Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications.

Create the _realm management user_:

. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*.
. Enter a valid *Username* (this example uses the user _app-mgmt-user_) and click *Save*.
. 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.
////
Need for the SAML?
. 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 {project_name} server rights that can be used by the {appserver_name} image to create clients.
////

Create the _application user_:

. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*.
. Enter a valid *Username* and any additional optional information for the _application user_ and click *Save*.
. 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.
. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, add the role created earlier.

*Create and Configure a SAML Client*:

Clients are {project_name} entities that request user authentication. This example configures a SAML client to handle authentication for the EAP application. This section saves two files, *keystore.jks* and *keycloak-saml-subsystem.xml* that are needed later in the procedure.

Create the SAML Client:

. Click *Clients* in the *Configure* sidebar to list the clients in the realm. Click *Create*.
. Enter a valid *Client ID*. This example uses _sso-saml-demo_.
. In the *Client Protocol* drop-down menu, select *saml*.
. Enter the *Root URL* for the application. This example uses _$$https://demoapp-eap-app-demo.openshift32.example.com$$_.
. Click *Save*.

Configure the SAML Client:

In the *Settings* tab, set the *Root URL* and the *Valid Redirect URLs* for the new *_sso-saml-demo_* client:

. For the *Root URL*, enter the same address used when creating the client. This example uses _$$https://demoapp-eap-app-demo.openshift32.example.com$$_.
. 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/*$$_.

Export the SAML Keys:

. Click the *SAML Keys* tab in the _sso-saml-demo_ client space and click *Export*.
. 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_.
. Enter the *Key Password* and the *Store Password*. This example uses _password_ for both.
. Click *Download* and save the *keystore-saml.jks* file for use later.
. Click the *_sso-saml-demo_* client to return to the client space ready for the next step.

Download the Client Adapter:

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

The *keystore-saml.jks* will be used with the other EAP keystores in the next section to create an OpenShift secret for the EAP application project. Copy the *keystore-saml.jks* file to an OpenShift node. +
The *keycloak-saml-subsystem.xml* will be modified and used in the application deployment. Copy it into the */configuration* folder of the application as *secure-saml-deployments*.

==== Preparing {project_name} authentication for OpenShift deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.

.Procedure

. Create a new project:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc new-project eap-app-demo
----
//. Create a service account to be used for the SSO deployment:
//+
//[source,bash,subs="attributes+,macros+"]
//----
//$ oc create serviceaccount app-service-account
//----
. Add the `view` role to the link:{ocpdocs_default_service_accounts_link}[`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.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
----
+
. The EAP template requires an xref:Configuring-Keystores[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 a secure key for the SSL keystore:
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks
----
.. Generate a secure key for the JGroups keystore:
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks
----
. Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc create secret generic eap-ssl-secret --from-file=eapkeystore.jks
$ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks
----
. Add the EAP application secret to the EAP service account created earlier:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc secrets link default eap-ssl-secret eap-jgroup-secret
----

[[modified-saml-xml]]
==== Modifying the *secure-saml-deployments* file

.Prerequisites

* The *keycloak-saml-subsystem.xml*, exported from the {project_name} client in a previous section, should have been copied into the */configuration* folder of the application and renamed *secure-saml-deployments*. EAP searches for this file when it starts and copies it to the *standalone-openshift.xml* file inside the {project_name} SAML adapter configuration.

.Procedure

. Open the */configuration/secure-saml-deployments* file in a text editor.
. Replace the *YOUR-WAR.war* value of the *secure-deployment name* tag with the application *.war* file. This example uses _sso-saml-demo.war_.
. 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*.
. Delete the *<PrivateKeyPem>* and *<CertificatePem>* tags and keys and replace it with keystore information:
+
[source,bash,subs="attributes+,macros+"]
----
...
<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 {project_name} client.
. Delete the second *<CertificatePem>* tag and key and replace it with the the realm certificate information:
+
[source,bash,subs="attributes+,macros+"]
----
...
<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 {project_name} client.
. Save and close the */configuration/secure-saml-deployments* file.

==== Configuring SAML Client Registration in the application *web.xml*

The client type must also be specified by the *<auth-method>* key in the application *web.xml*. This file is read by the image at deployment.

Open the application *web.xml* file and ensure it includes the following:
[source,bash,subs="attributes+,macros+"]
----
...
<login-config>
  <auth-method>KEYCLOAK-SAML</auth-method>
</login-config>
...
----

==== Deploying the application

You do not need to include any {project_name} configuration for the image because that has been configured in the application itself. Navigating to the application login page redirects you to the {project_name} login. Log in to the application through {project_name} using the _application user_ user created earlier.


