1701 lines
80 KiB
Text
1701 lines
80 KiB
Text
== Tutorials
|
|
|
|
[[upgrading-sso-db-from-previous-version]]
|
|
=== Example Workflow: Updating Existing Database to Migrate to New {project_openshift_product_name} Image Version
|
|
[IMPORTANT]
|
|
====
|
|
* Rolling updates from previous versions of {project_openshift_product_name} to version {project_version} are not supported as databases and caches are not backward compatible.
|
|
* Stop all instances running some of previous versions of the {project_openshift_product_name} before upgrading. They cannot run concurrently against the same database.
|
|
* Pre-generated scripts are not available, they are generated dynamically depending on the database.
|
|
====
|
|
|
|
{project_name} {project_version} can xref:automatic-db-migration[automatically migrate the database schema], or you can choose to do it 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 link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[running] some previous version of the {project_openshift_product_name} image, backed by MySQL or PostgreSQL database (deployed in ephemeral or persistent mode), running on a separate pod.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Stop all pods running the previous version of the {project_openshift_product_name} image before upgrading to {project_name} {project_version}, as they cannot run concurrently against the same database.
|
|
====
|
|
|
|
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.
|
|
+
|
|
[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": "redhat-{project_templates_version}-openshift:{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
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Pre-generated scripts are not available. They are generated dynamically depending on the database. With {project_name} {project_version} one can generate and export these to an SQL file that can be manually applied to the database afterwards. To dynamically generate the SQL migration file for the database:
|
|
|
|
. Configure {project_name} {project_version} with the correct datasource,
|
|
. Set 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 (e.g. `migrationExport="${jboss.home.dir}/keycloak-database-update.sql"`).
|
|
|
|
See link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_installation_and_configuration_guide/database-1#database_configuration[database configuration of {project_name} {project_version}] for further details.
|
|
|
|
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.
|
|
====
|
|
|
|
This process assumes that you are link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[running] some previous version of the {project_openshift_product_name} image, backed by MySQL or PostgreSQL database (deployed in ephemeral or persistent mode), running on a separate pod.
|
|
|
|
Perform the following to generate and get the SQL migration file for the database:
|
|
|
|
. Prepare template of OpenShift link:https://docs.openshift.com/container-platform/latest/dev_guide/jobs.html[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:[<<DB_SERVICE_PREFIX_MAPPING_VALUE>>]
|
|
- name: pass:[<<PREFIX>>]_JNDI
|
|
value: pass:[<<PREFIX_JNDI_VALUE>>]
|
|
- name: pass:[<<PREFIX>>]_USERNAME
|
|
value: pass:[<<PREFIX_USERNAME_VALUE>>]
|
|
- name: pass:[<<PREFIX>>]_PASSWORD
|
|
value: pass:[<<PREFIX_PASSWORD_VALUE>>]
|
|
- name: pass:[<<PREFIX>>]_DATABASE
|
|
value: pass:[<<PREFIX_DATABASE_VALUE>>]
|
|
- name: TX_DATABASE_PREFIX_MAPPING
|
|
value: pass:[<<TX_DATABASE_PREFIX_MAPPING_VALUE>>]
|
|
- name: pass:[<<SERVICE_HOST>>]
|
|
value: pass:[<<SERVICE_HOST_VALUE>>]
|
|
- name: pass:[<<SERVICE_PORT>>]
|
|
value: pass:[<<SERVICE_PORT_VALUE>>]
|
|
image: pass:[<<SSO_IMAGE_VALUE>>]
|
|
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/#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:[<<SERVICE>>]_SERVICE_HOST
|
|
# and pass:[<<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:
|
|
# * pass:[<<SERVICE_HOST>>] with ${SERVICE}_SERVICE_HOST and
|
|
# * pass:[<<SERVICE_HOST_VALUE>>] with pass:[<<${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=pass:["<<SERVICE_${KEY}>>"]
|
|
REPL_1="${SERVICE}_SERVICE_${KEY}"
|
|
sed -i "s#${PATTERN_1}#${REPL_1}#g" ${JOB_MIGRATION_YAML}
|
|
PATTERN_2=pass:["<<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}" &&
|
|
pass:[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
|
|
----
|
|
+
|
|
[[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
|
|
redhat-{project_templates_version}-openshift
|
|
----
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc new-build redhat-{project_templates_version}-openshift:{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/redhat-{project_templates_version}-openshift" under tag "{project_latest_image_tag}" for "redhat-{project_templates_version}-openshift:{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:[<<SSO_IMAGE_VALUE>>] field in the job template with the pull specification.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ sed -i "s#pass:[<<SSO_IMAGE_VALUE>>]#$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].
|
|
* Run the following commands if running some previous version of the {project_openshift_product_name} image, backed by the MySQL database deployed in ephemeral or persistent mode, running on a separate pod:
|
|
... Given the pod situation similar to the following:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc get pods
|
|
NAME READY STATUS RESTARTS AGE
|
|
sso-mysql-1-zvhk3 1/1 Running 0 1h
|
|
job-to-migrate-db-to-{project_templates_version}-m202t 1/1 Running 0 11m
|
|
{project_templates_version}-db-migration-image-1-build 0/1 Completed 0 13m
|
|
----
|
|
... Copy the generated SQL migration file to the MySQL pod.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc rsync --no-perms=true ./db-update/ sso-mysql-1-zvhk3:/tmp
|
|
sending incremental file list
|
|
keycloak-database-update.sql
|
|
|
|
sent 24,718 bytes received 34 bytes 49,504.00 bytes/sec
|
|
total size is 24,594 speedup is 0.99
|
|
----
|
|
... Start a shell session to the MySQL pod.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc rsh sso-mysql-1-zvhk3
|
|
sh-4.2$
|
|
----
|
|
... Use the `mysql` tool to apply database update manually.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
sh-4.2$ alias mysql="/opt/rh/rh-mysql57/root/bin/mysql"
|
|
sh-4.2$ mysql --version
|
|
/opt/rh/rh-mysql57/root/bin/mysql Ver 14.14 Distrib 5.7.16, for Linux (x86_64) using EditLine wrapper
|
|
sh-4.2$ mysql -D <PREFIX>_DATABASE -u <PREFIX>_USERNAME -p < /tmp/keycloak-database-update.sql
|
|
Enter password:
|
|
sh-4.2$ echo $?
|
|
0
|
|
----
|
|
+
|
|
[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 MySQL 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": "redhat-{project_templates_version}-openshift:{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
|
|
----
|
|
|
|
=== Example Workflow: Migrating The {project_name} Server's Database Across Environments
|
|
This tutorial focuses on migrating the Red Hat Single Sign-On server database from one environment to another or migrating to a different database. It assumes steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
|
|
|
|
==== Deploying the {project_name} MySQL Application Template
|
|
|
|
. 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}-mysql_* {project_name} application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value).
|
|
+
|
|
[IMPORTANT]
|
|
====
|
|
Export and import of {project_name} {project_version} database link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[is triggered at {project_name} server boot time and its paramaters are passed in via Java system properties.] This means during one {project_name} server boot only one of the possible migration actions (either *_export_*, or *_import_*) can be performed.
|
|
====
|
|
+
|
|
[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.
|
|
====
|
|
|
|
==== (Optional) Creating additional {project_name} link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported
|
|
|
|
When performing link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[{project_name} {project_version} server database export] only {project_name} realms and users currently present in the database will be exported. If the exported JSON file should include also additional {project_name} realms and users, these need to be created first:
|
|
|
|
. link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#create-realm[Create a new realm]
|
|
. link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#create-new-user[Create new users]
|
|
|
|
Upon their creation xref:sso-export-the-database[the database can be exported.]
|
|
|
|
[[sso-export-the-database]]
|
|
==== Export the {project_name} database as a JSON file on the OpenShift pod
|
|
|
|
. 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-mysql
|
|
|
|
$ 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-mysql-1-ozzl0 1/1 Running 0 4h
|
|
|
|
$ oc logs sso-4-ejr0k | grep 'Export'
|
|
09:24:59,503 INFO [org.keycloak.exportimport.singlefile.SingleFileExportProvider] (ServerService Thread Pool -- 57) Exporting model into file /tmp/demorealm-export.json
|
|
09:24:59,998 INFO [org.keycloak.services] (ServerService Thread Pool -- 57) KC-SERVICES0035: Export finished successfully
|
|
----
|
|
|
|
==== Retrieve and import the exported JSON file
|
|
|
|
. 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-mysql-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:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/export_import[Export and Import section] of the RH SSO Server Administration Guide.
|
|
====
|
|
+
|
|
Use the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#admin_console_export_import[administration console] of the {project_name} server to import the resources from previously exported JSON file into the {project_name} server's database, when the {project_name} server is running as a {project_name} {project_version} container on OpenShift:
|
|
|
|
.. Log into the `master` realm's administration 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.
|
|
+
|
|
[NOTE]
|
|
====
|
|
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.
|
|
====
|
|
+
|
|
[NOTE]
|
|
====
|
|
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.
|
|
====
|
|
+
|
|
[IMPORTANT]
|
|
====
|
|
The administration 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]]
|
|
=== Example Workflow: Configuring OpenShift to use {project_name} for Authentication
|
|
Configure OpenShift to use the {project_name} deployment as the authorization gateway for OpenShift. This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name} was deployed on OpenShift.
|
|
|
|
This example adds {project_name} as an authentication method alongside https://docs.openshift.com/container-platform/latest/install_config/configuring_authentication.html#identity-providers-configuring[the identity providers] configured during https://docs.openshift.com/container-platform/latest/install/index.html[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.
|
|
|
|
==== Configuring {project_name} Credentials
|
|
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*
|
|
|
|
See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#clients[Managing Clients] chapter of the Red Hat Single Sign-On Server Administration Guide for more information.
|
|
|
|
. 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.
|
|
|
|
==== Configuring OpenShift Master for {project_name} Authentication
|
|
Log in to the OpenShift master CLI. You must have the required permissions to edit the */etc/origin/master/master-config.yaml* file.
|
|
|
|
. Edit the */etc/origin/master/master-config.yaml* file and find the *identityProviders*. For example, in the case the OpenShift master is configured with the https://docs.openshift.com/container-platform/latest/install_config/configuring_authentication.html#HTPasswdPasswordIdentityProvider[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
|
|
|
|
Navigate to the OpenShift web console, which in this example is _https://openshift.example.com:8443/console_. The OpenShift login page now has the option to use either *htpasswd_auth* or *rh-sso*. 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]]
|
|
=== Example Workflow: Creating OpenShift Application from Existing Maven Binaries and Securing it Using {project_name}
|
|
|
|
To deploy existing applications on OpenShift, you can use the link:https://docs.openshift.com/container-platform/latest/dev_guide/builds/build_inputs.html#binary-source[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}.
|
|
|
|
*Prerequisite:*
|
|
|
|
[IMPORTANT]
|
|
====
|
|
This guide assumes the {project_openshift_product_name} image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:]
|
|
|
|
* *_{project_templates_version}-mysql_*
|
|
* *_{project_templates_version}-mysql-persistent_*
|
|
* *_{project_templates_version}-postgresql_*
|
|
* *_{project_templates_version}-postgresql-persistent_*
|
|
* *_{project_templates_version}-x509-mysql-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 administration 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*
|
|
|
|
[NOTE]
|
|
====
|
|
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 `user` {project_name} 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
|
|
|
|
. 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:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`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:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#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 secret new eap-ssl-secret eapkeystore.jks
|
|
----
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc secret new eap-jgroup-secret eapjgroups.jceks
|
|
----
|
|
.. Add the EAP application secret to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`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
|
|
|
|
. Clone the source code.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ git clone \https://github.com/keycloak/keycloak-quickstarts.git
|
|
----
|
|
. link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.1/html-single/development_guide/#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 JavaEE 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 JavaEE 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]
|
|
|
|
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.
|
|
====
|
|
+
|
|
Perform the following steps to add the `appuser` to the `admin` {project_name} role:
|
|
+
|
|
. Access the administration 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]]
|
|
=== Example Workflow: Automatically Registering EAP Application in {project_name} with OpenID-Connect Client
|
|
This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name} was deployed on OpenShift. 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.
|
|
====
|
|
|
|
==== 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:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`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 secret new eap-ssl-secret eapkeystore.jks
|
|
$ oc secret new eap-jgroup-secret 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.
|
|
|
|
*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
|
|
|
|
. 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}
|
|
|
|
. 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]]
|
|
=== Example Workflow: Manually Registering EAP Application in {project_name} with SAML Client
|
|
This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name} was deployed on OpenShift.
|
|
|
|
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.
|
|
====
|
|
|
|
==== 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.
|
|
|
|
*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.
|
|
|
|
. 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:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`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 secret new eap-ssl-secret eapkeystore.jks
|
|
$ oc secret new eap-jgroup-secret eapjgroups.jceks
|
|
----
|
|
. Add the EAP application secret to the EAP service account created earlier:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc secrets link default eap-ssl-secret eap-jgroup-secret
|
|
----
|
|
|
|
[[modified-saml-xml]]
|
|
==== Modifying the *secure-saml-deployments* File
|
|
|
|
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.
|
|
|
|
. 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.
|