From 23d48bb12c237d2cd6b91718e675d795b2b996ec Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Mon, 19 Mar 2018 20:04:57 +0100 Subject: [PATCH] KEYCLOAK-6566 Initial commit of xPaaS documentation (#343) --- openshift/build.cfg | 2 + openshift/common/attributes.adoc | 5 + openshift/common/common_admin.adoc | 16 + openshift/common/common_basic_info.adoc | 0 openshift/common/common_clustering.adoc | 25 + openshift/common/common_datasources.adoc | 10 + openshift/common/common_eap_sso.adoc | 99 ++ openshift/common/common_https.adoc | 18 + openshift/common/common_s2i.adoc | 86 ++ openshift/common/common_s2i_env_vars.adoc | 39 + openshift/common/common_security_domains.adoc | 34 + openshift/common/jndi_mappings.adoc | 99 ++ openshift/common/maven_mirror_url.adoc | 54 + .../before_you_begin/before_you_begin.adoc | 24 + .../content/get_started/get_started.adoc | 929 ++++++++++++ .../content/introduction/introduction.adoc | 32 + openshift/content/reference/reference.adoc | 631 +++++++++ openshift/content/tutorials/tutorials.adoc | 1245 +++++++++++++++++ openshift/docinfo.xml | 13 + openshift/images/import_realm_error.svg | 95 ++ openshift/images/sso_app_jee_jsp.svg | 297 ++++ .../images/sso_app_jee_jsp_logged_in.svg | 332 +++++ openshift/master.adoc | 20 + 23 files changed, 4105 insertions(+) create mode 100644 openshift/build.cfg create mode 100644 openshift/common/attributes.adoc create mode 100644 openshift/common/common_admin.adoc create mode 100644 openshift/common/common_basic_info.adoc create mode 100644 openshift/common/common_clustering.adoc create mode 100644 openshift/common/common_datasources.adoc create mode 100644 openshift/common/common_eap_sso.adoc create mode 100644 openshift/common/common_https.adoc create mode 100644 openshift/common/common_s2i.adoc create mode 100644 openshift/common/common_s2i_env_vars.adoc create mode 100644 openshift/common/common_security_domains.adoc create mode 100644 openshift/common/jndi_mappings.adoc create mode 100644 openshift/common/maven_mirror_url.adoc create mode 100644 openshift/content/before_you_begin/before_you_begin.adoc create mode 100644 openshift/content/get_started/get_started.adoc create mode 100644 openshift/content/introduction/introduction.adoc create mode 100644 openshift/content/reference/reference.adoc create mode 100644 openshift/content/tutorials/tutorials.adoc create mode 100644 openshift/docinfo.xml create mode 100644 openshift/images/import_realm_error.svg create mode 100644 openshift/images/sso_app_jee_jsp.svg create mode 100644 openshift/images/sso_app_jee_jsp_logged_in.svg create mode 100644 openshift/master.adoc diff --git a/openshift/build.cfg b/openshift/build.cfg new file mode 100644 index 0000000000..602c1f7694 --- /dev/null +++ b/openshift/build.cfg @@ -0,0 +1,2 @@ +pdf_mono_font: "DejaVu Sans Mono" +pdf_body_font: "DejaVu Sans" diff --git a/openshift/common/attributes.adoc b/openshift/common/attributes.adoc new file mode 100644 index 0000000000..ee36459e62 --- /dev/null +++ b/openshift/common/attributes.adoc @@ -0,0 +1,5 @@ +:productname: Red Hat JBoss Middleware for OpenShift +:productversion: 3 +:productdocsemail: xpaas-docs@redhat.com +:imagesdir: images + diff --git a/openshift/common/common_admin.adoc b/openshift/common/common_admin.adoc new file mode 100644 index 0000000000..71667a0d69 --- /dev/null +++ b/openshift/common/common_admin.adoc @@ -0,0 +1,16 @@ +==== Environment Variables + +|=== +|Variable name |Description |Example value + +|`*ADMIN_USERNAME*` +|If both this and `*ADMIN_PASSWORD`* are defined, +used for the EAP management port user name. +|`eapadmin` + +|`*ADMIN_PASSWORD*` +|If defined, an admin user is defined for accessing +the management port, with this value as password. +|`passw0rd` +|=== + diff --git a/openshift/common/common_basic_info.adoc b/openshift/common/common_basic_info.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/openshift/common/common_clustering.adoc b/openshift/common/common_clustering.adoc new file mode 100644 index 0000000000..ca9ef51fa2 --- /dev/null +++ b/openshift/common/common_clustering.adoc @@ -0,0 +1,25 @@ +Clustering is achieved through one of two discovery mechanisms: +Kubernetes or DNS. This is done by configuring the JGroups protocol stack in +standalone-openshift.xml with either the `` or `` +elements. Out of the box, `KUBE_PING` is the pre-configured and supported protocol. + +For `KUBE_PING` to work, however, the following steps must be taken: + +. The `OPENSHIFT_KUBE_PING_NAMESPACE` environment variable must be set (see table above). +If not set, the server will act as if it is a single-node cluster (a "cluster of one"). +. The `OPENSHIFT_KUBE_PING_LABELS` environment variables should be set (see table above). +If not set, pods outside of your application (albeit in your namespace) will try to join. +. Authorization must be granted to the service account the pod is running under to be +allowed to access Kubernetes' REST api. This is done on the command line. + +.Policy commands +==== +Using the default service account in the myproject namespace: +.... +oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q) +.... +Using the eap-service-account in the myproject namespace: +.... +oc policy add-role-to-user view system:serviceaccount:$(oc project -q):eap-service-account -n $(oc project -q) +.... +==== \ No newline at end of file diff --git a/openshift/common/common_datasources.adoc b/openshift/common/common_datasources.adoc new file mode 100644 index 0000000000..b302198ddf --- /dev/null +++ b/openshift/common/common_datasources.adoc @@ -0,0 +1,10 @@ +Datasources are automatically created based on the value of some environment variables. + +The most important is the `*DB_SERVICE_PREFIX_MAPPING*` environment variable +that defines JNDI mappings for data sources. This variable must be set to a +comma-separated list of `*_=*` triplets, where +`name` is used as the pool-name in the data source, `database_type` determines +what database driver to use, and `PREFIX` is the prefix used in the names of +environment variables, which are used to configure the data source. + +include::jndi_mappings.adoc[] \ No newline at end of file diff --git a/openshift/common/common_eap_sso.adoc b/openshift/common/common_eap_sso.adoc new file mode 100644 index 0000000000..2e98ab47d8 --- /dev/null +++ b/openshift/common/common_eap_sso.adoc @@ -0,0 +1,99 @@ +This image contains support for Red Hat SSO/Keycloak-enabled applications. + +==== Environment variables + +|=== +|Variable name |Description |Example value + +|`SSO_URI` +| URI of the SSO/Keycloak server +| - + +|`SSO_REALM` +| SSO/Keycloak realm for the deployed application(s) +| - + +|`SSO_PUBLIC_KEY` +| Public key of the SSO/Keycloak Realm. This field is optional but if omitted can leave the applications vulnerable to man-in-middle attacks +| - + +|`SSO_USERNAME` +| SSO/Keycloak User required to access the SSO/Keycloak REST API +| `mySsoUser` + +|`SSO_PASSWORD` +| Password for `SSO_USERNAME` +| `6fedmL3P` + +|`SSO_SAML_KEYSTORE_SECRET` +| Secret to use for access to SAML keystore +| Default: `sso-app-secret` + +|`SSO_SAML_KEYSTORE` +| Keystore location for SAML +| Default: `/etc/sso-saml-secret-volume/keystore.jks` + +|`SSO_SAML_KEYSTORE_PASSWORD` +| Keystore password for SAML +| Default: `mykeystorepass` + +|`SSO_SAML_CERTIFICATE_NAME` +| Alias for keys/certificate to use for SAML +| Default: `jboss` + +|`SSO_BEARER_ONLY` +| Optional. SSO Client Access Type +| true + +|`SSO_CLIENT` +| Path for SSO redirects back to the application +| Defaults to match module-name + +|`SSO_ENABLE_CORS` +| Optionally enable CORS for SSO applications +| true + +|`SSO_SECRET` +| The SSO Client Secret for Confidential Access +| KZ1QyIq4 + +|`SSO_SECURE_SSL_CONNECTIONS` +| If true SSL communication between EAP and the SSO Server will be secure (i.e. certificate validation is enabled with curl) +| false +|=== + +==== Example + +.Creating Secrets and SSO/Keycloak-enabled EAP in "myproject" project/namespace +==== +Once the SSO/Keycloak server has been instantiated and configured with the +appropriate Realm, Role(s), and User(s): + +. Create Realm (e.g demo) +. Create Role that corresponds to JEE Role (e.g. user) +. Create User with permanent password credential (e.g. mgmtuser/mgmtpass). Add + all "realm-management" Roles. This User is used to automatically configure + the SSO Clients in the SSO Server. +. Create User with permanent password credential (e.g. demouser/demopass). Add + Roles to User: JEE Role from #2. This User is used to authenticate access to + user applications. + +Copy the Realm Public Key from the SSO/Keycloak console and use as the value of +`SSO_PUBLIC_KEY` below. Set `SSO_URI` according to the location of the SSO +server. + +.... +$ oc create -n myproject -f secrets/eap-app-secret.json +$ oc create -n myproject -f secrets/sso-app-secret.json +$ oc process -f eap/eap64-sso-s2i.json -v APPLICATION_NAME=helloworld,SOURCE_REPOSITORY_URL=https://github.com/keycloak/keycloak-examples,SOURCE_REPOSITORY_REF=0.4-openshift,CONTEXT_DIR=,SSO_URI=https://secure-sso-demo.hostname/auth,SSO_REALM=demo,SSO_USERNAME=mgmtuser,SSO_PASSWORD=mgmtpass,SSO_PUBLIC_KEY=XXX | oc create -n myproject -f - +.... +After executing the above, you should be able to access the +SSO/Keycloak-enabled applications at +http://helloworld-myproject.hostname/app-context and +https://secure-helloworld-myproject.hostname/app-context where app-context is +`app-jee`, `app-profile-jee`, `app-profile-jee-saml`, or service depending on the +example application. + +Note the `app-html5` and `app-profile-html5` example applications are not deployed +or functional. +==== \ No newline at end of file diff --git a/openshift/common/common_https.adoc b/openshift/common/common_https.adoc new file mode 100644 index 0000000000..a7b1c26696 --- /dev/null +++ b/openshift/common/common_https.adoc @@ -0,0 +1,18 @@ +==== Environment variables + +|=== +|Variable name |Description |Example value + +|`HTTPS_NAME` +|If defined along with `HTTPS_PASSWORD` and `HTTPS_KEYSTORE`, enable HTTPS and set the SSL name. +|`example.com` + +|`HTTPS_PASSWORD` +|If defined along with `HTTPS_NAME` and `HTTPS_KEYSTORE`, enable HTTPS and set the SSL key password. +|`passw0rd` + +|`HTTPS_KEYSTORE` +|If defined along with `HTTPS_PASSWORD` and `HTTPS_NAME`, enable HTTPS and set the SSL certificate key file to a +relative path under `$JBOSS_HOME/standalone/configuration` +|`ssl.key` +|=== \ No newline at end of file diff --git a/openshift/common/common_s2i.adoc b/openshift/common/common_s2i.adoc new file mode 100644 index 0000000000..c8f0b6f804 --- /dev/null +++ b/openshift/common/common_s2i.adoc @@ -0,0 +1,86 @@ +The image includes S2I scripts and maven. + +Maven is currently only supported as a build tool for applications +that are supposed to be deployed on JBoss EAP-based containers (or +related/descendant images) on OpenShift. + +Only WAR deployments are supported at this time. + +==== Custom configuration + +It is possible to add custom configuration files for the image. All +files put into configuration/ directory will be copied into +`$JBOSS_HOME/standalone/configuration/`. For example to override the +default configuration used in the image, just add a custom +standalone-openshift.xml into the configuration/ directory. +https://github.com/goldmann/openshift-eap-examples/tree/master/custom-configuration[See +example] for such deployment. + +===== Custom modules + +It is possible to add custom modules. All files from the +modules/Â directory will be copied into `$JBOSS_HOME/modules/`. +https://github.com/goldmann/openshift-eap-examples/tree/master/custom-module[See +example] for such deployment. + +==== Deployment Artifacts + +By default, artifacts from the source `target` directory will be deployed. To deploy from +different directories set the ARTIFACT_DIR environment variable in the BuildConfig +definition. ARTIFACT_DIR is a comma-delimited list. For example: +ARTIFACT_DIR=app1/target,app2/target,app3/target + +==== Artifact Repository Mirrors + +// Define required 'bcname' attribute for maven_mirror_url.adoc page +:bcname: eap + +// Include the Artifact Repository Mirros section +// (MAVEN_MIRROR_URL variable usage information) +include::maven_mirror_url.adoc[bcname] + +==== Scripts + +`run`:: runs the container without any changes to the default +configuration, this means that the standalone-ha.xml configuration will +be used. +`assemble`:: uses Maven to build the source, create a package (war) and +move it to the `$JBOSS_HOME/standalone/deployments` directory. + +==== Environment variables + +You can influence the way the build is executed by supplying environment +variables to the `s2i build` command. See the +link:https://github.com/openshift/source-to-image/blob/master/docs/cli.md[s2i +docs] for more information. The environment variables that can be supplied are: + +|=== +|Variable name |Description |Example value + +include::common_s2i_env_vars.adoc[] + +|*_APP_DATADIR_* +| If defined, directory in the source from where data files are copied. +|*_mydata_* + +|*_DATA_DIR_* +| Directory in the image where data from `$APP_DATADIR` will be copied. +|*_$JBOSS_HOME/data_* + +|=== + +==== Example + +This example for the JBoss EAP 6.4 image builds the Heroku Java example + +---- +s2i build -e "MAVEN_ARGS=clean package" --loglevel=5 --forcePull=false https://github.com/heroku/java-sample.git ce-registry.usersys.redhat.com/jboss-eap-6/eap-openshift:6.4 test-jee-app +---- + +Later you can run the application with: + +---- +docker run -it --rm test-jee-app +---- + +This will run a container and deploy the hello world application on start-up. diff --git a/openshift/common/common_s2i_env_vars.adoc b/openshift/common/common_s2i_env_vars.adoc new file mode 100644 index 0000000000..ec0869ba81 --- /dev/null +++ b/openshift/common/common_s2i_env_vars.adoc @@ -0,0 +1,39 @@ +|`ARTIFACT_DIR` +|`.war` and `.jar` files from this directory will be copied into the `deployments` directory. +|`target` + +|`HTTP_PROXY_HOST` +| Hostname or IP address of a HTTP proxy for Maven to use. +|`192.168.1.1` + +|`HTTP_PROXY_PORT` +| TCP Port of a HTTP proxy for Maven to use. +|`8080` + +|`HTTP_PROXY_USERNAME` +| If supplied with `HTTP_PROXY_PASSWORD`, use credentials for HTTP proxy. +| myusername + +|`HTTP_PROXY_PASSWORD` +| If supplied with `HTTP_PROXY_USERNAME`, use credentials for HTTP proxy. +| mypassword + +|`HTTP_PROXY_NONPROXYHOSTS` +| If supplied, a configured HTTP proxy will ignore these hosts. +|`some.example.org\|*.example.net` + +|`MAVEN_ARGS` +| Overrides the arguments supplied to maven during build. +|`-e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga package` + +|`MAVEN_ARGS_APPEND` +| Appends user arguments supplied to maven during build. +|`-Dfoo=bar` + +|`MAVEN_MIRROR_URL` +| URL of a Maven Mirror/repository manager to configure. +|`\http://10.0.0.1:8080/repository/internal/` + +|`MAVEN_CLEAR_REPO` +| Optionally clear the local maven repository after the build. +|`true` \ No newline at end of file diff --git a/openshift/common/common_security_domains.adoc b/openshift/common/common_security_domains.adoc new file mode 100644 index 0000000000..e57b69913a --- /dev/null +++ b/openshift/common/common_security_domains.adoc @@ -0,0 +1,34 @@ +To configure a new Security Domain, the user must define the +`SECDOMAIN_NAME` environment variable. + +This will result in the creation of a security domain named +after the environment variable. The user may also define the following +environment variables to customize the domain: + +|=== +|Variable name |Description |Example value + +|`SECDOMAIN_NAME` +| Define in order to enable the definition of an additional security +domain. +| `myDomain` +|`SECDOMAIN_PASSWORD_STACKING` +| If defined, the password-stacking module option is enabled and + set to the value useFirstPass. +| `true` + +|`SECDOMAIN_LOGIN_MODULE` +| The login module to be used. + + Defaults to `UsersRoles` +| `UsersRoles` + +|`SECDOMAIN_USERS_PROPERTIES` +| The name of the properties file containing user definitions. + + Defaults to `users.properties` +| `users.properties` + +|`SECDOMAIN_ROLES_PROPERTIES` +| The name of the properties file containing role definitions. + + Defaults to `roles.properties` +| `roles.properties` +|=== \ No newline at end of file diff --git a/openshift/common/jndi_mappings.adoc b/openshift/common/jndi_mappings.adoc new file mode 100644 index 0000000000..d86be87a08 --- /dev/null +++ b/openshift/common/jndi_mappings.adoc @@ -0,0 +1,99 @@ +[[db_service_prefix_mapping]] +==== JNDI mappings for datasources + +For each `-=PREFIX` triplet in the `DB_SERVICE_PREFIX_MAPPING` +environment variable, a separate datasource will be created by the launch script, which is +executed when running the image. + +The `` will determine the driver for the datasource. Currently, only `postgresql` and +`mysql` are supported. + +The `` parameter can be chosen on you own. Do not use any special characters. + +NOTE: The first part (before the equal sign) of the `DB_SERVICE_PREFIX_MAPPING` + should be lowercase. + +===== Database drivers + +Every image contains Java drivers for MySQL, PostgreSQL and MongoDB databases deployed. +Datasources are *generated only for MySQL and PostgreSQL databases*. + +NOTE: For MongoDB database there are no JNDI mappings created because this is not + a SQL database. + +===== Datasource configuration environment variables + +Other datasource properties will be configured from the following environment +variables: + +|=== +|Variable name |Description |Example value + +|`__SERVICE_HOST` |Defines the database server's hostname or IP to be +used in the datasource's `connection-url` property. +|`192.168.1.3` + +|`__SERVICE_PORT` |Defines the database server's port for the datasource. +|`5432` + +|`_JNDI` |Defines the JNDI name for the datasource. Defaults to +`java:jboss/datasources/_`, where `name` and `database_type` are taken from +the triplet described above. This setting is useful if you want to override the default +generated JNDI name. |`java:jboss/datasources/test-postgresql` + +|`_USERNAME` |Defines the username for the datasource. +|`admin` + +|`_PASSWORD` |Defines the password for the datasource. +|`password` + +|`_DATABASE` |Defines the database name for the datasource. +|`myDatabase` + +|`_TX_ISOLATION` |Defines the java.sql.Connection transaction isolation +level for the datasource. +|`TRANSACTION_READ_UNCOMMITTED` + +|`_MIN_POOL_SIZE` |Defines the minimum pool size option for the datasource. +|`1` + +|`_MAX_POOL_SIZE` |Defines the maximum pool size option for the datasource. +|`20` + +|=== + +When running this image in OpenShift, the `__SERVICE_HOST` +and `__SERVICE_PORT` environment variables are set up +automatically from the database service definition in the OpenShift application +template, while the others are configured in the template directly (as `env` +entries in container definitions under each pod template). + +===== Examples + +These examples show how value of the `DB_SERVICE_PREFIX_MAPPING` environment +variable influences datasource creation. + +====== Single mapping + +Consider value `test-postgresql=TEST`. + +This will create a datasource with `java:jboss/datasources/test_postgresql` name. +Additionally all the required settings like password and username will be expected +to be provided as env variables with the `TEST_` prefix, for example `TEST_USERNAME` +and `TEST_PASSWORD`. + +====== Multiple mappings + +You can also specify multiple database mappings. Consider following value for the +`DB_SERVICE_PREFIX_MAPPING` environment variable: `cloud-postgresql=CLOUD,test-mysql=TEST_MYSQL`. + +NOTE: Multiple datasource mappings should be separated with comma. + +This will create two datasources: + +1. `java:jboss/datasources/test_mysql`, and +2. `java:jboss/datasources/cloud_postgresql`. + +MySQL datasource configuration (username, etc) will be expected with the +`TEST_MYSQL` prefix, for example `TEST_MYSQL_USERNAME`, whereas for the PostgreSQL +datasource it'll expect beexpected with the `CLOUD_` prefix, for example `CLOUD_USERNAME`. diff --git a/openshift/common/maven_mirror_url.adoc b/openshift/common/maven_mirror_url.adoc new file mode 100644 index 0000000000..3a5c2bc165 --- /dev/null +++ b/openshift/common/maven_mirror_url.adoc @@ -0,0 +1,54 @@ +// This page describes MAVEN_MIRROR_URL variable usage +// It requires 'bcname' attribute to be set to the name of the product + +A repository in Maven holds build artifacts and dependencies of various types +(all the project jars, library jar, plugins or any other project specific +artifacts). It also specifies locations from where to download artifacts from, +while performing the S2I build. Besides using central repositories, it is a +common practice for organizations to deploy a local custom repository (mirror). + +Benefits of using a mirror are: + +* Availability of a synchronized mirror, which is geographically closer and + faster. +* Ability to have greater control over the repository content. +* Possibility to share artifacts across different teams (developers, CI), + without the need to rely on public servers and repositories. +* Improved build times. + +Often, a repository manager can serve as local cache to a mirror. Assuming that +the repository manager is already deployed and reachable externally at +*_pass:[http://10.0.0.1:8080/repository/internal/]_*, the S2I build can then use this +manager by supplying the `MAVEN_MIRROR_URL` environment variable to the +build configuration of the application as follows: + +. Identify the name of the build configuration to apply `MAVEN_MIRROR_URL` + variable against: ++ +[subs="attributes"] +---- +oc get bc -o name +buildconfig/{bcname} +---- +. Update build configuration of `{bcname}` with a `MAVEN_MIRROR_URL` environment variable ++ +[subs="attributes"] +---- +oc env bc/{bcname} MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" +buildconfig "{bcname}" updated +---- +. Verify the setting ++ +[subs="attributes"] +---- +oc env bc/{bcname} --list +# buildconfigs {bcname} +MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/ +---- +. Schedule new build of the application + +NOTE: During application build, you will notice that Maven dependencies are +pulled from the repository manager, instead of the default public repositories. +Also, after the build is finished, you will see that the mirror is filled with +all the dependencies that were retrieved and used during the build. + diff --git a/openshift/content/before_you_begin/before_you_begin.adoc b/openshift/content/before_you_begin/before_you_begin.adoc new file mode 100644 index 0000000000..55c21cb795 --- /dev/null +++ b/openshift/content/before_you_begin/before_you_begin.adoc @@ -0,0 +1,24 @@ +=== Comparison: {xpaasproduct-shortname} Image and Red Hat Single Sign-On +The {xpaasproduct-shortname} image version number 7.2 is based on Red Hat Single Sign-On 7.2. There are some differences in functionality between the {xpaasproduct-shortname} image and Red Hat Single Sign-On: + +* The {xpaasproduct-shortname} image includes all of the functionality of Red Hat Single Sign-On. In addition, the RH-SSO-enabled JBoss EAP image automatically handles OpenID Connect or SAML client registration and configuration for *_.war_* deployments that contain *KEYCLOAK* or *KEYCLOAK-SAML* in their respective *web.xml* files. + +=== Version Compatibility and Support +See the xPaaS part of the https://access.redhat.com/articles/2176281[OpenShift and Atomic Platform Tested Integrations page] for details about OpenShift image version compatibility. + +=== Deprecated Image Streams and Application Templates for {xpaasproduct-shortname} + +[IMPORTANT] +==== +The {xpaasproduct-shortname} image version number 7.0 is deprecated and it will no longer receive updates of image and application templates. + +*To deploy new applications, it is recommended to use the version 7.1 or 7.2 of the {xpaasproduct-shortname} image along with the application templates specific to those versions.* +==== + +=== Initial Setup +The Tutorials in this guide follow on from and assume an OpenShift instance similar to that created in the https://access.redhat.com/documentation/en/red-hat-application-services/0/openshift-primer[OpenShift Primer]. + +[IMPORTANT] +==== +For information related to updating the existing database when migrating {xpaasproduct-shortname} image from RH-SSO 7.0 to RH-SSO 7.1, or from RH-SSO 7.1 to RH-SSO 7.2, see the xref:../tutorials/tutorials.adoc#upgrading-sso-db-from-70-to-71[Updating Existing Database when Migrating {xpaasproduct-shortname} Image to a new version] section. +==== diff --git a/openshift/content/get_started/get_started.adoc b/openshift/content/get_started/get_started.adoc new file mode 100644 index 0000000000..39714e1be0 --- /dev/null +++ b/openshift/content/get_started/get_started.adoc @@ -0,0 +1,929 @@ +=== Using the {xpaasproduct-shortname} Image Streams and Application Templates +Red Hat JBoss Middleware for OpenShift images are pulled on demand from the Red Hat Registry: link:http://registry.access.redhat.com[registry.access.redhat.com]. To update to the latest {xpaasproduct-shortname} images, run the following commands: + +. On your master host(s), ensure that you are logged in as a cluster administrator or a user with project administrator access to the global `openshift` project. ++ +---- +$ oc login -u system:admin +---- +. Run the following commands to update the core set of RH-SSO 7.2 resources for OpenShift in the `openshift` project: ++ +---- +$ for resource in sso72-image-stream.json \ + sso72-https.json \ + sso72-mysql-persistent.json \ + sso72-mysql.json \ + sso72-postgresql-persistent.json \ + sso72-postgresql.json +do + oc replace -n openshift --force -f \ + https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.4.9/sso/${resource} +done +---- +. Run the following command to install the RH-SSO 7.2 OpenShift image streams in the `openshift` project: ++ +---- +$ oc -n openshift import-image redhat-sso72-openshift:1.0 +---- + +=== Preparing and Deploying the {xpaasproduct-shortname} Application Templates + +[[Configuring-Keystores]] +==== Configuring Keystores + +The {xpaasproduct-shortname} image requires two keystores: + +- An SSL keystore to provide private and public keys for https traffic encryption. + +- A JGroups keystore to provide private and public keys for network traffic encryption between nodes in the cluster. + +These keystores are expected by the {xpaasproduct-shortname} image, even if the application uses only http on a single-node OpenShift instance. Self-signed certificates do not provide secure communication and are intended for internal testing purposes. + +[WARNING] +For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS). + +See the https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.1/html-single/Security_Guide/index.html#Generate_a_SSL_Encryption_Key_and_Certificate[JBoss Enterprise Application Platform Security Guide] for more information on how to create a keystore with self-signed or purchased SSL certificates. + +==== Generating Secrets + +OpenShift uses objects called `Secrets` to hold sensitive information, such as passwords or keystores. See the https://access.redhat.com/documentation/en/openshift-enterprise/version-3.2/developer-guide/#dev-guide-secrets[Secrets chapter] in the OpenShift documentation for more information. + +The {xpaasproduct-shortname} image requires one or more secrets that hold the two keystores described earlier. This provides the necessary authorization to applications in the project. + +Use the SSL and JGroups keystore files to create secrets for the project: +[subs="verbatim,macros"] +---- +$ oc secret new +$ oc secret new +---- + +//// +==== Creating the Service Account + +Service accounts are API objects that exist within each project and allow users to associate certain secrets and roles with applications in a project namespace. This provides the application with the necessary authorization to run with all required privileges. + +The service account that you create must be configured with the correct permissions to view pods in Kubernetes. This is required in order for clustering with the {xpaasproduct-shortname} image to work. You can view the top of the log files to see whether the correct service account permissions have been configured. + +. Create a service account to be used for the SSO deployment: ++ +[subs="verbatim,macros"] +---- +$ oc create serviceaccount +---- +. Add the *view* role to the service account. This enables the service account to view all the resources in the application namespace in OpenShift, which is necessary for managing the cluster. ++ +[subs="verbatim,macros"] +---- +$ oc policy add-role-to-user view system:serviceaccount:: -n +---- +. Link the secrets created for the project to the service account: ++ +[subs="verbatim,macros"] +---- +$ oc secrets link +---- +//// + +[[sso-administrator-setup]] +==== Creating Administrator Account for Red Hat Single Sign-On Server + +Red Hat Single Sign-On does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the `master` realm's management console and perform server maintenance operations such as, creating realms or users, or registering applications intended to be secured by Red Hat Single Sign-On. + +The administrator account can be created: + +* By providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the RH-SSO application template, or +* By xref:sso-admin-remote-shell[a remote shell session to particular RH-SSO pod], if the {xpaasproduct-shortname} image is deployed without an application template. + +[NOTE] +==== +Red Hat Single Sign-On allows an initial administrator account creation via the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/getting_started_guide/#creating_the_admin_account[Welcome Page] web form. But only if the `Welcome Page` is accessed from a localhost, this method of administrator account creation is not applicable for {xpaasproduct-shortname} image. +==== + +[[sso-admin-template-parameters]] +===== Creating RH-SSO Administrator Account via Template Parameters + +When deploying RH-SSO application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the RH-SSO server's administrator account to be created for the `master` realm. + +[NOTE] +==== +*Both of these parameters are required.* If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated. +==== + +[IMPORTANT] +==== +The lifespan of the RH-SSO server's administrator account depends upon the the storage type used to store the RH-SSO server's database: + +* For an in-memory database mode (*_sso71-https_* and *_sso72-https_* templates) the account exist throughout the lifecycle of the particular RH-SSO pod (stored account data is lost upon pod destruction), +* For an ephemeral database mode (*_sso71-mysql_*, *_sso71-postgresql_*, *_sso72-mysql_*, and *_sso72-postgresql_* templates) the account exist throughout the lifecycle of the database pod (even if RH-SSO pod is destructed, the stored account data is preserved under the assumption that the database pod is still running), +* For persistent database mode (*_sso71-mysql-persistent_*, *_sso71-postgresql-persistent_*, *_sso72-mysql-persistent_*, and *_sso72-postgresql-persistent_* templates) the account exists throughout the lifecycle of the persistent medium used to hold the database data. This means that the stored account data is preserved even when both, the RH-SSO and the database pods are destructed. + +It is a common practice to deploy an RH-SSO application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new RH-SSO application needs to be instantiated). +==== + +[WARNING] +==== +In the case of *ephemeral or persistent database mode*, after creating the RH_SSO server's administrator account, remove the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables from the deployment config before deploying new RH-SSO applications. +==== + +[IMPORTANT] +==== +Run the following commands to prepare the previously created deployment config of the RH-SSO application for reuse after the administrator account has been created: + +. Identify the deployment config of the RH-SSO application. ++ +---- +$ oc get dc -o name +deploymentconfig/sso +deploymentconfig/sso-mysql +---- +. Clear the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables setting. ++ +---- +$ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD="" +---- +==== + +[[sso-admin-remote-shell]] +===== Creating RH-SSO Administrator Account via Remote Shell Session to RH-SSO Pod + +Run following commands to create administrator account for the `master` realm of the RH-SSO server, when deploying the {xpaasproduct-shortname} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the RH-SSO application pod has been started: + +. Identify the RH-SSO application pod. ++ +---- +$ oc get pods +NAME READY STATUS RESTARTS AGE +sso-12-pt93n 1/1 Running 0 1m +sso-mysql-6-d97pf 1/1 Running 0 2m +---- +. Open a remote shell session to {xpaasproduct-shortname} container. ++ +---- +$ oc rsh sso-12-pt93n +sh-4.2$ +---- +. Create the RH-SSO server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script. ++ +---- +sh-4.2$ cd /opt/eap/bin/ +sh-4.2$ ./add-user-keycloak.sh -r master -u sso_admin -p sso_password +Added 'sso_admin' to '/opt/eap/standalone/configuration/keycloak-add-user.json', restart server to load user +---- ++ +[NOTE] +==== +The `sso_admin`/`sso_password` credentials in the example above are for demonstration purposes only. Refer to the password policy applicable within your organization for guidance on how to create a secure user name and password. +==== +. Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly. ++ +---- +sh-4.2$ ./jboss-cli.sh --connect ':reload' +{ + "outcome" => "success", + "result" => undefined +} +---- ++ +[WARNING] +==== +When restarting the server it is important to restart just the JBoss EAP process within the running RH-SSO container, and not the whole container. Because restarting the whole container recreates it from scratch, without the RH-SSO server administration account for the `master` realm to be created. +==== +. Log into the `master` realm's administration console of the RH-SSO server using the the credentials created in the steps above. In the browser, navigate to *\http://sso-./auth/admin* for the RH-SSO web server, or to *\https://secure-sso-./auth/admin* for the encrypted RH-SSO web server, and specify user name and password used to create the administrator user. + +==== Using the OpenShift Web Console +Log in to the OpenShift web console: + +. 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 an application template and configure the deployment parameters as required. +. Click *Create* to deploy the application template. + +These are some of the more common variables to configure an RH-SSO deployment: + +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_APPLICATION_NAME_* +|The name for the RH-SSO application. + +|*_HOSTNAME_HTTPS_* +|Custom hostname for https service route. Leave blank for default hostname of _.._ + +|*_HOSTNAME_HTTP_* +|Custom hostname for http service route. Leave blank for default hostname of _.._ + +|*_HTTPS_KEYSTORE_* +|The name of the keystore file within the secret. + +|*_HTTPS_PASSWORD_* +|The password for the keystore and certificate. + +|*_HTTPS_SECRET_* +|The name of the secret containing the keystore file. + +|*_JGROUPS_ENCRYPT_KEYSTORE_* +|The name of the JGroups keystore file within the secret. + +|*_JGROUPS_ENCRYPT_PASSWORD_* +|The password for the JGroups keystore and certificate. + +|*_JGROUPS_ENCRYPT_SECRET_* +|The name of the secret containing the JGroups keystore file. + +|*_SSO_ADMIN_USERNAME_* +|Username of the administrator account for the `master` realm of the RH-SSO server. *Required.* If no value is specified, it is auto generated and displayed as an OpenShift instructional message when the template is instantiated. + +|*_SSO_ADMIN_PASSWORD_* +|Password of the administrator account for the `master` realm of the RH-SSO server. *Required.* If no value is specified, it is auto generated and displayed as an OpenShift instructional message when the template is instantiated. + +|*_SSO_REALM_* +|The name of an additional RH-SSO realm to create during deployment. + +|*_SSO_SERVICE_USERNAME_* +|RH-SSO service user name to manage the realm. + +|*_SSO_SERVICE_PASSWORD_* +|RH-SSO service user password. +|=== + +See the xref:env_vars[Reference chapter] for a more comprehensive list of the RH-SSO environment variables. +See the xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {xpaasproduct-shortname} Image] for an end-to-end example of RH-SSO deployment. + +==== Routes + +The {xpaasproduct-shortname} templates use TLS passthrough termination for routes by default. This means that the destination route receives encrypted traffic without the OpenShift router providing TLS termination. Users do not need the relevant SSL certificate to connect to the RH-SSO login page. + +For more information on OpenShift route types, see the link:https://docs.openshift.com/container-platform/3.7/architecture/networking/routes.html#route-types[Networking chapter] of the OpenShift Architecture Guide. + +==== Deployment Process + +Once deployed, the *_sso71-https_* and *_sso72-https_* templates create a single pod that contains both the database and the RH-SSO servers. The *_sso71-mysql_*, *_sso72-mysql_*, *_sso71-mysql-persistent_*, *_sso72-mysql-persistent_*, *_sso71-postgresql_*, *_sso72-postgresql_*, *_sso71-postgresql-persistent_*, and *_sso72-postgresql-persistent_* templates create two pods, one for the database server and one for the RH-SSO web server. + +After the RH-SSO web server pod has started, it can be accessed at its custom configured hostnames, or at the default hostnames: + +* *\http://sso-__.__/auth/admin*: for the RH-SSO web server, and +* *\https://secure-sso-__.__/auth/admin*: for the encrypted RH-SSO web server. + +Use the xref:../get_started/get_started.adoc#sso-administrator-setup[administrator user credentials] to log in into the `master` realm’s administration console. + +[[SSO-Clients]] +==== RH-SSO Clients + +Clients are RH-SSO entities that request user authentication. A client can be an application requesting RH-SSO to provide user authentication, or it can be making requests for access tokens to start services on behalf of an authenticated user. See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients[Managing Clients chapter of the Red Hat Single Sign-On documentation] for more information. + +RH-SSO provides link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#oidc_clients[OpenID-Connect] and link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#saml_clients[SAML] client protocols. + +OpenID-Connect is the preferred protocol and utilizes three different access types: + +- *public*: Useful for JavaScript applications that run directly in the browser and require no server configuration. +- *confidential*: Useful for server-side clients, such as EAP web applications, that need to perform a browser login. +- *bearer-only*: Useful for back-end services that allow bearer token requests. + +It is required to specify the client type in the ** key of the application *web.xml* file. This file is read by the image at deployment. Set the value of ** element to: + +* *KEYCLOAK* for the OpenID Connect client. +* *KEYCLOAK-SAML* for the SAML client. + +The following is an example snippet for the application *web.xml* to configure an OIDC client: + +---- +... + + KEYCLOAK + +... +---- + +[[Auto-Man-Client-Reg]] +==== Automatic and Manual RH-SSO Client Registration Methods +A client application can be automatically registered to an RH-SSO realm by using credentials passed in variables specific to the *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. + +Alternatively, you can manually register the client application by configuring and exporting the RH-SSO client adapter and including it in the client application configuration. + +==== Automatic RH-SSO Client Registration + +Automatic RH-SSO client registration is determined by RH-SSO environment variables specific to the *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. The RH-SSO credentials supplied in the template are then used to register the client to the RH-SSO realm during deployment of the client application. + +The RH-SSO environment variables included in the *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are: + +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_HOSTNAME_HTTP_* +|Custom hostname for http service route. Leave blank for default hostname of .. + +|*_HOSTNAME_HTTPS_* +|Custom hostname for https service route. Leave blank for default hostname of .. + +|*_SSO_URL_* +|The RH-SSO web server authentication address: $$https://secure-sso-$$__.__/auth + +|*_SSO_REALM_* +|The RH-SSO realm created for this procedure. + +|*_SSO_USERNAME_* +|The name of the _realm management user_. + +|*_SSO_PASSWORD_* +| The password of the user. + +|*_SSO_PUBLIC_KEY_* +|The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the RH-SSO console. + +|*_SSO_BEARER_ONLY_* +|If set to *true*, the OpenID Connect client is registered as bearer-only. + +|*_SSO_ENABLE_CORS_* +|If set to *true*, the RH-SSO adapter enables Cross-Origin Resource Sharing (CORS). +|=== + +If the RH-SSO client uses the SAML protocol, the following additional variables need to be configured: + +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_SSO_SAML_KEYSTORE_SECRET_* +|Secret to use for access to SAML keystore. The default is _sso-app-secret_. + +|*_SSO_SAML_KEYSTORE_* +|Keystore filename in the SAML keystore secret. The default is _keystore.jks_. + +|*_SSO_SAML_KEYSTORE_PASSWORD_* +|Keystore password for SAML. The default is _mykeystorepass_. + +|*_SSO_SAML_CERTIFICATE_NAME_* +|Alias for keys/certificate to use for SAML. The default is _jboss_. +|=== + +See xref:Example-EAP-Auto[Example Workflow: Automatically Registering EAP Application in RH-SSO with OpenID-Connect Client] for an end-to-end example of the automatic client registration method using an OpenID-Connect client. + +==== Manual RH-SSO Client Registration + +Manual RH-SSO client registration is determined by the presence of a deployment file in the client application's _../configuration/_ directory. These files are exported from the client adapter in the RH-SSO web console. The name of this file is different for OpenID-Connect and SAML clients: + +[horizontal] +*OpenID-Connect*:: _../configuration/secure-deployments_ +*SAML*:: _../configuration/secure-saml-deployments_ + +These files are copied to the RH-SSO adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed. + +There are two methods for passing the RH-SSO adapter configuration to the client application: + +* Modify the deployment file to contain the RH-SSO adapter configuration so that it is included in the _standalone-openshift.xml_ file at deployment, or +* Manually include the OpenID-Connect _keycloak.json_ file, or the SAML _keycloak-saml.xml_ file in the client application's *../WEB-INF* directory. + +See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use RH-SSO Authentication, Using SAML Client] for an end-to-end example of the manual RH-SSO client registration method using a SAML client. + +==== Limitations +OpenShift does not currently accept OpenShift role mapping from external providers. If RH-SSO is used as an authentication gateway for OpenShift, users created in RH-SSO must have the roles added using the OpenShift Administrator `oadm policy` command. + +For example, to allow an RH-SSO-created user to view a project namespace in OpenShift: +[subs="verbatim,macros"] +---- +oadm policy add-role-to-user view -n +---- + +=== Binary Builds + +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.0 JSP Service Invocation Application that Authenticates Using Red Hat Single Sign-On + +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.0 JSP service application that authenticates using the Red Hat Single Sign-On. + +*Prerequisite:* + +[IMPORTANT] +==== +This guide assumes the {xpaasproduct-shortname} image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_jboss_sso_for_openshift/#Example-Deploying-SSO[deployed using one of the following templates:] + +* *_sso71-mysql_* +* *_sso72-mysql_* +* *_sso71-postgresql_* +* *_sso72-postgresql_* +* *_sso71-mysql-persistent_* +* *_sso72-mysql-persistent_* +* *_sso71-postgresql-persistent_* +* *_sso72-postgresql-persistent_* +==== + +===== Create RH-SSO Realm, Roles, and User for the EAP 6.4 / 7.0 JSP Application + +The EAP 6.4 / 7.0 JSP service application requires dedicated RH-SSO realm, username, and password to be able to authenticate using Red Hat Single Sign-On. Perform the following steps after the {xpaasproduct-shortname} image has been deployed: + +*Create the RH-SSO Realm* + +. Login to the administration console of the RH-SSO server. ++ +*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin* ++ +Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the RH-SSO 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 and copy the public key that has been generated. + +[NOTE] +==== +RH-SSO 7.1 and RH-SSO 7.2 images generate two keys by default: + +* RSA key, and +* HMAC key + +To copy the public key information for the RH-SSO 7.1 or RH-SSO 7.2 image, click the *Public key* button of the *RSA* row of the keys table. 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 RH-SSO-enabled EAP 6.4 / 7.0 JSP application. + +*Create RH-SSO 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 RH-SSO. These roles will be assigned to an RH-SSO 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 roles: + +* `offline_access` and `uma_authorization` role for the RH-SSO 7.1 and RH-SSO 7.2 images. +==== +. Click *Add Role*. +. Enter the role name (`user`) and click *Save*. + +Repeat these steps for the `admin` role. + +*Create the RH-SSO 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 prompts for additional confirmation. + +===== Assign `user` RH-SSO Role to the Realm Management User + +Perform the following steps to tie the previously created `appuser` with the `user` RH-SSO 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 RH-SSO Authentication for OpenShift Deployment of the EAP 6.4 / 7.0 JSP Application + +. Create a new project for the EAP 6.4 / 7.0 JSP application. ++ +[subs="verbatim,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. ++ +[subs="verbatim,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_jboss_sso_for_openshift/#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). ++ +[subs="verbatim,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). ++ +[subs="verbatim,macros"] +---- +$ keytool -genseckey \ +-alias jgroups \ +-storetype JCEKS \ +-keystore eapjgroups.jceks +---- +.. Generate the EAP 6.4 / 7.0 for OpenShift secrets with the SSL and JGroup keystore files. ++ +[subs="verbatim,macros"] +---- +$ oc secret new eap-ssl-secret eapkeystore.jks +---- ++ +[subs="verbatim,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. ++ +[subs="verbatim,macros"] +---- +$ oc secrets link default eap-ssl-secret eap-jgroup-secret +---- + +===== Deploy Binary Build of the EAP 6.4 / 7.0 JSP Application + +. Clone the source code. ++ +[subs="verbatim,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. ++ +[subs="verbatim,macros"] +---- +$ cd keycloak-quickstarts/service-jee-jaxrs/ +---- ++ +[subs="verbatim,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. ++ +[subs="verbatim,macros"] ++ +---- +service-jee-jaxrs]$ cd ../app-jee-jsp/ +---- ++ +[subs="verbatim,macros"] +---- +app-jee-jsp]$ sed -i /\/s/^/\<\!--/ pom.xml +---- ++ +[subs="verbatim,macros"] +---- +app-jee-jsp]$ sed -i '/\(<\/executions>\)/a\-->' pom.xml +---- ++ +[subs="verbatim,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 to configure the adapter, and adapter configuration file (`keycloak.json`) to be present at 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.0 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 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: ++ +[subs="verbatim,macros"] +---- +app-jee-jsp]$ ls +config pom.xml README.md src target +---- ++ +[subs="verbatim,macros"] +---- +app-jee-jsp]$ mkdir -p sso-eap7-bin-demo/deployments +---- ++ +[subs="verbatim,macros"] +---- +app-jee-jsp]$ cp target/app-jsp.war sso-eap7-bin-demo/deployments/ +---- ++ +[subs="verbatim,macros"] +---- +app-jee-jsp]$ cp ../service-jee-jaxrs/target/service.war sso-eap7-bin-demo/deployments/ +---- ++ +[subs="verbatim,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] +==== +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.0 | *_$JBOSS_HOME/standalone/deployments_* + +| Java S2I for OpenShift | *_/deployments_* + +| JWS for OpenShift | *_$JWS_HOME/webapps_* + +|=== +==== +. Identify the image stream for EAP 6.4 / 7.0 image. ++ +[subs="verbatim,macros"] +---- +$ oc get is -n openshift | grep eap | cut -d ' ' -f 1 +jboss-eap64-openshift +jboss-eap70-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-eap70-openshift` parameter with the `--image-stream=jboss-eap64-openshift` one in the following oc command to deploy the JSP application on top of JBoss EAP 6.4 for OpenShift image. +==== ++ +[subs="verbatim,macros"] +---- +$ oc new-build --binary=true \ +--image-stream=jboss-eap70-openshift \ +--name=eap-app +--> Found image 31895a4 (3 months old) in image stream "openshift/jboss-eap70-openshift" under tag "latest" for "jboss-eap70-openshift" + + JBoss EAP 7.0 + ------------- + Platform for building and running JavaEE applications on JBoss EAP 7.0 + + 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. ++ +[subs="verbatim,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. ++ +[subs="verbatim,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 JBoss EAP 7.0 + + 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.0 JSP application in the current namespace. ++ +[subs="verbatim,macros"] +---- +$ oc get dc -o name +deploymentconfig/eap-app +---- ++ +[subs="verbatim,macros"] +---- +$ oc scale dc/eap-app --replicas=0 +deploymentconfig "eap-app" scaled +---- +. Further configure the EAP 6.4 / 7.0 JSP application prior the deployment. +[[sso-public-key-details]] +.. Configure the application with proper details about the RH-SSO 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]. +==== ++ +[subs="verbatim,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. ++ +[subs="verbatim,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. ++ +[subs="verbatim,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 +---- ++ +[subs="verbatim,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). ++ +[subs="verbatim,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.0 JSP application using the modified deployment config. ++ +[subs="verbatim,macros"] +---- +$ oc scale dc/eap-app --replicas=1 +deploymentconfig "eap-app" scaled +---- +. Expose the service as route. ++ +[subs="verbatim,macros"] +---- +$ oc get svc -o name +service/eap-app +---- ++ +[subs="verbatim,macros"] +---- +$ oc get route +No resources found. +---- ++ +[subs="verbatim,macros"] +---- +$ oc expose svc/eap-app +route "eap-app" exposed +---- ++ +[subs="verbatim,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.svg[RH-SSO 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 RH-SSO server instance against the `demo` realm. ++ +Specify username and password of the RH-SSO 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.svg[RH-SSO Example JSP Application - After User Log-in] + +* 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` RH-SSO 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` RH-SSO role: ++ +. Access the administration console of the RH-SSO server's instance. ++ +*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*. ++ +Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the RH-SSO 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.0 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. diff --git a/openshift/content/introduction/introduction.adoc b/openshift/content/introduction/introduction.adoc new file mode 100644 index 0000000000..d6706e7763 --- /dev/null +++ b/openshift/content/introduction/introduction.adoc @@ -0,0 +1,32 @@ +=== What Is Red Hat Single Sign-On? +Red Hat Single Sign-On (RH-SSO) is an integrated sign-on solution available as a Red Hat JBoss Middleware for OpenShift containerized image. The {xpaasproduct} image provides an authentication server for users to centrally log in, log out, register, and manage user accounts for web applications, mobile applications, and RESTful web services. + +[[sso-templates]] +Red Hat offers multiple OpenShift application templates utilizing the {xpaasproduct-shortname} image. + +For RH-SSO 7.2: + +* *_sso72-https_*: RH-SSO 7.2 backed by internal H2 database on the same pod. +* *_sso72-mysql_*: RH-SSO 7.2 backed by ephemeral MySQL database on a separate pod. +* *_sso72-mysql-persistent_*: RH-SSO 7.2 backed by persistent MySQL database on a separate pod. +* *_sso72-postgresql_*: RH-SSO 7.2 backed by ephemeral PostgreSQL database on a separate pod. +* *_sso72-postgresql-persistent_*: RH-SSO 7.2 backed by persistent PostgreSQL database on a separate pod. + +For RH-SSO 7.1: + +* *_sso71-https_*: RH-SSO 7.1 backed by internal H2 database on the same pod. +* *_sso71-mysql_*: RH-SSO 7.1 backed by ephemeral MySQL database on a separate pod. +* *_sso71-mysql-persistent_*: RH-SSO 7.1 backed by persistent MySQL database on a separate pod. +* *_sso71-postgresql_*: RH-SSO 7.1 backed by ephemeral PostgreSQL database on a separate pod. +* *_sso71-postgresql-persistent_*: RH-SSO 7.1 backed by persistent PostgreSQL database on a separate pod. + +Other templates that integrate with RH-SSO are also available: + +* *_eap64-sso-s2i_*: RH-SSO-enabled Red Hat JBoss Enterprise Application Platform 6.4. +* *_eap70-sso-s2i_*: RH-SSO-enabled Red Hat JBoss Enterprise Application Platform 7.0. +* *_eap71-sso-s2i_*: RH-SSO enabled Red Hat JBoss Enterprise Application Platform 7.1. +* *_datavirt63-secure-s2i_*: RH-SSO-enabled Red Hat JBoss Data Virtualization 6.3. + +These templates contain environment variables specific to RH-SSO that enable automatic RH-SSO client registration when deployed. + +See xref:Auto-Man-Client-Reg[Automatic and Manual RH-SSO Client Registration Methods] for more information. diff --git a/openshift/content/reference/reference.adoc b/openshift/content/reference/reference.adoc new file mode 100644 index 0000000000..4f29525ff8 --- /dev/null +++ b/openshift/content/reference/reference.adoc @@ -0,0 +1,631 @@ +[[sso-artifact-repository-mirrors-section]] +=== Artifact Repository Mirrors + +// Define required 'bcname' attribute for maven_mirror_url.adoc page +:bcname: sso + +// Include the Artifact Repository Mirros section +// (MAVEN_MIRROR_URL variable usage information) +include::../../common/maven_mirror_url.adoc[bcname] + +[[env_vars]] +=== Environment Variables + +==== Information Environment Variables +The following information environment variables are designed to convey +information about the image and should not be modified by the user: + +.Information Environment Variables +[cols="3",options="header"] +|=== +|Variable Name |Description |Example Value +|*_AB_JOLOKIA_AUTH_OPENSHIFT_* +|- +|*_true_* + +|*_AB_JOLOKIA_HTTPS_* +|- +|*_true_* + +|*_AB_JOLOKIA_PASSWORD_RANDOM_* +|- +|*_true_* + +|*_JBOSS_IMAGE_NAME_* +|Image name, same as Name label. +|*_redhat-sso-7/sso71-openshift_* or *_redhat-sso-7/sso72-openshift_* + +|*_JBOSS_IMAGE_RELEASE_* +|Image release, same as Release label. +|*_dev_* + +|*_JBOSS_IMAGE_VERSION_* +|Image version, same as Version label. +|*_1.0_* + +|*_JBOSS_MODULES_SYSTEM_PKGS_* +|- +|*_org.jboss.logmanager,jdk.nashorn.api_* + +|*_STI_BUILDER_* +|Provides OpenShift S2I support for jee project types. +|*_jee_* + +|=== + +==== Configuration Environment Variables +Configuration environment variables are designed to conveniently adjust the +image without requiring a rebuild, and should be set by the user as desired. + +[[conf_env_vars]] +.Configuration Environment Variables +[cols="3",options="header"] +|=== +|Variable Name |Description |Example Value +|*_AB_JOLOKIA_AUTH_OPENSHIFT_* +|Switch on client authentication for OpenShift TLS communication. The value of +this parameter can be a relative distinguished name which must be contained in +a presented client’s certificate. Enabling this parameter will automatically +switch Jolokia into https communication mode. The default CA cert is set to +`/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. +|*_true_* + +|*_AB_JOLOKIA_CONFIG_* +|If set uses this file (including path) as Jolokia JVM agent properties (as +described in Jolokia’s +link:http://www.jolokia.org/reference/html/agents.html#agents-jvm[reference +manual]). If not set, the `/opt/jolokia/etc/jolokia.properties` file will be +created using the settings as defined in this document, otherwise the rest of +the settings in this document are ignored. +|*_/opt/jolokia/custom.properties_* + +|*_AB_JOLOKIA_DISCOVERY_ENABLED_* +|Enable Jolokia discovery. Defaults to *_false_*. +|*_true_* + +|*_AB_JOLOKIA_HOST_* +|Host address to bind to. Defaults to *_0.0.0.0_*. +|*_127.0.0.1_* + +|*_AB_JOLOKIA_HTTPS_* +|Switch on secure communication with https. By default self-signed server +certificates are generated if no serverCert configuration is given in +*_AB_JOLOKIA_OPTS_*. _NOTE: If the values is set to an empty string, https is +turned `off`. If the value is set to a non empty string, https is turned `on`._ +|*_true_* + +|*_AB_JOLOKIA_ID_* +|Agent ID to use ($HOSTNAME by default, which is the container id). +|*_openjdk-app-1-xqlsj_* + +|*_AB_JOLOKIA_OFF_* +|If set disables activation of Jolokia (i.e. echos an empty value). By default, +Jolokia is enabled. _NOTE: If the values is set to an empty string, https is +turned `off`. If the value is set to a non empty string, https is turned `on`._ +|*_true_* + +|*_AB_JOLOKIA_OPTS_* +|Additional options to be appended to the agent configuration. They should be +given in the format `"key=value, key=value, …<200b> "` +|*_backlog=20_* + +|*_AB_JOLOKIA_PASSWORD_* +|Password for basic authentication. By default authentication is switched off. +|*_mypassword_* + +|*_AB_JOLOKIA_PASSWORD_RANDOM_* +|If set, a random value is generated for *_AB_JOLOKIA_PASSWORD_*, and it is +saved in the *_/opt/jolokia/etc/jolokia.pw_* file. +|*_true_* + +|*_AB_JOLOKIA_PORT_* +|Port to use (Default: *_8778_*). +|*_5432_* + +|*_AB_JOLOKIA_USER_* +|User for basic authentication. Defaults to *_jolokia_*. +|*_myusername_* + +|*_CONTAINER_CORE_LIMIT_* +|A calculated core limit as described in +link:https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt[CFS +Bandwidth Control.] +|*_2_* + +|*_GC_ADAPTIVE_SIZE_POLICY_WEIGHT_* +|The weighting given to the current Garbage Collection (GC) time versus previous +GC times. +|*_90_* + +|*_GC_MAX_HEAP_FREE_RATIO_* +|Maximum percentage of heap free after GC to avoid shrinking. +|*_40_* + +|*_GC_MAX_METASPACE_SIZE_* +|The maximum metaspace size. +|*_100_* + +|*_GGC_TIME_RATIOC_MIN_HEAP_FREE_RATIO_* +|Minimum percentage of heap free after GC to avoid expansion. +|*_20_* + +|*_GC_TIME_RATIO_* +|Specifies the ratio of the time spent outside the garbage collection (for +example, the time spent for application execution) to the time spent in the +garbage collection. +|*_4_* + +|*_JAVA_DIAGNOSTICS_* +|Set this to get some diagnostics information to standard out when things are +happening. +|*_true_* + +|*_JAVA_INITIAL_MEM_RATIO_* +|This is used to calculate a default initial heap memory based the maximal +heap memory. The default is 100 which means 100% of the maximal heap is used +for the initial heap size. You can skip this mechanism by setting this value +to 0 in which case no `-Xms` option is added. +|*_100_* + +|*_JAVA_MAX_MEM_RATIO_* +|It is used to calculate a default maximal heap memory based on a containers +restriction. If used in a Docker container without any memory constraints for +the container then this option has no effect. If there is a memory constraint +then `-Xmx` is set to a ratio of the container available memory as set here. +The default is 50 which means 50% of the available memory is used as an upper +boundary. You can skip this mechanism by setting this value to 0 in which case +no `-Xmx` option is added. +|*_40_* + +|*_JAVA_OPTS_APPEND_* +|Server startup options. +|*_-Dkeycloak.migration.action=export -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=/tmp_* + +|*_MQ_SIMPLE_DEFAULT_PHYSICAL_DESTINATION_* +|For backwards compatability, set to true to use `MyQueue` and `MyTopic` as +physical destination name defaults instead of `queue/MyQueue` and `topic/MyTopic`. +|*_false_* + +|*_OPENSHIFT_KUBE_PING_LABELS_* +|Clustering labels selector. +|*_app=sso-app_* + +|*_OPENSHIFT_KUBE_PING_NAMESPACE_* +|Clustering project namespace. +|*_myproject_* + +|*_SCRIPT_DEBUG_* +|If set to `true`, ensurses that the bash scripts are executed with the `-x` +option, printing the commands and their arguments as they are executed. +|*_true_* + +|*_SSO_ADMIN_PASSWORD_* +|Password of the administrator account for the `master` realm of the RH-SSO +server. *Required.* If no value is specified, it is auto generated and +displayed as an OpenShift Instructional message when the template is +instantiated. +|*_adm-password_* + +|*_SSO_ADMIN_USERNAME_* +|Username of the administrator account for the `master` realm of the RH-SSO +server. *Required.* If no value is specified, it is auto generated and +displayed as an OpenShift Instructional message when the template is +instantiated. +|*_admin_* + +|*_SSO_REALM_* +|Name of the realm to be created in the RH-SSO server if this environment variable +is provided. +|*_demo_* + +|*_SSO_SERVICE_PASSWORD_* +|The password for the RH-SSO service user. +|*_mgmt-password_* + +|*_SSO_SERVICE_USERNAME_* +|The username used to access the RH-SSO service. This is used by clients to create +the application client(s) within the specified RH-SSO realm. This user is created +if this environment variable is provided. +|*_sso-mgmtuser_* + +|*_SSO_TRUSTSTORE_* +|The name of the truststore file within the secret. +|*_truststore.jks_* + +|*_SSO_TRUSTSTORE_DIR_* +|Truststore directory. +|*_/etc/sso-secret-volume_* + +|*_SSO_TRUSTSTORE_PASSWORD_* +|The password for the truststore and certificate. +|*_mykeystorepass_* + +|*_SSO_TRUSTSTORE_SECRET_* +|The name of the secret containing the truststore file. Used for +_sso-truststore-volume_ volume. +|*_truststore-secret_* + +|=== + +Available link:https://docs.openshift.com/container-platform/latest/dev_guide/templates.html#overview[application templates] +for {xpaasproduct-shortname} can combine the xref:conf_env_vars[aforementioned +configuration variables] with common OpenShift variables (for example +*_APPLICATION_NAME_* or *_SOURCE_REPOSITORY_URL_*), product specific variables +(e.g. *_HORNETQ_CLUSTER_PASSWORD_*), or configuration variables typical to +database images (e.g. *_MYSQL_FT_MAX_WORD_LEN_*) yet. All of these different +types of configuration variables can be adjusted as desired to achieve the +deployed RH-SSO-enabled application will align with the intended use case as much +as possible. The list of configuration variables, available for each category +of application templates for RH-SSO-enabled applications, is described below. + +==== Template variables for all RH-SSO images + +.Configuration Variables Available For All RH-SSO Images +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_APPLICATION_NAME_* +|The name for the application. + +|*_DB_MAX_POOL_SIZE_* +|Sets xa-pool/max-pool-size for the configured datasource. + +|*_DB_TX_ISOLATION_* +|Sets transaction-isolation for the configured datasource. + +|*_DB_USERNAME_* +|Database user name. + +|*_HOSTNAME_HTTP_* +|Custom hostname for http service route. Leave blank for default hostname, +e.g.: _.._. + +|*_HOSTNAME_HTTPS_* +|Custom hostname for https service route. Leave blank for default hostname, +e.g.: _.._. + +|*_HTTPS_KEYSTORE_* +|The name of the keystore file within the secret. If defined along with +*_HTTPS_PASSWORD_* and *_HTTPS_NAME_*, enable HTTPS and set the SSL certificate +key file to a relative path under _$JBOSS_HOME/standalone/configuration_. + +|*_HTTPS_KEYSTORE_TYPE_* +|The type of the keystore file (JKS or JCEKS). + +|*_HTTPS_NAME_* +|The name associated with the server certificate (e.g. _jboss_). If defined +along with *_HTTPS_PASSWORD_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set the +SSL name. + +|*_HTTPS_PASSWORD_* +|The password for the keystore and certificate (e.g. _mykeystorepass_). If +defined along with *_HTTPS_NAME_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set +the SSL key password. + +|*_HTTPS_SECRET_* +|The name of the secret containing the keystore file. + +|*_IMAGE_STREAM_NAMESPACE_* +|Namespace in which the ImageStreams for Red Hat Middleware images are +installed. These ImageStreams are normally installed in the _openshift_ +namespace. You should only need to modify this if you've installed the +ImageStreams in a different namespace/project. + +|*_JGROUPS_CLUSTER_PASSWORD_* +|JGroups cluster password. + +|*_JGROUPS_ENCRYPT_KEYSTORE_* +|The name of the keystore file within the secret. + +|*_JGROUPS_ENCRYPT_NAME_* +|The name associated with the server certificate (e.g. _secret-key_). + +|*_JGROUPS_ENCRYPT_PASSWORD_* +|The password for the keystore and certificate (e.g. _password_). + +|*_JGROUPS_ENCRYPT_SECRET_* +|The name of the secret containing the keystore file. + +|*_SSO_ADMIN_USERNAME_* +|Username of the administrator account for the `master` realm of the RH-SSO +server. *Required.* If no value is specified, it is auto generated and +displayed as an OpenShift instructional message when the template is +instantiated. + +|*_SSO_ADMIN_PASSWORD_* +|Password of the administrator account for the `master` realm of the RH-SSO +server. *Required.* If no value is specified, it is auto generated and +displayed as an OpenShift instructional message when the template is +instantiated. + +|*_SSO_REALM_* +|Name of the realm to be created in the RH-SSO server if this environment variable +is provided. + +|*_SSO_SERVICE_USERNAME_* +|The username used to access the RH-SSO service. This is used by clients to create +the application client(s) within the specified RH-SSO realm. This user is created +if this environment variable is provided. + +|*_SSO_SERVICE_PASSWORD_* +|The password for the RH-SSO service user. + +|*_SSO_TRUSTSTORE_* +|The name of the truststore file within the secret. + +|*_SSO_TRUSTSTORE_SECRET_* +|The name of the secret containing the truststore file. Used for +*_sso-truststore-volume_* volume. + +|*_SSO_TRUSTSTORE_PASSWORD_* +|The password for the truststore and certificate. +|=== + +==== Template variables specific to *sso71-mysql*, *sso72-mysql*, *sso71-mysql-persistent*, and *sso72-mysql-persistent* + +.Configuration Variables Specific To RH-SSO-enabled MySQL Applications With Ephemeral Or Persistent Storage +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_DB_USERNAME_* +|Database user name. + +|*_DB_PASSWORD_* +|Database user password. + +|*_DB_JNDI_* +|Database JNDI name used by application to resolve the datasource, +e.g. _java:/jboss/datasources/mysql_. + +|*_MYSQL_AIO_* +|Controls the _innodb_use_native_aio_ setting value if the native AIO is +broken. + +|*_MYSQL_FT_MAX_WORD_LEN_* +|The maximum length of the word to be included in a FULLTEXT index. + +|*_MYSQL_FT_MIN_WORD_LEN_* +|The minimum length of the word to be included in a FULLTEXT index. + +|*_MYSQL_LOWER_CASE_TABLE_NAMES_* +|Sets how the table names are stored and compared. + +|*_MYSQL_MAX_CONNECTIONS_* +|The maximum permitted number of simultaneous client connections. +|=== + +==== Template variables specific to *sso71-postgresql*, *sso72-postgresql*, *sso71-postgresql-persistent*, and *sso72-postgresql-persistent* + +.Configuration Variables Specific To RH-SSO-enabled PostgreSQL Applications With Ephemeral Or Persistent Storage +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_DB_USERNAME_* +|Database user name. + +|*_DB_PASSWORD_* +|Database user password. + +|*_DB_JNDI_* +|Database JNDI name used by application to resolve the datasource, +e.g. _java:/jboss/datasources/postgresql_ + +|*_POSTGRESQL_MAX_CONNECTIONS_* +|The maximum number of client connections allowed. This also sets the maximum +number of prepared transactions. + +|*_POSTGRESQL_SHARED_BUFFERS_* +|Configures how much memory is dedicated to PostgreSQL for caching data. +|=== + +==== Template variables specific to *sso71-mysql-persistent*, *sso72-mysql-persistent*, *sso71-postgresql-persistent*, and *sso72-postgresql-persistent* + +.Configuration Variables Specific To RH-SSO-enabled MySQL / PostgreSQL Applications With Persistent Storage +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_VOLUME_CAPACITY_* +|Size of persistent storage for database volume. +|=== + +==== Template variables for general *eap64*, *eap70*, and *eap71* S2I images + +.Configuration Variables For EAP 6.4 and EAP 7 Applications Built Via S2I +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_APPLICATION_NAME_* +|The name for the application. + +|*_ARTIFACT_DIR_* +|Artifacts directory. + +|*_AUTO_DEPLOY_EXPLODED_* +|Controls whether exploded deployment content should be automatically deployed. + +|*_CONTEXT_DIR_* +|Path within Git project to build; empty for root project directory. + +|*_GENERIC_WEBHOOK_SECRET_* +|Generic build trigger secret. + +|*_GITHUB_WEBHOOK_SECRET_* +|GitHub trigger secret. + +|*_HORNETQ_CLUSTER_PASSWORD_* +|HornetQ cluster administrator password. + +|*_HORNETQ_QUEUES_* +|Queue names. + +|*_HORNETQ_TOPICS_* +|Topic names. + +|*_HOSTNAME_HTTP_* +|Custom host name for http service route. Leave blank for default host name, +e.g.: _.._. + +|*_HOSTNAME_HTTPS_* +|Custom host name for https service route. Leave blank for default host name, +e.g.: _.._. + +|*_HTTPS_KEYSTORE_TYPE_* +|The type of the keystore file (JKS or JCEKS). + +|*_HTTPS_KEYSTORE_* +|The name of the keystore file within the secret. If defined along with +*_HTTPS_PASSWORD_* and *_HTTPS_NAME_*, enable HTTPS and set the SSL certificate +key file to a relative path under _$JBOSS_HOME/standalone/configuration_. + +|*_HTTPS_NAME_* +|The name associated with the server certificate (e.g. _jboss_). If defined +along with *_HTTPS_PASSWORD_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set the +SSL name. + +|*_HTTPS_PASSWORD_* +|The password for the keystore and certificate (e.g. _mykeystorepass_). If +defined along with *_HTTPS_NAME_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set +the SSL key password. + +|*_HTTPS_SECRET_* +|The name of the secret containing the keystore file. + +|*_IMAGE_STREAM_NAMESPACE_* +|Namespace in which the ImageStreams for Red Hat Middleware images are +installed. These ImageStreams are normally installed in the _openshift_ +namespace. You should only need to modify this if you've installed the +ImageStreams in a different namespace/project. + +|*_JGROUPS_CLUSTER_PASSWORD_* +|JGroups cluster password. + +|*_JGROUPS_ENCRYPT_KEYSTORE_* +|The name of the keystore file within the secret. + +|*_JGROUPS_ENCRYPT_NAME_* +|The name associated with the server certificate (e.g. _secret-key_). + +|*_JGROUPS_ENCRYPT_PASSWORD_* +|The password for the keystore and certificate (e.g. _password_). + +|*_JGROUPS_ENCRYPT_SECRET_* +|The name of the secret containing the keystore file. + +|*_SOURCE_REPOSITORY_REF_* +|Git branch/tag reference. + +|*_SOURCE_REPOSITORY_URL_* +|Git source URI for application. +|=== + +==== Template variables specific to *eap64-sso-s2i*, *eap70-sso-s2i*, and *eap71-sso-s2i* for automatic client registration + +.Configuration Variables For EAP 6.4 and EAP 7 RH-SSO-enabled Applications Built Via S2I +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_SSO_URL_* +|RH-SSO server location. + +|*_SSO_REALM_* +|Name of the realm to be created in the RH-SSO server if this environment variable +is provided. + +|*_SSO_USERNAME_* +|The username used to access the RH-SSO service. This is used to create the +application client(s) within the specified RH-SSO realm. This should match the +*_SSO_SERVICE_USERNAME_* specified through one of the *sso71-* or *sso72-* templates. + +|*_SSO_PASSWORD_* +|The password for the RH-SSO service user. + +|*_SSO_PUBLIC_KEY_* +|RH-SSO public key. Public key is recommended to be passed into the template to +avoid man-in-the-middle security attacks. + +|*_SSO_SECRET_* +|The RH-SSO client secret for confidential access. + +|*_SSO_SERVICE_URL_* +|RH-SSO service location. + +|*_SSO_TRUSTSTORE_SECRET_* +|The name of the secret containing the truststore file. Used for +*_sso-truststore-volume_* volume. + +|*_SSO_TRUSTSTORE_* +|The name of the truststore file within the secret. + +|*_SSO_TRUSTSTORE_PASSWORD_* +|The password for the truststore and certificate. + +|*_SSO_BEARER_ONLY_* +|RH-SSO client access type. + +|*_SSO_DISABLE_SSL_CERTIFICATE_VALIDATION_* +|If true SSL communication between EAP and the RH-SSO Server is insecure +(i.e. certificate validation is disabled with curl) + +|*_SSO_ENABLE_CORS_* +|Enable CORS for RH-SSO applications. +|=== + +==== Template variables specific to *eap64-sso-s2i*, *eap70-sso-s2i*, and *eap71-sso-s2i* for automatic client registration with SAML clients + +.Configuration Variables For EAP 6.4 and EAP 7 RH-SSO-enabled Applications Built Via S2I Using SAML Protocol +[cols="2*", options="header"] +|=== +|Variable +|Description +|*_SSO_SAML_CERTIFICATE_NAME_* +|The name associated with the server certificate. + +|*_SSO_SAML_KEYSTORE_PASSWORD_* +|The password for the keystore and certificate. + +|*_SSO_SAML_KEYSTORE_* +|The name of the keystore file within the secret. + +|*_SSO_SAML_KEYSTORE_SECRET_* +|The name of the secret containing the keystore file. + +|*_SSO_SAML_LOGOUT_PAGE_* +|RH-SSO logout page for SAML applications. +|=== + +=== Exposed Ports +[cols="2",options="header"] +|=== +|Port Number | Description +|*_8443_* | HTTPS + +|*_8778_* | Jolokia monitoring + +|=== + +//// +=== Labels + +=== Datasources + +=== Clustering + +=== Security Domains + +=== HTTPS + +=== Source-to-Image (S2I) + +=== Known Issues +* There is a known issue with the EAP6 Adapter _HttpServletRequest.logout()_ in which the adapter does not log out from the application, which can create a login loop. The workaround is to call _HttpSession.invalidate();_ after _request.logout()_ to clear the Keycloak token from the session. For more information, see https://issues.jboss.org/browse/KEYCLOAK-2665[KEYCLOAK-2665]. +* The SSO logs throw a duplication error if the SSO pod is restarted while backed by a database pod. This error can be safely ignored. +* Setting _adminUrl_ to a "https://..." address in an OpenID Connect client will cause *javax.net.ssl.SSLHandshakeException* exceptions on the SSO server if the default secrets (*sso-app-secret* and *eap-app-secret*) are used. The application server must use either CA-signed certificates or configure the SSO trust store to trust the self-signed certificates. +* If the client route uses a different domain suffix to the SSO service, the client registration script will erroneously configure the client on the SSO side, causing bad redirection. +* The SSO-enabled JBoss EAP image does not properly set the *adminUrl* property during automatic client registration. As a workaround, log in to the SSO console after the application has started and manually modify the client registration *adminUrl* property to *http://__-__.__/__*. +//// diff --git a/openshift/content/tutorials/tutorials.adoc b/openshift/content/tutorials/tutorials.adoc new file mode 100644 index 0000000000..7472fa18a5 --- /dev/null +++ b/openshift/content/tutorials/tutorials.adoc @@ -0,0 +1,1245 @@ +[[Example-Deploying-SSO]] +=== Example Workflow: Preparing and Deploying the {xpaasproduct-shortname} image +[[Preparing-SSO-Authentication-for-OpenShift-Deployment]] +==== Preparing RH-SSO Authentication for OpenShift Deployment +Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. + +. Create a new project: ++ +---- +$ oc new-project sso-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 sso-app-demo namespace, which is necessary for managing the cluster. ++ +---- +$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default +---- +. The RH-SSO template requires an SSL keystore and a JGroups keystore. ++ +[NOTE] +==== +OpenShift does not permit login authentication from self-signed certificates. For demonstration purposes, this example uses _openssl_ to generate a CA certificate to sign the SSL keystore and create a truststore. This truststore is also included in the creation of the secret, and specified in the RH-SSO template. + +This example also uses _keytool_, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. +==== ++ +[WARNING] +==== +For production environments, its recommended that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS). +==== ++ +The following commands will prompt for passwords. ++ +.. Generate a CA certificate: ++ +[subs="verbatim,macros"] +---- +$ openssl req -new -newkey rsa:4096 -x509 -keyout xpaas.key -out xpaas.crt -days 365 -subj "/CN=xpaas-sso-demo.ca" +---- +.. Generate a Certificate for the SSL keystore: ++ +---- +$ keytool -genkeypair -keyalg RSA -keysize 2048 -dname "CN=secure-sso-sso-app-demo.openshift32.example.com" -alias sso-https-key -keystore sso-https.jks +---- +.. Generate a Certificate Sign Request for the SSL keystore: ++ +---- +$ keytool -certreq -keyalg rsa -alias sso-https-key -keystore sso-https.jks -file sso.csr +---- +.. Sign the Certificate Sign Request with the CA certificate: ++ +---- +$ openssl x509 -req -CA xpaas.crt -CAkey xpaas.key -in sso.csr -out sso.crt -days 365 -CAcreateserial +---- +.. Import the CA into the SSL keystore: ++ +---- +$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore sso-https.jks +---- +.. Import the signed Certificate Sign Request into the SSL keystore: ++ +---- +$ keytool -import -file sso.crt -alias sso-https-key -keystore sso-https.jks +---- +.. Import the CA into a new truststore keystore: ++ +---- +$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore truststore.jks +---- +.. Generate a secure key for the JGroups keystore: ++ +---- +$ keytool -genseckey -alias jgroups -storetype JCEKS -keystore jgroups.jceks +---- +. Create the keystore secrets with the JGroups keystore, and with the SSL keystore and truststore. The truststore is included in this example because it was necessary to sign the example SSL keystore. ++ +---- +$ oc secret new sso-jgroup-secret jgroups.jceks +$ oc secret new sso-ssl-secret sso-https.jks truststore.jks +---- +. Link the secrets to the `default` service account: ++ +---- +$ oc secrets link default sso-jgroup-secret sso-ssl-secret +---- + +==== Deploying the RH-SSO Application Template + +. Log in to the OpenShift web console and select the _sso-app-demo_ project space. +. Click *Add to Project*, then *Browse Catalog* 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 *Middleware*, then *Integration* to show the desired application template. +. Select an RH-SSO application template. This example uses *_sso72-https_*. Specify the application name, hostnames, and SSL keystore, JGroups keystore, and secret information: ++ +[cols="2*", options="header"] +|=== +|Variable +|Example Value +|*_APPLICATION_NAME_* +|_sso_ + +|*_HOSTNAME_HTTPS_* +|_secure-sso-sso-app-demo.openshift32.example.com_ + +|*_HOSTNAME_HTTP_* +|_sso-sso-app-demo.openshift32.example.com_ + +|*_HTTPS_KEYSTORE_* +|_sso-https.jks_ + +|*_HTTPS_PASSWORD_* +|_password_ + +|*_HTTPS_SECRET_* +|_sso-ssl-secret_ + +|*_JGROUPS_ENCRYPT_KEYSTORE_* +|_jgroups.jceks_ + +|*_JGROUPS_ENCRYPT_PASSWORD_* +|_password_ + +|*_JGROUPS_ENCRYPT_SECRET_* +|_sso-jgroup-secret_ +|=== ++ +Include the following variables to create a new _demorealm_ realm when the RH-SSO server is deployed and a user to manage that realm. ++ +It is *required* to specify xref:../get_started/get_started.adoc#sso-administrator-setup[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* credentials] here. If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated. ++ +[cols="2*", options="header"] +|=== +|Variable +|Example Value +|*_SSO_REALM_* +|_demorealm_ + +|*_SSO_SERVICE_USERNAME_* +|_sso-mgmtuser_ + +|*_SSO_SERVICE_PASSWORD_* +|_mgmt-password_ + +|*_SSO_ADMIN_USERNAME_* +|_admin_ + +|*_SSO_ADMIN_PASSWORD_* +|_adm-password_ +|=== ++ +This example uses self-signed certificates and must additionally include information on the truststore. These variables are not required with SSL certificates purchased from a verified Certificate Authority: ++ +[cols="2*", options="header"] +|=== +|Variable +|Example Value +|*_SSO_TRUSTSTORE_* +|_truststore.jks_ + +|*_SSO_TRUSTSTORE_SECRET_* +|_sso-ssl-secret_ + +|*_SSO_TRUSTSTORE_PASSWORD_* +|_password_ +|=== +. Click *Create* to deploy the application template and start pod deployment. This may take a couple of minutes. + +Then access the RH-SSO web console at *$$https://secure-sso-$$__.__/auth/admin* using the xref:../get_started/get_started.adoc#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 RH-SSO 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. +==== + +[[upgrading-sso-db-from-70-to-71]] +=== Example Workflow: Updating Existing Database when Migrating {xpaasproduct-shortname} Image to a new version +[IMPORTANT] +==== +* Rolling updates from {xpaasproduct-shortname} 7.0 / 7.1 to 7.2 are not supported as databases and caches are not backward compatible. +* Stop all {xpaasproduct-shortname} 7.0 / 7.1 instances before upgrading, they cannot run concurrently against the same database. +* Pre-generated scripts are not available, they are generated dynamically depending on the database. +==== + +Red Hat Single Sign-On 7.2 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 RH-SSO 7.2 for the first time. +==== + +[[automatic-db-migration]] +==== Automatic Database Migration +This process assumes that you are running RH-SSO 7.1 image link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_jboss_sso_for_openshift/#Example-Deploying-SSO[deployed using one of the following templates]: + +* *_sso71-mysql_* +* *_sso71-postgresql_* +* *_sso71-mysql-persistent_* +* *_sso71-postgresql-persistent_* + +[IMPORTANT] +==== +Stop all RH-SSO 7.1 pods before upgrading to RH-SSO 7.2, as they cannot run concurrently against the same database. +==== + +Use the following steps to automatically migrate the database schema: + +. Identify existing deployment config for RH-SSO 7.1 containers. ++ +---- +$ oc get dc -o name --selector=application=sso +deploymentconfig/sso +deploymentconfig/sso-postgresql +---- +. Stop all RH-SSO 7.1 containers in the current namespace. ++ +---- +$ oc scale --replicas=0 dc/sso +deploymentconfig "sso" scaled +---- +. Update the image change trigger in the existing deployment config to reference the RH-SSO 7.2 image. ++ +---- +$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-sso72-openshift:1.0"}]' +"sso" patched +---- +. Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers. ++ +---- +$ oc rollout latest dc/sso +deploymentconfig "sso" rolled out +---- +. Deploy RH-SSO 7.2 containers using the modified deployment config. ++ +---- +$ oc scale --replicas=1 dc/sso +deploymentconfig "sso" scaled +---- +. (Optional) Verify the database has been successfully updated. ++ +---- +$ oc get pods --selector=application=sso +NAME READY STATUS RESTARTS AGE +sso-4-vg21r 1/1 Running 0 1h +sso-postgresql-1-t871r 1/1 Running 0 2h +---- ++ +---- +$ oc logs sso-4-vg21r | grep 'Updating' +11:23:45,160 INFO [org.keycloak.connections.jpa.updater.liquibase.LiquibaseJpaUpdaterProvider] (ServerService Thread Pool -- 58) Updating database. Using changelog META-INF/jpa-changelog-master.xml +---- + +[[manual-db-migration]] +==== Manual Database Migration + +[IMPORTANT] +==== +Pre-generated scripts are not available. They are generated dynamically depending on the database. With RH-SSO 7.2 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 RH-SSO 7.2 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 RH-SSO 7.2] for further details. + +The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all RH-SSO 7.1 instances before dynamic generation of the SQL migration file. +==== + +This guide assumes the RH-SSO 7.1 for OpenShift image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_jboss_sso_for_openshift/#Example-Deploying-SSO[deployed using one of the following templates:] + +* *_sso71-mysql_* +* *_sso71-postgresql_* +* *_sso71-mysql-persistent_* +* *_sso71-postgresql-persistent_* + +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. ++ +---- +$ cat sso71-to-sso72-db-migrate-job.yaml.orig +apiVersion: batch/v1 +kind: Job +metadata: + name: sso71-to-sso72-db-migrate-job +spec: + autoSelector: true + parallelism: 0 + completions: 1 + template: + metadata: + name: sso71-to-sso72-db-migrate-job + spec: + containers: + - env: + - name: DB_SERVICE_PREFIX_MAPPING + value: <> + - name: <>_JNDI + value: <> + - name: <>_USERNAME + value: <> + - name: <>_PASSWORD + value: <> + - name: <>_DATABASE + value: <> + - name: TX_DATABASE_PREFIX_MAPPING + value: <> + - name: <> + value: <> + - name: <> + value: <> + image: <> + imagePullPolicy: Always + name: sso71-to-sso72-db-migrate-job + # Keep the pod running after SQL migration file has been generated, + # so we can retrieve it + command: ["/bin/bash", "-c", "/opt/eap/bin/openshift-launch.sh || sleep 600"] + restartPolicy: Never +---- ++ +---- +$ cp sso71-to-sso72-db-migrate-job.yaml.orig sso71-to-sso72-db-migrate-job.yaml +---- +. Copy the datasource definition and database access credentials from RH-SSO 7.1 deployment config to appropriate places in database job migration template. ++ +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 `sso71-to-sso72-db-migrate-job.yaml`. ++ +[NOTE] +==== +Although the `DB_SERVICE_PREFIX_MAPPING` environment variable allows a link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_jboss_enterprise_application_platform_for_openshift/#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. +==== ++ +---- +$ 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="sso71-to-sso72-db-migrate-job.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 (the order in which replacements are made is important): +# * <> with actual $PREFIX value and +# * <>#${PREFIX}#g" ${JOB_MIGRATION_YAML} +sed -i "s#<>_SERVICE_HOST and +# <>_SERVICE_PORT variables, add them to the datasource array. +# Their values also need to be propagated into yaml definition of the migration job. +if grep -Pq "${SERVICE}_SERVICE_HOST=[^ ]+" <<< "${SSO_DC_VARS[@]}" && + grep -Pq "${SERVICE}_SERVICE_PORT=[^ ]+" <<< "${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 (the order in which replacements are made is important): +# * <> with ${SERVICE}_SERVICE_HOST and +# * <> with "<<${SERVICE}_SERVICE_HOST_VALUE>>" +# Do this for both "HOST" and "PORT" +for KEY in "HOST" "PORT" +do + sed -i "s#<>#${SERVICE}_SERVICE_${KEY}#g" ${JOB_MIGRATION_YAML} + sed -i "s#<>#<<${SERVICE}_SERVICE_${KEY}_VALUE>>#g" \ + ${JOB_MIGRATION_YAML} +done + +# Propagate the values of the datasource array items into yaml definition of the +# migration job +for VAR in "${SSO_DC_VARS[@]}" +do + IFS=$'=' read KEY VALUE <<< $VAR + if grep -q $KEY <<< ${DB_VARS[@]} + then + KEY+="_VALUE" + # Enwrap integer port value with double quotes + if [[ ${KEY} =~ ${SERVICE}_SERVICE_PORT_VALUE ]] + then + sed -i "s#<<${KEY}>>#\"${VALUE}\"#g" ${JOB_MIGRATION_YAML} + # Character values do not need quotes + else + sed -i "s#<<${KEY}>>#${VALUE}#g" ${JOB_MIGRATION_YAML} + fi + # Verify that the value has been successfully propagated. + if grep -q '(JNDI|USERNAME|PASSWORD|DATABASE)' <<< "${KEY}" && + grep -q "<>" ${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. ++ +---- +$ 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 RH-SSO 7.2 database migration image using the link:https://github.com/iankko/openshift-examples/tree/sso_manual_db_migration[pre-configured source] and wait for the build to finish. ++ +---- +$ oc get is -n openshift | grep sso72 | cut -d ' ' -f1 +redhat-sso72-openshift +---- ++ +---- +$ oc new-build redhat-sso72-openshift:1.0~https://github.com/jboss-openshift/openshift-examples --context-dir=sso-manual-db-migration --name=sso72-db-migration-image +--> Found image bf45ac2 (7 days old) in image stream "openshift/redhat-sso72-openshift" under tag "1.0" for "redhat-sso72-openshift:1.0" + + Red Hat SSO 7.2 + --------------- + Platform for running Red Hat SSO + + Tags: sso, sso7, keycloak + + * A source build using source code from https://github.com/jboss-openshift/openshift-examples will be created + * The resulting image will be pushed to image stream "sso72-db-migration-image:latest" + * Use 'start-build' to trigger a new build + +--> Creating resources with label build=sso72-db-migration-image ... + imagestream "sso72-db-migration-image" created + buildconfig "sso72-db-migration-image" created +--> Success + Build configuration "sso72-db-migration-image" created and build triggered. + Run 'oc logs -f bc/sso72-db-migration-image' to stream the build progress. +---- ++ +---- +$ oc logs -f bc/sso72-db-migration-image --follow +Cloning "https://github.com/iankko/openshift-examples.git" ... +... +Push successful +---- +. Update the template of the database migration job (`sso71-to-sso72-db-migrate-job.yaml`) with reference to the built `sso72-db-migration-image` image. +.. Get the docker pull reference for the image. ++ +---- +$ PULL_REF=$(oc get istag -n $(oc project -q) --no-headers | grep sso72-db-migration-image | tr -s ' ' | cut -d ' ' -f 2) +---- +.. Replace the \<> field in the job template with the pull specification. ++ +---- +$ sed -i "s#<>#$PULL_REF#g" sso71-to-sso72-db-migrate-job.yaml +---- +.. Verify that the field is updated. +. Instantiate database migration job from the job template. ++ +---- +$ oc create -f sso71-to-sso72-db-migrate-job.yaml +job "sso71-to-sso72-db-migrate-job" created +---- ++ +[IMPORTANT] +==== +The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all RH-SSO 7.1 instances before dynamic generation of the SQL migration file. +==== ++ +. Identify existing deployment config for RH-SSO 7.1 containers. ++ +---- +$ oc get dc -o name --selector=application=sso +deploymentconfig/sso +deploymentconfig/sso-postgresql +---- +. Stop all RH-SSO 7.1 containers in the current namespace. ++ +---- +$ oc scale --replicas=0 dc/sso +deploymentconfig "sso" scaled +---- +. Run the database migration job and wait for the pod to be running correctly. ++ +---- +$ oc get jobs +NAME DESIRED SUCCESSFUL AGE +sso71-to-sso72-db-migrate-job 1 0 3m +---- ++ +---- +$ oc scale --replicas=1 job/sso71-to-sso72-db-migrate-job +job "sso71-to-sso72-db-migrate-job" scaled +---- ++ +---- +$ oc get pods +NAME READY STATUS RESTARTS AGE +sso-postgresql-1-n5p16 1/1 Running 1 19h +sso71-to-sso72-db-migrate-job-b87bb 1/1 Running 0 1m +sso72-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. ++ +---- +$ mkdir -p ./db-update +$ oc rsync sso71-to-sso72-db-migrate-job-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 RH-SSO 7.2 database update. +. Apply the database update manually. +* Run the following commands for *_sso71-postgresql_* and *_sso71-postgresql-persistent_* templates (PostgreSQL database): +... Copy the generated SQL migration file to the PostgreSQL pod. ++ +---- +$ oc rsync --no-perms=true ./db-update/ sso-postgresql-1-n5p16:/tmp +sending incremental file list + +sent 77 bytes received 11 bytes 176.00 bytes/sec +total size is 26,333 speedup is 299.24 +---- +... Start a shell session to the PostgreSQL pod. ++ +---- +$ oc rsh sso-postgresql-1-n5p16 +sh-4.2$ +---- +... Use the `psql` tool to apply database update manually. ++ +---- +sh-4.2$ alias psql="/opt/rh/rh-postgresql95/root/bin/psql" +sh-4.2$ psql --version +psql (PostgreSQL) 9.5.4 +sh-4.2$ psql -U _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]. +* Run the following commands for *_sso71-mysql_* and *_sso71-mysql-persistent_* templates (MySQL database): +... Given pod situation similar to the following: ++ +---- +$ oc get pods +NAME READY STATUS RESTARTS AGE +sso-mysql-1-zvhk3 1/1 Running 0 1h +sso71-to-sso72-db-migrate-job-m202t 1/1 Running 0 11m +sso72-db-migration-image-1-build 0/1 Completed 0 13m +---- +... Copy the generated SQL migration file to the MySQL pod. ++ +---- +$ 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. ++ +---- +$ oc rsh sso-mysql-1-zvhk3 +sh-4.2$ +---- +... Use the `mysql` tool to apply database update manually. ++ +---- +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 _DATABASE -u _USERNAME -p < /tmp/keycloak-database-update.sql +Enter password: +sh-4.2$ echo $? +0 +---- ++ +[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 MySQL pod. Continue with xref:image-change-trigger-update-step[updating image change trigger step]. + +[[image-change-trigger-update-step]] +[start=12] +. Update image change trigger in the existing deployment config of RH-SSO 7.1 to reference the RH-SSO 7.2 image. ++ +---- +$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-sso72-openshift:1.0"}]' +"sso" patched +---- +. Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers. ++ +---- +$ oc rollout latest dc/sso +deploymentconfig "sso" rolled out +---- +. Deploy RH-SSO 7.2 containers using the modified deployment config. ++ +---- +$ oc scale --replicas=1 dc/sso +deploymentconfig "sso" scaled +---- + +=== Example Workflow: Migrating Entire RH-SSO Server Database Across The 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 RH-SSO Authentication for OpenShift Deployment] section have been performed already. + +==== Deploying the RH-SSO 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 *_sso72-mysql_* RH-SSO application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value). ++ +[IMPORTANT] +==== +Export and import of Red Hat Single Sign-On 7.2 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 RH-SSO server boot time and its paramaters are passed in via Java system properties.] This means during one RH-SSO 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 {xpaasproduct-shortname} image, a database import is performed in order to create the RH-SSO 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 RH-SSO web console at *$$https://secure-sso-$$__.__/auth/admin* using the xref:../get_started/get_started.adoc#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 RH-SSO 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 RH-SSO 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[Red Hat Single Sign-On 7.2 server database export] only RH-SSO realms and users currently present in the database will be exported. If the exported JSON file should include also additional RH-SSO 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 RH-SSO database as a JSON file on the OpenShift pod + +. Get the RH-SSO deployment config and scale it down to zero. ++ +---- +$ oc get dc -o name +deploymentconfig/sso +deploymentconfig/sso-mysql + +$ oc scale --replicas=0 dc sso +deploymentconfig "sso" scaled +---- +. Instruct the RH-SSO 7.2 server deployed on {xpaasproduct-shortname} image to perform database export at RH-SSO server boot time. ++ +---- +oc env dc/sso -e "JAVA_OPTS_APPEND=-Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=/tmp/demorealm-export.json" +---- +. Scale the RH-SSO deployment config back up. This will start the RH-SSO server and export its database. ++ +---- +$ oc scale --replicas=1 dc sso +deploymentconfig "sso" scaled +---- +. (Optional) Verify that the export was successful. ++ +---- +$ oc get pods +NAME READY STATUS RESTARTS AGE +sso-4-ejr0k 1/1 Running 0 27m +sso-mysql-1-ozzl0 1/1 Running 0 4h + +$ oc logs sso-4-ejr0k | grep 'Export' +09:24:59,503 INFO [org.keycloak.exportimport.singlefile.SingleFileExportProvider] (ServerService Thread Pool -- 57) Exporting model into file /tmp/demorealm-export.json +09:24:59,998 INFO [org.keycloak.services] (ServerService Thread Pool -- 57) KC-SERVICES0035: Export finished successfully +---- + +==== Retrieve and import the exported JSON file + +. Retrieve the JSON file of the RH-SSO database from the pod. ++ +---- +$ oc get pods +NAME READY STATUS RESTARTS AGE +sso-4-ejr0k 1/1 Running 0 2m +sso-mysql-1-ozzl0 1/1 Running 0 4h + +$ oc rsync sso-4-ejr0k:/tmp/demorealm-export.json . +---- + +. (Optional) Import the JSON file of the RH-SSO database into an RH-SSO server running in another environment. ++ +[NOTE] +==== +For importing into an RH-SSO 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 RH-SSO server to import the resources from previously exported JSON file into the RH-SSO server's database, when the RH-SSO server is running as a Red Hat Single Sign-On 7.2 container on OpenShift: + +.. Log into the `master` realm's administration console of the RH-SSO server using the credentials used to create the administrator user. In the browser, navigate to *\http://sso-./auth/admin* for the RH-SSO web server, or to *\https://secure-sso-./auth/admin* for the encrypted RH-SSO web server. +.. At the top of the sidebar choose the name of the RH-SSO 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 RH-SSO 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.svg[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 RH-SSO server, on which the export JSON file was created, to the target RH-SSO 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 RH-SSO for Authentication +Configure OpenShift to use the RH-SSO deployment as the authorization gateway for OpenShift. This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {xpaasproduct-shortname} image], in which RH-SSO was deployed on OpenShift. + +This example adds RH-SSO as an authentication method alongside the HTPasswd method configured in the https://access.redhat.com/documentation/en/red-hat-application-services/0/openshift-primer/#understand_roles_and_authentication[OpenShift Primer]. Once configured, both methods will be available for user login to your OpenShift web console. + +==== Configuring RH-SSO Credentials +Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$_sso-app-demo_._openshift32.example.com_/auth/admin* using the xref:../get_started/get_started.adoc#sso-administrator-setup[administrator account] created during the RH-SSO 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 RH-SSO-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 for this example. + +==== Configuring OpenShift Master for Red Hat Single Sign-On 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*. The OpenShift master, which was deployed using the OpenShift Primer, is configured with HTPassword and shows the following: ++ +---- +identityProviders: +- challenge: true + login: true + name: htpasswd_auth + provider: + apiVersion: v1 + file: /etc/origin/openshift-passwd + kind: HTPasswdPasswordIdentityProvider +---- ++ +Add RH-SSO as a secondary identity provider with content similar to the following snippet: ++ +[subs="verbatim,macros"] +---- +- name: rh_sso + challenge: false + login: true + mappingInfo: 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 RH-SSO *Secret* hash for the *clientSecret* can be found in the RH-SSO web console: *Clients* -> *_openshift-demo_* -> *Credentials* +.. The endpoints for the *urls* can be found by making a request with the RH-SSO application. For example: ++ +[subs="verbatim,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: ++ +---- +$ 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 RH-SSO. 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: +---- +$ oadm policy add-role-to-user view testuser -n sso-app-demo +---- + +[[Example-EAP-Auto]] +=== Example Workflow: Automatically Registering EAP Application in RH-SSO with OpenID-Connect Client +This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {xpaasproduct-shortname} image], in which RH-SSO was deployed on OpenShift. This example prepares RH-SSO 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 RH-SSO client registration. Once deployed, the RH-SSO user can be used to authenticate and access JBoss EAP. + +[NOTE] +==== +This example uses a OpenID-Connect client but an SAML client could also be used. See xref:SSO-Clients[RH-SSO Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual RH-SSO Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients. +==== + +==== Preparing RH-SSO Authentication for OpenShift Deployment +Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. + +. Create a new project: ++ +---- +$ oc new-project eap-app-demo +---- +//. Create a service account to be used for the RH-SSO deployment: +//+ +//---- +//$ 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. ++ +---- +$ 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: ++ +---- +$ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks +---- +.. Generate a secure key for the JGroups keystore: ++ +---- +$ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks +---- +. Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files: ++ +---- +$ oc secret new eap-ssl-secret eapkeystore.jks +$ oc secret new eap-jgroup-secret eapjgroups.jceks +---- +. Add the EAP secret to the `default` service account: ++ +---- +$ oc secrets link default eap-ssl-secret eap-jgroup-secret +---- + +==== Preparing the RH-SSO Credentials +Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$__.__/auth/admin* using the xref:../get_started/get_started.adoc#sso-administrator-setup[administrator account] created during the RH-SSO 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 __ for brevity. This is used later to deploy the RH-SSO-enabled JBoss EAP image. + +*Create a Role* + +Create a role in RH-SSO 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 RH-SSO _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 RH-SSO client registration in the RH-SSO 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 RH-SSO server rights that can be used by the JBoss EAP 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 RH-SSO-enabled JBoss EAP 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 RH-SSO parameters to configure the RH-SSO 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 JBoss EAP image. + +It may take several minutes for the JBoss EAP image to deploy. + +==== Log in to the JBoss EAP Server Using RH-SSO + +. Access the JBoss EAP application server and click *Login*. You are redirected to the RH-SSO login. +. Log in using the RH-SSO user created in the example. You are authenticated against the RH-SSO server and returned to the JBoss EAP application server. + + +[[Example-EAP-Manual]] +=== Example Workflow: Manually Registering EAP Application in RH-SSO with SAML Client +This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {xpaasproduct-shortname} image], in which RH-SSO was deployed on OpenShift. + +This example prepares RH-SSO realm, role, and user credentials for an EAP project and configures an EAP for OpenShift deployment. Once deployed, the RH-SSO user can be used to authenticate and access JBoss EAP. + +[NOTE] +==== +This example uses a SAML client but an OpenID-Connect client could also be used. See xref:SSO-Clients[RH-SSO Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual RH-SSO Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients. +==== + +==== Preparing the RH-SSO Credentials +Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$__.__/auth/admin* using the xref:../get_started/get_started.adoc#sso-administrator-setup[administrator account] created during the RH-SSO 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 RH-SSO-enabled JBoss EAP image. + +*Create a Role* + +Create a role in RH-SSO 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 RH-SSO _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 RH-SSO client registration in the RH-SSO 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 RH-SSO server rights that can be used by the JBoss EAP 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 RH-SSO 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 RH-SSO Authentication for OpenShift Deployment +Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. + +. Create a new project: ++ +---- +$ oc new-project eap-app-demo +---- +//. Create a service account to be used for the SSO deployment: +//+ +//---- +//$ 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. ++ +---- +$ 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: ++ +---- +$ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks +---- +.. Generate a secure key for the JGroups keystore: ++ +---- +$ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks +---- +. Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files: ++ +---- +$ oc secret new eap-ssl-secret eapkeystore.jks +$ oc secret new eap-jgroup-secret eapjgroups.jceks +---- +. Add the EAP application secret to the EAP service account created earlier: ++ +---- +$ oc secrets link default eap-ssl-secret eap-jgroup-secret +---- + +[[modified-saml-xml]] +==== Modifying the *secure-saml-deployments* File + +The *keycloak-saml-subsystem.xml*, exported from the RH-SSO 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 RH-SSO 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 ** and ** tags and keys and replace it with keystore information: ++ +---- +... + + + + + + + + +---- ++ +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 RH-SSO client. +. Delete the second ** tag and key and replace it with the the realm certificate information: ++ +---- +... + + + + + + + +... +---- ++ +The certificate alias and password were configured when the SAML Keys were exported from the RH-SSO 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: +---- +... + + KEYCLOAK-SAML + +... +---- + +==== Deploying the Application + +You do not need to include any RH-SSO configuration for the image because that has been configured in the application itself. Navigating to the application login page redirects you to the RH-SSO login. Log in to the application through RH-SSO using the _application user_ user created earlier. diff --git a/openshift/docinfo.xml b/openshift/docinfo.xml new file mode 100644 index 0000000000..1b2b3b7033 --- /dev/null +++ b/openshift/docinfo.xml @@ -0,0 +1,13 @@ +{productname} +{productversion} +Using {xpaasproduct} + + Guide to using {xpaasproduct} + + + + {productname} Documentation Team + {productdocsemail} + + + diff --git a/openshift/images/import_realm_error.svg b/openshift/images/import_realm_error.svg new file mode 100644 index 0000000000..3fa2511508 --- /dev/null +++ b/openshift/images/import_realm_error.svg @@ -0,0 +1,95 @@ + + + + + + image/svg+xml + + + + + + + + diff --git a/openshift/images/sso_app_jee_jsp.svg b/openshift/images/sso_app_jee_jsp.svg new file mode 100644 index 0000000000..b92bb3789a --- /dev/null +++ b/openshift/images/sso_app_jee_jsp.svg @@ -0,0 +1,297 @@ + + + + + + image/svg+xml + + + + + + + + + + diff --git a/openshift/images/sso_app_jee_jsp_logged_in.svg b/openshift/images/sso_app_jee_jsp_logged_in.svg new file mode 100644 index 0000000000..c0c36cafa0 --- /dev/null +++ b/openshift/images/sso_app_jee_jsp_logged_in.svg @@ -0,0 +1,332 @@ + + + + + + image/svg+xml + + + + + + + + + + diff --git a/openshift/master.adoc b/openshift/master.adoc new file mode 100644 index 0000000000..ebe0161260 --- /dev/null +++ b/openshift/master.adoc @@ -0,0 +1,20 @@ +include::common/attributes.adoc[] +:xpaasproduct: Red Hat Single Sign-On for OpenShift +:xpaasproduct-shortname: RH-SSO for OpenShift + += {xpaasproduct} + +== Introduction +include::content/introduction/introduction.adoc[] + +== Before You Begin +include::content/before_you_begin/before_you_begin.adoc[] + +== Get Started +include::content/get_started/get_started.adoc[] + +== Tutorials +include::content/tutorials/tutorials.adoc[] + +== Reference +include::content/reference/reference.adoc[]