== 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:[<<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 (`_JNDI`, `_USERNAME`, `_PASSWORD`, and `_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 *-=* 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: # * <> with actual $PREFIX value and # * <>#${PREFIX}#g" ${JOB_MIGRATION_YAML} sed -i "s#<>#\"${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 {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:[<<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 _USERNAME -d _DATABASE -W -f /tmp/keycloak-database-update.sql Password for user _USERNAME: INSERT 0 1 INSERT 0 1 ... ---- + [IMPORTANT] ==== Replace `_USERNAME` and `_DATABASE` with the actual database credentials retrieved xref:get-db-credentials[in previous section]. Also use value of `_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-$$__.__/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-./auth/admin* for the {project_name} web server, or to *\https://secure-sso-./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 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+"] ---- ---- + 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 . 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 /\/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-$$__.__/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 __ 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_* |__ |*_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-$$__.__/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 ** and ** tags and keys and replace it with keystore information: + [source,bash,subs="attributes+,macros+"] ---- ... ---- + 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 ** tag and key and replace it with the the realm certificate information: + [source,bash,subs="attributes+,macros+"] ---- ... ... ---- + 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 ** 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+"] ---- ... KEYCLOAK-SAML ... ---- ==== 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.