diff --git a/openshift/build.cfg b/openshift/build.cfg deleted file mode 100644 index 602c1f7694..0000000000 --- a/openshift/build.cfg +++ /dev/null @@ -1,2 +0,0 @@ -pdf_mono_font: "DejaVu Sans Mono" -pdf_body_font: "DejaVu Sans" diff --git a/openshift/common/attributes.adoc b/openshift/common/attributes.adoc deleted file mode 100644 index ee36459e62..0000000000 --- a/openshift/common/attributes.adoc +++ /dev/null @@ -1,5 +0,0 @@ -: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 deleted file mode 100644 index 71667a0d69..0000000000 --- a/openshift/common/common_admin.adoc +++ /dev/null @@ -1,16 +0,0 @@ -==== 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 deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/openshift/common/common_clustering.adoc b/openshift/common/common_clustering.adoc deleted file mode 100644 index ca9ef51fa2..0000000000 --- a/openshift/common/common_clustering.adoc +++ /dev/null @@ -1,25 +0,0 @@ -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 deleted file mode 100644 index b302198ddf..0000000000 --- a/openshift/common/common_datasources.adoc +++ /dev/null @@ -1,10 +0,0 @@ -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 deleted file mode 100644 index 2e98ab47d8..0000000000 --- a/openshift/common/common_eap_sso.adoc +++ /dev/null @@ -1,99 +0,0 @@ -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 deleted file mode 100644 index a7b1c26696..0000000000 --- a/openshift/common/common_https.adoc +++ /dev/null @@ -1,18 +0,0 @@ -==== 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 deleted file mode 100644 index c8f0b6f804..0000000000 --- a/openshift/common/common_s2i.adoc +++ /dev/null @@ -1,86 +0,0 @@ -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 deleted file mode 100644 index ec0869ba81..0000000000 --- a/openshift/common/common_s2i_env_vars.adoc +++ /dev/null @@ -1,39 +0,0 @@ -|`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 deleted file mode 100644 index e57b69913a..0000000000 --- a/openshift/common/common_security_domains.adoc +++ /dev/null @@ -1,34 +0,0 @@ -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 deleted file mode 100644 index d86be87a08..0000000000 --- a/openshift/common/jndi_mappings.adoc +++ /dev/null @@ -1,99 +0,0 @@ -[[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 deleted file mode 100644 index 3a5c2bc165..0000000000 --- a/openshift/common/maven_mirror_url.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// 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/advanced_concepts/advanced_concepts.adoc b/openshift/content/advanced_concepts/advanced_concepts.adoc index fa0295d4f8..c0b9b4e890 100644 --- a/openshift/content/advanced_concepts/advanced_concepts.adoc +++ b/openshift/content/advanced_concepts/advanced_concepts.adoc @@ -38,7 +38,7 @@ The *_openssl_* toolkit is used in the following example to generate a CA certif ==== 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. +See the https://access.redhat.com/documentation/en-us/jboss_enterprise_application_platform/6.1/html-single/security_guide/index#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. ==== [[create-https-keystore]] diff --git a/openshift/content/getting_started/getting_started.adoc b/openshift/content/getting_started/getting_started.adoc index b3acb3f879..5f86e488be 100644 --- a/openshift/content/getting_started/getting_started.adoc +++ b/openshift/content/getting_started/getting_started.adoc @@ -1,5 +1,5 @@ === 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: +Red Hat JBoss Middleware for OpenShift images are pulled on demand from the Red Hat Registry: link:https://access.redhat.com/containers/[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. + diff --git a/openshift/docinfo-footer.html b/openshift/docinfo-footer.html new file mode 120000 index 0000000000..a39d3bd0f6 --- /dev/null +++ b/openshift/docinfo-footer.html @@ -0,0 +1 @@ +../aggregation/navbar.html \ No newline at end of file diff --git a/openshift/docinfo.html b/openshift/docinfo.html new file mode 120000 index 0000000000..14514f94d2 --- /dev/null +++ b/openshift/docinfo.html @@ -0,0 +1 @@ +../aggregation/navbar-head.html \ No newline at end of file diff --git a/openshift/docinfo.xml b/openshift/docinfo.xml deleted file mode 100644 index a75284e533..0000000000 --- a/openshift/docinfo.xml +++ /dev/null @@ -1,10 +0,0 @@ -Red Hat Single Sign-On -7.3 -Using {xpaasproduct} - - Guide to using {xpaasproduct} - - - Red Hat Customer Content Services - - diff --git a/openshift/images/import_realm_error.png b/openshift/images/import_realm_error.png new file mode 100644 index 0000000000..940ca1c2a9 Binary files /dev/null and b/openshift/images/import_realm_error.png differ diff --git a/openshift/images/import_realm_error.svg b/openshift/images/import_realm_error.svg deleted file mode 100644 index 3fa2511508..0000000000 --- a/openshift/images/import_realm_error.svg +++ /dev/null @@ -1,95 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - diff --git a/openshift/images/sso_app_jee_jsp.png b/openshift/images/sso_app_jee_jsp.png new file mode 100644 index 0000000000..2c8726ff1c Binary files /dev/null and b/openshift/images/sso_app_jee_jsp.png differ diff --git a/openshift/images/sso_app_jee_jsp.svg b/openshift/images/sso_app_jee_jsp.svg deleted file mode 100644 index b92bb3789a..0000000000 --- a/openshift/images/sso_app_jee_jsp.svg +++ /dev/null @@ -1,297 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - - - diff --git a/openshift/images/sso_app_jee_jsp_logged_in.png b/openshift/images/sso_app_jee_jsp_logged_in.png new file mode 100644 index 0000000000..c5b0933c94 Binary files /dev/null and b/openshift/images/sso_app_jee_jsp_logged_in.png differ diff --git a/openshift/images/sso_app_jee_jsp_logged_in.svg b/openshift/images/sso_app_jee_jsp_logged_in.svg deleted file mode 100644 index c0c36cafa0..0000000000 --- a/openshift/images/sso_app_jee_jsp_logged_in.svg +++ /dev/null @@ -1,332 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - - - diff --git a/openshift/index.adoc b/openshift/index.adoc new file mode 100644 index 0000000000..3aff23af50 --- /dev/null +++ b/openshift/index.adoc @@ -0,0 +1,7 @@ +:toc: +:toclevels: 3 +:numbered: +:linkattrs: + +include::topics/templates/document-attributes-product.adoc[] +include::topics.adoc[] diff --git a/openshift/master-docinfo.xml b/openshift/master-docinfo.xml new file mode 100644 index 0000000000..7e96366212 --- /dev/null +++ b/openshift/master-docinfo.xml @@ -0,0 +1,25 @@ +{project_name} +{project_versionDoc} +For Use with {project_name} {project_versionDoc} +{xpaasproduct} +{project_versionDoc} + + This guide consists of basic information and instructions to get started with {project_name} for OpenShift {project_versionDoc} + + + Red Hat Customer Content Services + + + Copyright 2018 Red Hat, Inc. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/openshift/master.adoc b/openshift/master.adoc index 5775ff865b..08822726f0 100644 --- a/openshift/master.adoc +++ b/openshift/master.adoc @@ -1,23 +1,12 @@ -include::common/attributes.adoc[] -:xpaasproduct: Red Hat Single Sign-On for OpenShift -:xpaasproduct-shortname: RH-SSO for OpenShift +:toc: +:toclevels: 3 +:numbered: +:linkattrs: -= {xpaasproduct} +include::topics/templates/document-attributes-product.adoc[] -== Introduction -include::content/introduction/introduction.adoc[] +:openshift: -== Before You Begin -include::content/before_you_begin/before_you_begin.adoc[] += Red Hat Single Sign-On for OpenShift -== Getting Started -include::content/getting_started/getting_started.adoc[] - -== Advanced Concepts -include::content/advanced_concepts/advanced_concepts.adoc[] - -== Tutorials -include::content/tutorials/tutorials.adoc[] - -== Reference -include::content/reference/reference.adoc[] +include::topics.adoc[] diff --git a/openshift/pom.xml b/openshift/pom.xml new file mode 100644 index 0000000000..93497cc2bf --- /dev/null +++ b/openshift/pom.xml @@ -0,0 +1,46 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Red Hat Single Sign-On for OpenShift + openshift + pom + + + + + org.keycloak.documentation + header-maven-plugin + + + add-file-headers + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + + + + + maven-antrun-plugin + + + echo-output + + + + + + diff --git a/openshift/topics.adoc b/openshift/topics.adoc new file mode 100644 index 0000000000..aa4674c1e5 --- /dev/null +++ b/openshift/topics.adoc @@ -0,0 +1,9 @@ +include::topics/introduction.adoc[leveloffset=+0] + +include::topics/before_you_begin.adoc[leveloffset=+0] + +include::topics/get_started.adoc[leveloffset=+0] + +include::topics/tutorials.adoc[leveloffset=+0] + +include::topics/reference.adoc[leveloffset=+0] diff --git a/openshift/content/before_you_begin/before_you_begin.adoc b/openshift/topics/before_you_begin.adoc similarity index 94% rename from openshift/content/before_you_begin/before_you_begin.adoc rename to openshift/topics/before_you_begin.adoc index c9b1635319..2360e4f4e4 100644 --- a/openshift/content/before_you_begin/before_you_begin.adoc +++ b/openshift/topics/before_you_begin.adoc @@ -1,3 +1,5 @@ +== Before You Begin + === 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: @@ -16,7 +18,7 @@ The {xpaasproduct-shortname} image version number 7.0 and 7.1 are deprecated and ==== === 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]. +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-xpaas/0/single/openshift-primer[OpenShift Primer]. [IMPORTANT] ==== diff --git a/openshift/topics/get_started.adoc b/openshift/topics/get_started.adoc new file mode 100644 index 0000000000..04a91646f4 --- /dev/null +++ b/openshift/topics/get_started.adoc @@ -0,0 +1,931 @@ +== Get Started + +=== 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:https://access.redhat.com/containers/[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#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-us/openshift_enterprise/3.2/html-single/developer_guide/index#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_single_sign-on_for_openshift/index#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_single_sign-on_for_openshift/index#Configuring-Keystores[SSL keystore and a JGroups keystore]. This example uses `keytool`, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. +.. Generate a secure key for the SSL keystore (this example uses `password` as password for the keystore). ++ +[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.png[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.png[] + +* Click the *INVOKE SECURED* button to access the `secured` endpoint. ++ +You should see the *Message: secured* output. +* Click the *INVOKE ADMIN* button to access the `admin` endpoint. ++ +You should see *403 Forbidden* output. ++ +[NOTE] +==== +The `admin` endpoint requires users with `admin` 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/topics/introduction.adoc similarity index 99% rename from openshift/content/introduction/introduction.adoc rename to openshift/topics/introduction.adoc index df918a886a..c8c9247c10 100644 --- a/openshift/content/introduction/introduction.adoc +++ b/openshift/topics/introduction.adoc @@ -1,3 +1,5 @@ +== Introduction + === 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. diff --git a/openshift/content/reference/reference.adoc b/openshift/topics/reference.adoc similarity index 83% rename from openshift/content/reference/reference.adoc rename to openshift/topics/reference.adoc index ed2b9c6a61..197549d5a0 100644 --- a/openshift/content/reference/reference.adoc +++ b/openshift/topics/reference.adoc @@ -1,12 +1,112 @@ +== Reference + [[sso-artifact-repository-mirrors-section]] === Artifact Repository Mirrors -// Define required 'bcname' attribute for maven_mirror_url.adoc page -:bcname: sso +// 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: ++ +---- +oc get bc -o name +buildconfig/sso +---- +. Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable ++ +---- +oc env bc/sso MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" +buildconfig "sso" updated +---- +. Verify the setting ++ +---- +oc env bc/sso --list +# buildconfigs sso +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. + + + +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: ++ +---- +oc get bc -o name +buildconfig/sso +---- +. Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable ++ +---- +oc env bc/sso MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" +buildconfig "sso" updated +---- +. Verify the setting ++ +---- +oc env bc/sso --list +# buildconfigs sso +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. + + + -// Include the Artifact Repository Mirros section -// (MAVEN_MIRROR_URL variable usage information) -include::../../common/maven_mirror_url.adoc[bcname] [[env_vars]] === Environment Variables @@ -73,7 +173,7 @@ switch Jolokia into https communication mode. The default CA cert is set to |*_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 +link:https://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. diff --git a/openshift/topics/templates b/openshift/topics/templates new file mode 120000 index 0000000000..d191264115 --- /dev/null +++ b/openshift/topics/templates @@ -0,0 +1 @@ +../../topics/templates \ No newline at end of file diff --git a/openshift/content/tutorials/tutorials.adoc b/openshift/topics/tutorials.adoc similarity index 71% rename from openshift/content/tutorials/tutorials.adoc rename to openshift/topics/tutorials.adoc index 92e17374f6..7fe48aee09 100644 --- a/openshift/content/tutorials/tutorials.adoc +++ b/openshift/topics/tutorials.adoc @@ -1,6 +1,14 @@ [[RH-SSO-Binary-Builds-Tutorial]] === Example Workflow: Creating OpenShift Application from Existing Maven Binaries and Securing it Using Red Hat Single Sing-On +== Tutorials + +[[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. + 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 and Secure it Using Red Hat Single Sign-On @@ -11,7 +19,7 @@ The following example uses both link:https://github.com/keycloak/keycloak-quicks [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:] +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_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:] * *_sso72-mysql_* * *_sso72-mysql-persistent_* @@ -35,513 +43,7 @@ Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the RH-SSO a . 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] -==== -The RH-SSO 7.2 image generates three keys by default: - -* RSA key, -* HMAC key, and -* AES key - -To copy the public key information for the 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.2 image. -==== -. 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 similar to what you see in 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 shown 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] -==== -To invoke properly, the `admin` endpoint requires users with the `admin` RH-SSO role. Access for the `appuser` is forbidden because they only have the `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. [[upgrading-sso-db-from-70-to-71]] === Example Workflow: Updating Existing Database when Migrating {xpaasproduct-shortname} Image to a new version @@ -561,7 +63,7 @@ By default the database is automatically migrated when you start RH-SSO 7.2 for [[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]: +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_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates]: * *_sso71-mysql_* * *_sso71-postgresql_* @@ -638,7 +140,7 @@ See link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7. 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:] +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_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:] * *_sso71-mysql_* * *_sso71-postgresql_* @@ -699,7 +201,7 @@ Use the following script to copy `DB_SERVICE_PREFIX_MAPPING` and `TX_DATABASE_PR + [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. +Although the `DB_SERVICE_PREFIX_MAPPING` environment variable allows a link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/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. ==== + ---- @@ -1140,7 +642,7 @@ When importing objects from a non-master realm to `master` realm or vice versa, [[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] +image:images/import_realm_error.png[Example of Possible Error Message when Performing Partial Import from Previously Exported JSON File] In such cases, it is necessary first to create the missing clients, having the *Access Type* set to *bearer-only*. These clients can be created by manual copy of their characteristics from the source 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. @@ -1161,7 +663,7 @@ The administration console import allows you to *overwrite* resources if you cho === 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. +This example adds RH-SSO as an authentication method alongside the HTPasswd method configured in the https://access.redhat.com/documentation/en/red-hat-xpaas/0/single/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:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the RH-SSO deployment. @@ -1510,7 +1012,7 @@ Export the SAML Keys: 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*. +. 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. + @@ -1583,7 +1085,7 @@ The *keycloak-saml-subsystem.xml*, exported from the RH-SSO client in a previous + 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 realm certificate information: +. Delete the second ** tag and key and replace it with the the realm certificate information: + ---- ... diff --git a/pom.xml b/pom.xml index dd5930c34b..95a2e8ea86 100644 --- a/pom.xml +++ b/pom.xml @@ -37,6 +37,7 @@ server_development server_installation upgrading + openshift aggregation tests @@ -205,4 +206,4 @@ - \ No newline at end of file + diff --git a/tests/src/test/java/org/keycloak/documentation/test/OpenShiftTest.java b/tests/src/test/java/org/keycloak/documentation/test/OpenShiftTest.java new file mode 100644 index 0000000000..a97b5f7d3a --- /dev/null +++ b/tests/src/test/java/org/keycloak/documentation/test/OpenShiftTest.java @@ -0,0 +1,10 @@ +package org.keycloak.documentation.test; + +public class OpenShiftTest extends AbstractDocsTest { + + @Override + public String getGuideDirName() { + return "openshift"; + } + +} diff --git a/tests/src/test/java/org/keycloak/documentation/test/utils/HttpUtils.java b/tests/src/test/java/org/keycloak/documentation/test/utils/HttpUtils.java index d037348fc7..208c18f808 100644 --- a/tests/src/test/java/org/keycloak/documentation/test/utils/HttpUtils.java +++ b/tests/src/test/java/org/keycloak/documentation/test/utils/HttpUtils.java @@ -36,7 +36,7 @@ public class HttpUtils { response.setContent(w.toString()); } response.setSuccess(true); - } else if (status == 302) { + } else if (status == 301 || status == 302) { String location = URLDecoder.decode(connection.getHeaderField("Location"), "utf-8"); response.setRedirectLocation(location); response.setSuccess(false); diff --git a/tests/src/test/resources/ignored-link-redirects b/tests/src/test/resources/ignored-link-redirects index 93e4249b06..ee4b6e1d29 100644 --- a/tests/src/test/resources/ignored-link-redirects +++ b/tests/src/test/resources/ignored-link-redirects @@ -7,4 +7,6 @@ https://apps.dev.microsoft.com/?mkt=en-us&deeplink=/appList/create/sapi&referrer /wiki/spaces/ops4j/pages/5046841/Pax Web Extender - War /wiki/spaces/ops4j/pages/5046828/Pax Web Extender - Whiteboard /wiki/spaces/ops4j/pages/5046828/Pax Web Extender - Whiteboard -https://nodejs.org/en/ \ No newline at end of file +https://nodejs.org/en/ +http://docs.openshift.com/container-platform/* +https://access.redhat.com/documentation/en/red-hat-jboss-middleware-for-openshift/3/single/openshift-primer/ \ No newline at end of file diff --git a/tests/src/test/resources/ignored-links b/tests/src/test/resources/ignored-links index f27b308b92..0220ae743c 100644 --- a/tests/src/test/resources/ignored-links +++ b/tests/src/test/resources/ignored-links @@ -14,4 +14,6 @@ http://node12:8080* http://node21:8080* http://node22:8080* http://web.example.com* -https://github.com/keycloak/keycloak-documentation/blob/master/* \ No newline at end of file +https://github.com/keycloak/keycloak-documentation/blob/master/* +https://openshift.example.com:8443/console +https://github.com/keycloak/keycloak-quickstarts.git diff --git a/topics/templates/document-attributes-product.adoc b/topics/templates/document-attributes-product.adoc index 32da828751..ce32ebb922 100644 --- a/topics/templates/document-attributes-product.adoc +++ b/topics/templates/document-attributes-product.adoc @@ -31,6 +31,9 @@ :developerguide_actiontoken_link: {developerguide_link}#_action_token_spi :gettingstarted_name: Getting Started Guide :gettingstarted_link: {project_doc_base_url}/getting_started_guide/ +:xpaasproduct: Red Hat Single Sign-On for OpenShift +:xpaasproduct_link: {project_doc_base_url}/openshift/ +:xpaasproduct-shortname: RH-SSO for OpenShift :upgradingguide_name: Upgrading Guide :upgradingguide_link: {project_doc_base_url}/upgrading_guide/ :installguide_name: Server Installation and Configuration Guide @@ -79,6 +82,7 @@ :appserver_managementcli_link: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html-single/configuration_guide/#management_cli_overview :appserver_managementconsole_link: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html-single/configuration_guide/#management_console_overview + :jdgserver_name: JDG :jdgserver_version: 7.1.0