diff --git a/openshift/topics/advanced_concepts.adoc b/openshift/topics/advanced_concepts.adoc index 765c845766..deab831296 100644 --- a/openshift/topics/advanced_concepts.adoc +++ b/openshift/topics/advanced_concepts.adoc @@ -9,11 +9,13 @@ Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. . Create a new project: + +[subs="verbatim,macros,attributes"] ---- $ oc new-project sso-app-demo ---- . Add the `view` role to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. This enables the service account to view all the resources in the sso-app-demo namespace, which is necessary for managing the cluster. + +[subs="verbatim,macros,attributes"] ---- $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default ---- @@ -49,17 +51,19 @@ See the https://access.redhat.com/documentation/en-us/jboss_enterprise_applicati [[generate-ca-certificate]] .. Generate a CA certificate. Pick and remember the password. Provide identical password, when xref:signing-csr-with-ca-certificate[signing the certificate sign request with the CA certificate] below: + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ openssl req -new -newkey rsa:4096 -x509 -keyout xpaas.key -out xpaas.crt -days 365 -subj "/CN=xpaas-sso-demo.ca" ---- .. Generate a CA certificate for the HTTPS keystore. Provide `mykeystorepass` as the keystore password: + +[subs="verbatim,macros,attributes"] ---- $ keytool -genkeypair -keyalg RSA -keysize 2048 -dname "CN=secure-sso-sso-app-demo.openshift.example.com" -alias jboss -keystore keystore.jks ---- .. Generate a certificate sign request for the HTTPS keystore. Provide `mykeystorepass` as the keystore password: + +[subs="verbatim,macros,attributes"] ---- $ keytool -certreq -keyalg rsa -alias jboss -keystore keystore.jks -file sso.csr ---- @@ -68,16 +72,19 @@ $ keytool -certreq -keyalg rsa -alias jboss -keystore keystore.jks -file sso.csr [start=4] .. Sign the certificate sign request with the CA certificate. Provide the same password that was used to xref:generate-ca-certificate[generate the CA certificate]: + +[subs="verbatim,macros,attributes"] ---- $ openssl x509 -req -CA xpaas.crt -CAkey xpaas.key -in sso.csr -out sso.crt -days 365 -CAcreateserial ---- .. Import the CA certificate into the HTTPS keystore. Provide `mykeystorepass` as the keystore password. Reply `yes` to `Trust this certificate? [no]:` question: + +[subs="verbatim,macros,attributes"] ---- $ keytool -import -file xpaas.crt -alias xpaas.ca -keystore keystore.jks ---- .. Import the signed certificate sign request into the HTTPS keystore. Provide `mykeystorepass` as the keystore password: + +[subs="verbatim,macros,attributes"] ---- $ keytool -import -file sso.crt -alias jboss -keystore keystore.jks ---- @@ -87,6 +94,7 @@ $ keytool -import -file sso.crt -alias jboss -keystore keystore.jks Provide `password` as the keystore password: +[subs="verbatim,macros,attributes"] ---- $ keytool -genseckey -alias secret-key -storetype JCEKS -keystore jgroups.jceks ---- @@ -96,6 +104,7 @@ $ keytool -genseckey -alias secret-key -storetype JCEKS -keystore jgroups.jceks Provide `mykeystorepass` as the truststore password. Reply `yes` to `Trust this certificate? [no]:` question: +[subs="verbatim,macros,attributes"] ---- $ keytool -import -file xpaas.crt -alias xpaas.ca -keystore truststore.jks ---- @@ -107,11 +116,13 @@ OpenShift uses objects called link:https://docs.openshift.com/container-platform . Create the secrets for the HTTPS and JGroups keystores, and RH-SSO server truststore, generated in the xref:Configuring-Keystores[previous section]. + +[subs="verbatim,macros,attributes"] ---- $ oc secret new sso-app-secret keystore.jks jgroups.jceks truststore.jks ---- . Link these secrets to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[default] service account, which is used to run RH-SSO pods. + +[subs="verbatim,macros,attributes"] ---- $ oc secrets link default sso-app-secret ---- @@ -122,17 +133,18 @@ After the aforementioned xref:Configuring-Keystores[keystores] and xref:Configur [WARNING] ==== -For simplicity, the values of *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, *_HTTPS_PASSWORD_*, *_JGROUPS_ENCRYPT_PASSWORD_*, and *_SSO_TRUSTSTORE_PASSWORD_* variables xref:advanced-topics-deploy-sso72-https-template[in the following command] have been chosen to match the default values of the respective parameters of the *_sso72-https_* RH-SSO application template. +For simplicity, the values of *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, *_HTTPS_PASSWORD_*, *_JGROUPS_ENCRYPT_PASSWORD_*, and *_SSO_TRUSTSTORE_PASSWORD_* variables xref:advanced-topics-deploy-{project_templates_version}-https-template[in the following command] have been chosen to match the default values of the respective parameters of the *_{project_templates_version}-https_* RH-SSO application template. For production environments, Red Hat recommends that you consult the on-site policy, specific to your organization for guidance on how to generate sufficiently strong user name and password for the administrator user account of the RH-SSO server, and passwords for the HTTPS and JGroups keystores, and the truststore of the RH-SSO server. -Be aware that *the passwords provided when provisioning the template need to match the passwords provided when creating the keystores*. If using different username and passwords, modify the values of respective xref:advanced-topics-deploy-sso72-https-template[template parameters] as appropriate for your environment. +Be aware that *the passwords provided when provisioning the template need to match the passwords provided when creating the keystores*. If using different username and passwords, modify the values of respective xref:advanced-topics-deploy-{project_templates_version}-https-template[template parameters] as appropriate for your environment. ==== [NOTE] ==== The following commands using the *_keytool_*, a package *included with the Java Development Kit*, can be used to determine the names associated with the certificate: +[subs="verbatim,macros,attributes"] ---- $ keytool -v -list -keystore keystore.jks | grep Alias Enter keystore password: mykeystorepass @@ -140,6 +152,7 @@ Alias name: xpaas.ca Alias name: jboss ---- +[subs="verbatim,macros,attributes"] ---- $ keytool -v -list -keystore jgroups.jceks -storetype jceks | grep Alias Enter keystore password: password @@ -149,9 +162,10 @@ Alias name: secret-key Finally, the *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, and the *_SSO_REALM_* template parameters in the following command are optional. ==== -[[advanced-topics-deploy-sso72-https-template]] +[[advanced-topics-deploy-{project_templates_version}-https-template]] +[subs="verbatim,macros,attributes"] ---- -$ oc new-app --template=sso72-https \ +$ oc new-app --template={project_templates_version}-https \ -p HTTPS_SECRET="sso-app-secret" \ -p HTTPS_KEYSTORE="keystore.jks" \ -p HTTPS_NAME="jboss" \ @@ -166,7 +180,7 @@ $ oc new-app --template=sso72-https \ -p SSO_TRUSTSTORE="truststore.jks" \ -p SSO_TRUSTSTORE_PASSWORD="mykeystorepass" \ -p SSO_TRUSTSTORE_SECRET="sso-app-secret" ---> Deploying template "openshift/sso72-https" to project sso-app-demo +--> Deploying template "openshift/{project_templates_version}-https" to project sso-app-demo Red Hat Single Sign-On 7.2 (Ephemeral with passthrough TLS) --------- @@ -217,6 +231,7 @@ $ oc new-app --template=sso72-https \ After the template got deployed, identify the available routes: +[subs="verbatim,macros,attributes"] ---- $ oc get routes ---- @@ -332,9 +347,9 @@ When deploying RH-SSO application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADM ==== The lifespan of the RH-SSO server's administrator account depends upon the storage type used to store the RH-SSO server's database: -* For an in-memory database mode (*_sso72-https_* and *_sso72-x509-https_* templates) the account exists throughout the lifecycle of the particular RH-SSO pod (stored account data is lost upon pod destruction), -* For an ephemeral database mode (*_sso72-mysql_* and *_sso72-postgresql_* templates) the account exists throughout the lifecycle of the database pod (even if the 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 (*_sso72-mysql-persistent_*, *_sso72-x509-mysql-persistent_*, *_sso72-postgresql-persistent_*, and *_sso72-x509-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. +* For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates) the account exists throughout the lifecycle of the particular RH-SSO pod (stored account data is lost upon pod destruction), +* For an ephemeral database mode (*_{project_templates_version}-mysql_* and *_{project_templates_version}-postgresql_* templates) the account exists throughout the lifecycle of the database pod (even if the 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 (*_{project_templates_version}-mysql-persistent_*, *_{project_templates_version}-x509-mysql-persistent_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-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). ==== @@ -350,6 +365,7 @@ Run the following commands to prepare the previously created deployment config o . Identify the deployment config of the RH-SSO application. + +[subs="verbatim,macros,attributes"] ---- $ oc get dc -o name deploymentconfig/sso @@ -357,6 +373,7 @@ deploymentconfig/sso-mysql ---- . Clear the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables setting. + +[subs="verbatim,macros,attributes"] ---- $ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD="" ---- @@ -369,6 +386,7 @@ Run following commands to create an administrator account for the `master` realm . Identify the RH-SSO application pod. + +[subs="verbatim,macros,attributes"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE @@ -377,12 +395,14 @@ sso-mysql-6-d97pf 1/1 Running 0 2m ---- . Open a remote shell session to the {project_openshift_product_name} container. + +[subs="verbatim,macros,attributes"] ---- $ 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. + +[subs="verbatim,macros,attributes"] ---- sh-4.2$ cd /opt/eap/bin/ sh-4.2$ ./add-user-keycloak.sh -r master -u sso_admin -p sso_password @@ -395,6 +415,7 @@ The `sso_admin`/`sso_password` credentials in the example above are for demonstr ==== . Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly. + +[subs="verbatim,macros,attributes"] ---- sh-4.2$ ./jboss-cli.sh --connect ':reload' { @@ -411,7 +432,7 @@ When restarting the server it is important to restart just the JBoss EAP process === Deployment Process -Once deployed, the *_sso72-https_* and *_sso72-x509-https_* templates create a single pod that contains both the database and the RH-SSO servers. The *_sso72-mysql_*, *_sso72-mysql-persistent_*, *_sso72-x509-mysql-persistent_*, *_sso72-postgresql_*, *_sso72-postgresql-persistent_*, and *_sso72-x509-postgresql-persistent_* templates create two pods, one for the database server and one for the RH-SSO web server. +Once deployed, the *_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates create a single pod that contains both the database and the RH-SSO servers. The *_{project_templates_version}-mysql_*, *_{project_templates_version}-mysql-persistent_*, *_{project_templates_version}-x509-mysql-persistent_*, *_{project_templates_version}-postgresql_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-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 from its custom configured hostnames, or from the default hostnames: @@ -439,6 +460,7 @@ It is required to specify the client type in the ** key of the appl The following is an example snippet for the application *web.xml* to configure an OIDC client: +[subs="verbatim,macros,attributes"] ---- ... @@ -533,7 +555,7 @@ See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application 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"] +[subs="verbatim,macros,attributes"] ---- oadm policy add-role-to-user view -n ---- diff --git a/openshift/topics/get_started.adoc b/openshift/topics/get_started.adoc index 734081409c..25a9816890 100644 --- a/openshift/topics/get_started.adoc +++ b/openshift/topics/get_started.adoc @@ -24,21 +24,23 @@ To update to the latest {project_openshift_product_name} images, run the followi . 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. + +[subs="verbatim,macros,attributes"] ---- $ 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: + +[subs="verbatim,macros,attributes"] ---- -$ for resource in sso72-image-stream.json \ - sso72-https.json \ - sso72-mysql.json \ - sso72-mysql-persistent.json \ - sso72-postgresql.json \ - sso72-postgresql-persistent.json \ - sso72-x509-https.json \ - sso72-x509-mysql-persistent.json \ - sso72-x509-postgresql-persistent.json +$ for resource in {project_templates_version}-image-stream.json \ + {project_templates_version}-https.json \ + {project_templates_version}-mysql.json \ + {project_templates_version}-mysql-persistent.json \ + {project_templates_version}-postgresql.json \ + {project_templates_version}-postgresql-persistent.json \ + {project_templates_version}-x509-https.json \ + {project_templates_version}-x509-mysql-persistent.json \ + {project_templates_version}-x509-postgresql-persistent.json do oc replace -n openshift --force -f \ https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.4.16/sso/${resource} @@ -46,8 +48,9 @@ done ---- . Run the following command to install the RH-SSO 7.2 OpenShift image streams in the `openshift` project: + +[subs="verbatim,macros,attributes"] ---- -$ oc -n openshift import-image redhat-sso72-openshift:1.2 +$ oc -n openshift import-image redhat-{project_templates_version}-openshift:{project_latest_image_tag} ---- === Preparing and Deploying the {project_openshift_product_name} Application Templates @@ -73,7 +76,7 @@ OpenShift uses objects called `Secrets` to hold sensitive information, such as p The {project_openshift_product_name} 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"] +[subs="verbatim,macros,attributes"] ---- $ oc secret new $ oc secret new @@ -88,19 +91,19 @@ The service account that you create must be configured with the correct permissi . Create a service account to be used for the SSO deployment: + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ 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"] +[subs="verbatim,macros,attributes"] ---- $ oc policy add-role-to-user view system:serviceaccount:: -n ---- . Link the secrets created for the project to the service account: + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc secrets link ---- @@ -135,9 +138,9 @@ When deploying RH-SSO application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADM ==== 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. +* For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-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 (*_{project_templates_version}-mysql_* and *_{project_templates_version}-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 (*_{project_templates_version}-mysql-persistent_*, *_{project_templates_version}-x509-mysql-persistent_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-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). ==== @@ -153,6 +156,7 @@ Run the following commands to prepare the previously created deployment config o . Identify the deployment config of the RH-SSO application. + +[subs="verbatim,macros,attributes"] ---- $ oc get dc -o name deploymentconfig/sso @@ -160,6 +164,7 @@ deploymentconfig/sso-mysql ---- . Clear the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables setting. + +[subs="verbatim,macros,attributes"] ---- $ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD="" ---- @@ -172,6 +177,7 @@ Run following commands to create administrator account for the `master` realm of . Identify the RH-SSO application pod. + +[subs="verbatim,macros,attributes"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE @@ -180,12 +186,14 @@ sso-mysql-6-d97pf 1/1 Running 0 2m ---- . Open a remote shell session to {project_openshift_product_name} container. + +[subs="verbatim,macros,attributes"] ---- $ 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. + +[subs="verbatim,macros,attributes"] ---- sh-4.2$ cd /opt/eap/bin/ sh-4.2$ ./add-user-keycloak.sh -r master -u sso_admin -p sso_password @@ -198,6 +206,7 @@ The `sso_admin`/`sso_password` credentials in the example above are for demonstr ==== . Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly. + +[subs="verbatim,macros,attributes"] ---- sh-4.2$ ./jboss-cli.sh --connect ':reload' { @@ -280,7 +289,7 @@ For more information on OpenShift route types, see the link:https://docs.openshi ==== 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. +Once deployed, the *_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates create a single pod that contains both the database and the RH-SSO servers. The *_{project_templates_version}-mysql_*, *_{project_templates_version}-mysql-persistent_*, *_{project_templates_version}-x509-mysql-persistent_*, *_{project_templates_version}-postgresql_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-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: @@ -308,6 +317,7 @@ It is required to specify the client type in the ** key of the appl The following is an example snippet for the application *web.xml* to configure an OIDC client: +[subs="verbatim,macros,attributes"] ---- ... @@ -402,7 +412,7 @@ See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application 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"] +[subs="verbatim,macros,attributes"] ---- oadm policy add-role-to-user view -n ---- @@ -421,14 +431,12 @@ The following example uses both link:https://github.com/keycloak/keycloak-quicks ==== This guide assumes the {project_openshift_product_name} image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:] -* *_sso71-mysql_* -* *_sso72-mysql_* -* *_sso71-postgresql_* -* *_sso72-postgresql_* -* *_sso71-mysql-persistent_* -* *_sso72-mysql-persistent_* -* *_sso71-postgresql-persistent_* -* *_sso72-postgresql-persistent_* +* *_{project_templates_version}-mysql_* +* *_{project_templates_version}-postgresql_* +* *_{project_templates_version}-mysql-persistent_* +* *_{project_templates_version}-x509-mysql-persistent_* +* *_{project_templates_version}-postgresql-persistent_* +* *_{project_templates_version}-x509-postgresql-persistent_* ==== ===== Create RH-SSO Realm, Roles, and User for the EAP 6.4 / 7.0 JSP Application @@ -514,20 +522,20 @@ You can select multiple items at once by holding the *Ctrl* key and simultaneous . Create a new project for the EAP 6.4 / 7.0 JSP application. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ 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"] +[subs="verbatim,macros,attributes"] ---- $ 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"] +[subs="verbatim,macros,attributes"] ---- $ keytool -genkeypair \ -dname "CN=secure-eap-app-eap-app-demo.openshift.example.com" \ @@ -537,7 +545,7 @@ $ keytool -genkeypair \ ---- .. Generate a secure key for the JGroups keystore (this example uses `password` as password for the keystore). + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ keytool -genseckey \ -alias jgroups \ @@ -546,18 +554,18 @@ $ keytool -genseckey \ ---- .. Generate the EAP 6.4 / 7.0 for OpenShift secrets with the SSL and JGroup keystore files. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc secret new eap-ssl-secret eapkeystore.jks ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ 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"] +[subs="verbatim,macros,attributes"] ---- $ oc secrets link default eap-ssl-secret eap-jgroup-secret ---- @@ -566,7 +574,7 @@ $ oc secrets link default eap-ssl-secret eap-jgroup-secret . Clone the source code. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ git clone https://github.com/keycloak/keycloak-quickstarts.git ---- @@ -574,12 +582,12 @@ $ git clone https://github.com/keycloak/keycloak-quickstarts.git . 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"] +[subs="verbatim,macros,attributes"] ---- $ cd keycloak-quickstarts/service-jee-jaxrs/ ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ mvn clean package -DskipTests [INFO] Scanning for projects... @@ -598,23 +606,22 @@ $ mvn clean package -DskipTests ---- .. *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"] -+ +[subs="verbatim,macros,attributes"] ---- service-jee-jaxrs]$ cd ../app-jee-jsp/ ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ sed -i /\/s/^/\<\!--/ pom.xml ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ sed -i '/\(<\/executions>\)/a\-->' pom.xml ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ mvn clean package -DskipTests [INFO] Scanning for projects... @@ -646,28 +653,28 @@ Application archives in the *deployments/* subdirectory of the main binary build + 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"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ ls config pom.xml README.md src target ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ mkdir -p sso-eap7-bin-demo/deployments ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ cp target/app-jsp.war sso-eap7-bin-demo/deployments/ ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ cp ../service-jee-jaxrs/target/service.war sso-eap7-bin-demo/deployments/ ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ tree sso-eap7-bin-demo/ sso-eap7-bin-demo/ @@ -699,7 +706,7 @@ Location of the standard deployments directory depends on the underlying base im ==== . Identify the image stream for EAP 6.4 / 7.0 image. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc get is -n openshift | grep eap | cut -d ' ' -f 1 jboss-eap64-openshift @@ -716,7 +723,7 @@ jboss-eap71-openshift 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"] +[subs="verbatim,macros,attributes"] ---- $ oc new-build --binary=true \ --image-stream=jboss-eap70-openshift \ @@ -740,7 +747,7 @@ $ oc new-build --binary=true \ ---- . 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"] +[subs="verbatim,macros,attributes"] ---- app-jee-jsp]$ oc start-build eap-app \ --from-dir=./sso-eap7-bin-demo/ \ @@ -765,7 +772,7 @@ Push successful ---- . Create a new OpenShift application based on the build. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ 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" @@ -788,13 +795,13 @@ $ oc new-app eap-app ---- . Stop all running containers of the EAP 6.4 / 7.0 JSP application in the current namespace. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc get dc -o name deploymentconfig/eap-app ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc scale dc/eap-app --replicas=0 deploymentconfig "eap-app" scaled @@ -808,7 +815,7 @@ deploymentconfig "eap-app" scaled 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"] +[subs="verbatim,macros,attributes"] ---- $ oc set env dc/eap-app \ -e HOSTNAME_HTTP="eap-app-eap-app-demo.openshift.example.com" \ @@ -824,7 +831,7 @@ deploymentconfig "eap-app" updated ---- .. Configure the application with details about both the SSL and JGroups keystore. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc set env dc/eap-app \ -e HTTPS_KEYSTORE_DIR="/etc/eap-secret-volume" \ @@ -838,7 +845,7 @@ deploymentconfig "eap-app" updated ---- .. Define OpenShift volumes for both the SSL and JGroups secrets created earlier. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc volume dc/eap-app --add \ --name="eap-keystore-volume" \ @@ -848,7 +855,7 @@ $ oc volume dc/eap-app --add \ deploymentconfig "eap-app" updated ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc volume dc/eap-app --add \ --name="eap-jgroups-keystore-volume" \ @@ -859,7 +866,7 @@ 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"] +[subs="verbatim,macros,attributes"] ---- $ oc patch dc/eap-app --type=json \ -p '[{"op": "add", "path": "/spec/template/spec/serviceAccountName", "value": "default"}]' @@ -867,32 +874,32 @@ $ oc patch dc/eap-app --type=json \ ---- . Deploy container of the EAP 6.4 / 7.0 JSP application using the modified deployment config. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc scale dc/eap-app --replicas=1 deploymentconfig "eap-app" scaled ---- . Expose the service as route. + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc get svc -o name service/eap-app ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc get route No resources found. ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc expose svc/eap-app route "eap-app" exposed ---- + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- $ oc get route NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD diff --git a/openshift/topics/introduction.adoc b/openshift/topics/introduction.adoc index 9e31d0be43..2a26ba6838 100644 --- a/openshift/topics/introduction.adoc +++ b/openshift/topics/introduction.adoc @@ -9,18 +9,18 @@ Red Hat offers multiple OpenShift application templates utilizing the {project_o [[passthrough-templates]] * Templates using HTTPS and JGroups keystores and a truststore for the RH-SSO server, all prepared beforehand. These secure the TLS communication using link:https://docs.openshift.com/container-platform/latest/architecture/networking/routes.html#passthrough-termination[passthrough TLS termination]: -** *_sso72-https_*: RH-SSO 7.2 backed by internal H2 database on the same pod. -** *_sso72-mysql_*: RH-SSO 7.2 backed by ephemeral MySQL database on a separate pod. -** *_sso72-mysql-persistent_*: RH-SSO 7.2 backed by persistent MySQL database on a separate pod. -** *_sso72-postgresql_*: RH-SSO 7.2 backed by ephemeral PostgreSQL database on a separate pod. -** *_sso72-postgresql-persistent_*: RH-SSO 7.2 backed by persistent PostgreSQL database on a separate pod. +** *_{project_templates_version}-https_*: RH-SSO 7.2 backed by internal H2 database on the same pod. +** *_{project_templates_version}-mysql_*: RH-SSO 7.2 backed by ephemeral MySQL database on a separate pod. +** *_{project_templates_version}-mysql-persistent_*: RH-SSO 7.2 backed by persistent MySQL database on a separate pod. +** *_{project_templates_version}-postgresql_*: RH-SSO 7.2 backed by ephemeral PostgreSQL database on a separate pod. +** *_{project_templates_version}-postgresql-persistent_*: RH-SSO 7.2 backed by persistent PostgreSQL database on a separate pod. [[reencrypt-templates]] * Templates using OpenShift's internal link:https://docs.openshift.com/container-platform/latest/dev_guide/secrets.html#service-serving-certificate-secrets[service serving x509 certificate secrets] to automatically create the HTTPS keystore used for serving secure content. The JGroups cluster traffic is authenticated using the `AUTH` protocol and encrypted using the `ASYM_ENCRYPT` protocol. The RH-SSO server truststore is also created automatically, containing the */var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt* CA certificate file, which is used to sign the certificate for HTTPS keystore. Moreover, the truststore for the RH-SSO server is pre-populated with the all known, trusted CA certificate files found in the Java system path. These templates secure the TLS communication using link:https://docs.openshift.com/container-platform/latest/architecture/networking/routes.html#re-encryption-termination[re-encryption TLS termination]: -** *_sso72-x509-https_*: RH-SSO 7.2 with auto-generated HTTPS keystore and RH-SSO truststore, backed by internal H2 database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic. -** *_sso72-x509-mysql-persistent_*: RH-SSO 7.2 with auto-generated HTTPS keystore and RH-SSO truststore, backed by persistent MySQL database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic. -** *_sso72-x509-postgresql-persistent_*: RH-SSO 7.2 with auto-generated HTTPS keystore and RH-SSO truststore, backed by persistent PostgreSQL database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic. +** *_{project_templates_version}-x509-https_*: RH-SSO 7.2 with auto-generated HTTPS keystore and RH-SSO truststore, backed by internal H2 database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic. +** *_{project_templates_version}-x509-mysql-persistent_*: RH-SSO 7.2 with auto-generated HTTPS keystore and RH-SSO truststore, backed by persistent MySQL database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic. +** *_{project_templates_version}-x509-postgresql-persistent_*: RH-SSO 7.2 with auto-generated HTTPS keystore and RH-SSO truststore, backed by persistent PostgreSQL database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic. Other templates that integrate with RH-SSO are also available: diff --git a/openshift/topics/reference.adoc b/openshift/topics/reference.adoc index 19c676e13a..82aaa1f126 100644 --- a/openshift/topics/reference.adoc +++ b/openshift/topics/reference.adoc @@ -30,20 +30,23 @@ build configuration of the application as follows: . Identify the name of the build configuration to apply `MAVEN_MIRROR_URL` variable against: + +[subs="verbatim,macros,attributes"] ---- -oc get bc -o name +$ oc get bc -o name buildconfig/sso ---- . Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable + +[subs="verbatim,macros,attributes"] ---- -oc env bc/sso MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" +$ oc env bc/sso MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" buildconfig "sso" updated ---- . Verify the setting + +[subs="verbatim,macros,attributes"] ---- -oc env bc/sso --list +$ oc env bc/sso --list # buildconfigs sso MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/ ---- @@ -80,20 +83,23 @@ build configuration of the application as follows: . Identify the name of the build configuration to apply `MAVEN_MIRROR_URL` variable against: + +[subs="verbatim,macros,attributes"] ---- -oc get bc -o name +$ oc get bc -o name buildconfig/sso ---- . Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable + +[subs="verbatim,macros,attributes"] ---- -oc env bc/sso MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" +$ oc env bc/sso MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/" buildconfig "sso" updated ---- . Verify the setting + +[subs="verbatim,macros,attributes"] ---- -oc env bc/sso --list +$ oc env bc/sso --list # buildconfigs sso MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/ ---- @@ -473,7 +479,7 @@ if this environment variable is provided. |The password for the truststore and certificate. |=== -==== Template variables specific to *_sso72-mysql_*, *_sso72-mysql-persistent_*, and *_sso72-x509-mysql-persistent_* +==== Template variables specific to *_{project_templates_version}-mysql_*, *_{project_templates_version}-mysql-persistent_*, and *_{project_templates_version}-x509-mysql-persistent_* .Configuration Variables Specific To RH-SSO-enabled MySQL Applications With Ephemeral Or Persistent Storage [cols="2*", options="header"] @@ -507,7 +513,7 @@ broken. |The maximum permitted number of simultaneous client connections. |=== -==== Template variables specific to *_sso72-postgresql_*, *_sso72-postgresql-persistent_*, and *_sso72-x509-postgresql-persistent_* +==== Template variables specific to *_{project_templates_version}-postgresql_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-postgresql-persistent_* .Configuration Variables Specific To RH-SSO-enabled PostgreSQL Applications With Ephemeral Or Persistent Storage [cols="2*", options="header"] @@ -532,7 +538,7 @@ number of prepared transactions. |Configures how much memory is dedicated to PostgreSQL for caching data. |=== -==== Template variables specific to *_sso72-mysql-persistent_*, *_sso72-x509-mysql-persistent_*, *_sso72-postgresql-persistent_*, and *_sso72-x509-postgresql-persistent_* +==== Template variables specific to *_{project_templates_version}-mysql-persistent_*, *_{project_templates_version}-x509-mysql-persistent_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-postgresql-persistent_* .Configuration Variables Specific To RH-SSO-enabled MySQL / PostgreSQL Applications With Persistent Storage [cols="2*", options="header"] @@ -651,7 +657,7 @@ is provided. |*_SSO_USERNAME_* |The username used to access the RH-SSO service. This is used to create the application client(s) within the specified RH-SSO realm. This should match the -*_SSO_SERVICE_USERNAME_* specified through one of the *sso72-* templates. +*_SSO_SERVICE_USERNAME_* specified through one of the *{project_templates_version}-* templates. |*_SSO_PASSWORD_* |The password for the RH-SSO service user. diff --git a/openshift/topics/tutorials.adoc b/openshift/topics/tutorials.adoc index be7e117ac7..489b9252ce 100644 --- a/openshift/topics/tutorials.adoc +++ b/openshift/topics/tutorials.adoc @@ -21,12 +21,12 @@ The following example uses both link:https://github.com/keycloak/keycloak-quicks ==== This guide assumes the {project_openshift_product_name} image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:] -* *_sso72-mysql_* -* *_sso72-mysql-persistent_* -* *_sso72-postgresql_* -* *_sso72-postgresql-persistent_* -* *_sso72-x509-mysql-persistent_* -* *_sso72-x509-postgresql-persistent_* +* *_{project_templates_version}-mysql_* +* *_{project_templates_version}-mysql-persistent_* +* *_{project_templates_version}-postgresql_* +* *_{project_templates_version}-postgresql-persistent_* +* *_{project_templates_version}-x509-mysql-persistent_* +* *_{project_templates_version}-x509-postgresql-persistent_* ==== ===== Create RH-SSO Realm, Roles, and User for the EAP 6.4 / 7.0 JSP Application @@ -79,6 +79,7 @@ Use the following steps to automatically migrate the database schema: . Identify existing deployment config for RH-SSO 7.1 containers. + +[subs="verbatim,macros,attributes"] ---- $ oc get dc -o name --selector=application=sso deploymentconfig/sso @@ -86,30 +87,35 @@ deploymentconfig/sso-postgresql ---- . Stop all RH-SSO 7.1 containers in the current namespace. + +[subs="verbatim,macros,attributes"] ---- $ oc scale --replicas=0 dc/sso deploymentconfig "sso" scaled ---- . Update the image change trigger in the existing deployment config to reference the RH-SSO 7.2 image. + +[subs="verbatim,macros,attributes"] ---- -$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-sso72-openshift:1.1"}]' +$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-{project_templates_version}-openshift:{project_latest_image_tag}"}]' "sso" patched ---- . Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers. + +[subs="verbatim,macros,attributes"] ---- $ oc rollout latest dc/sso deploymentconfig "sso" rolled out ---- . Deploy RH-SSO 7.2 containers using the modified deployment config. + +[subs="verbatim,macros,attributes"] ---- $ oc scale --replicas=1 dc/sso deploymentconfig "sso" scaled ---- . (Optional) Verify the database has been successfully updated. + +[subs="verbatim,macros,attributes"] ---- $ oc get pods --selector=application=sso NAME READY STATUS RESTARTS AGE @@ -117,6 +123,7 @@ sso-4-vg21r 1/1 Running 0 1h sso-postgresql-1-t871r 1/1 Running 0 2h ---- + +[subs="verbatim,macros,attributes"] ---- $ oc logs sso-4-vg21r | grep 'Updating' 11:23:45,160 INFO [org.keycloak.connections.jpa.updater.liquibase.LiquibaseJpaUpdaterProvider] (ServerService Thread Pool -- 58) Updating database. Using changelog META-INF/jpa-changelog-master.xml @@ -142,118 +149,153 @@ The database migration process handles the data schema update and performs manip 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_* -* *_sso71-mysql-persistent_* -* *_sso71-postgresql-persistent_* +* *_{project_previous_templates_version}-mysql_* +* *_{project_previous_templates_version}-mysql-persistent_* +* *_{project_previous_templates_version}-postgresql_* +* *_{project_previous_templates_version}-postgresql-persistent_* +* *_{project_previous_templates_version}-x509-mysql-persistent_* +* *_{project_previous_templates_version}-x509-postgresql-persistent_* Perform the following to generate and get the SQL migration file for the database: . Prepare template of OpenShift link:https://docs.openshift.com/container-platform/latest/dev_guide/jobs.html[database migration job] to generate the SQL file. + +[source,yaml,subs="verbatim,macros,attributes"] ---- -$ cat sso71-to-sso72-db-migrate-job.yaml.orig +$ cat {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml.orig apiVersion: batch/v1 kind: Job metadata: - name: sso71-to-sso72-db-migrate-job + name: {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job spec: autoSelector: true parallelism: 0 completions: 1 template: metadata: - name: sso71-to-sso72-db-migrate-job + name: {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job spec: containers: - env: - name: DB_SERVICE_PREFIX_MAPPING - value: <> - - name: <>_JNDI - value: <> - - name: <>_USERNAME - value: <> - - name: <>_PASSWORD - value: <> - - name: <>_DATABASE - value: <> + value: pass:[<<DB_SERVICE_PREFIX_MAPPING_VALUE>>] + - name: pass:[<<PREFIX>>]_JNDI + value: pass:[<<PREFIX_JNDI_VALUE>>] + - name: pass:[<<PREFIX>>]_USERNAME + value: pass:[<<PREFIX_USERNAME_VALUE>>] + - name: pass:[<<PREFIX>>]_PASSWORD + value: pass:[<<PREFIX_PASSWORD_VALUE>>] + - name: pass:[<<PREFIX>>]_DATABASE + value: pass:[<<PREFIX_DATABASE_VALUE>>] - name: TX_DATABASE_PREFIX_MAPPING - value: <> - - name: <> - value: <> - - name: <> - value: <> - image: <> + value: pass:[<<TX_DATABASE_PREFIX_MAPPING_VALUE>>] + - name: pass:[<<SERVICE_HOST>>] + value: pass:[<<SERVICE_HOST_VALUE>>] + - name: pass:[<<SERVICE_PORT>>] + value: pass:[<<SERVICE_PORT_VALUE>>] + image: pass:[<<SSO_IMAGE_VALUE>>] imagePullPolicy: Always - name: sso71-to-sso72-db-migrate-job - # Keep the pod running after SQL migration file has been generated, - # so we can retrieve it - command: ["/bin/bash", "-c", "/opt/eap/bin/openshift-launch.sh || sleep 600"] + name: {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job + # Keep the pod running after the SQL migration + # file was generated, so we can retrieve it + command: + - "/bin/bash" + - "-c" + - "/opt/eap/bin/openshift-launch.sh || sleep 600" restartPolicy: Never ---- + +[subs="verbatim,macros,attributes"] ---- -$ cp sso71-to-sso72-db-migrate-job.yaml.orig sso71-to-sso72-db-migrate-job.yaml +$ cp {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml.orig \ + {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml ---- . Copy the datasource definition and database access credentials from RH-SSO 7.1 deployment config to appropriate places in database job migration template. + -Use the following script to copy `DB_SERVICE_PREFIX_MAPPING` and `TX_DATABASE_PREFIX_MAPPING` variable values, together with values of environment variables specific to particular datasource (`_JNDI`, `_USERNAME`, `_PASSWORD`, and `_DATABASE`) from the deployment config named `sso` to the database job migration template named `sso71-to-sso72-db-migrate-job.yaml`. +Use the following script to copy `DB_SERVICE_PREFIX_MAPPING` and `TX_DATABASE_PREFIX_MAPPING` variable values, together with values of environment variables specific to particular datasource (`_JNDI`, `_USERNAME`, `_PASSWORD`, and `_DATABASE`) from the deployment config named `sso` to the database job migration template named `{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml`. + [NOTE] ==== Although the `DB_SERVICE_PREFIX_MAPPING` environment variable allows a link:https://access.redhat.com/documentation/en-us/red_hat_jboss_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. ==== + +[source,bash,subs="verbatim,macros,attributes"] ---- $ cat mirror_sso_dc_db_vars.sh #!/bin/bash # IMPORTANT: # -# If the name of the SSO deployment config differs from 'sso' or if the file name of the -# YAML definition of the migration job is different, update the following two variables +# If the name of the SSO deployment config differs from 'sso' +# or if the file name of the YAML definition of the migration +# job is different, update the following two variables SSO_DC_NAME="sso" -JOB_MIGRATION_YAML="sso71-to-sso72-db-migrate-job.yaml" +JOB_MIGRATION_YAML="{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml" -# Get existing variables of the $SSO_DC_NAME deployment config in an array -declare -a SSO_DC_VARS=($(oc set env dc/${SSO_DC_NAME} --list | sed '/^#/d')) +# Get existing variables of the $SSO_DC_NAME deployment config +# in an array +declare -a SSO_DC_VARS=( \ + $(oc set env dc/${SSO_DC_NAME} --list \ + | sed '/^#/d') \ +) # Get the PREFIX used in the names of environment variables -PREFIX=$(grep -oP 'DB_SERVICE_PREFIX_MAPPING=[^ ]+' <<< "${SSO_DC_VARS[@]}") +PREFIX=$( \ + grep -oP 'DB_SERVICE_PREFIX_MAPPING=\[^ ]++' \ + <<< "${SSO_DC_VARS[@]}" \ +) PREFIX=${PREFIX##*=} -# Substitute (the order in which replacements are made is important): +# Substitute: # * <> with actual $PREFIX value and # * <>#${PREFIX}#g" ${JOB_MIGRATION_YAML} sed -i "s#<>_SERVICE_HOST and -# <>_SERVICE_PORT variables, add them to the datasource array. -# Their values also need to be propagated into yaml definition of the migration job. -if grep -Pq "${SERVICE}_SERVICE_HOST=[^ ]+" <<< "${SSO_DC_VARS[@]}" && - grep -Pq "${SERVICE}_SERVICE_PORT=[^ ]+" <<< "${SSO_DC_VARS[@]}" +# If the deployment config contains pass:[<<SERVICE>>]_SERVICE_HOST +# and pass:[<<SERVICE>>]_SERVICE_PORT variables, add them to the +# datasource array. Their values also need to be propagated into +# yaml definition of the migration job. +HOST_PATTERN="${SERVICE}_SERVICE_HOST=\[^ ]+" +PORT_PATTERN="${SERVICE}_SERVICE_PORT=[^ ]+" +if + grep -Pq "${HOST_PATTERN}" <<< "${SSO_DC_VARS[@]}" && + grep -Pq "${PORT_PATTERN}" <<< "${SSO_DC_VARS[@]}" then - DB_VARS=( "${DB_VARS[@]}" ${SERVICE}_SERVICE_HOST ${SERVICE}_SERVICE_PORT ) -# If they are not defined, delete their placeholder rows in yaml definition file -# (since if not defined they are not expanded which make the yaml definition invalid). + DB_VARS=( \ + "${DB_VARS[@]}" \ + "${SERVICE}_SERVICE_HOST" \ + "${SERVICE}_SERVICE_PORT" \ + ) +# If they are not defined, delete their placeholder rows in +# yaml definition file (since if not defined they are not +# expanded which make the yaml definition invalid). else for KEY in "HOST" "PORT" do @@ -261,19 +303,23 @@ else done fi -# Substitute (the order in which replacements are made is important): -# * <> with ${SERVICE}_SERVICE_HOST and -# * <> with "<<${SERVICE}_SERVICE_HOST_VALUE>>" +# Substitute: +# * pass:[<<SERVICE_HOST>>] with ${SERVICE}_SERVICE_HOST and +# * pass:[<<SERVICE_HOST_VALUE>>] with pass:[<<${SERVICE}_SERVICE_HOST_VALUE>>] +# The order in which replacements are made is important! # Do this for both "HOST" and "PORT" for KEY in "HOST" "PORT" do - sed -i "s#<>#${SERVICE}_SERVICE_${KEY}#g" ${JOB_MIGRATION_YAML} - sed -i "s#<>#<<${SERVICE}_SERVICE_${KEY}_VALUE>>#g" \ - ${JOB_MIGRATION_YAML} + PATTERN_1=pass:["<<SERVICE_${KEY}>>"] + REPL_1="${SERVICE}_SERVICE_${KEY}" + sed -i "s#${PATTERN_1}#${REPL_1}#g" ${JOB_MIGRATION_YAML} + PATTERN_2=pass:["<<SERVICE_${KEY}_VALUE>>"] + REPL_2="<<${SERVICE}_SERVICE_${KEY}_VALUE>>" + sed -i "s#${PATTERN_2}#${REPL_2}#g" ${JOB_MIGRATION_YAML} done -# Propagate the values of the datasource array items into yaml definition of the -# migration job +# Propagate the values of the datasource array items into +# yaml definition of the migration job for VAR in "${SSO_DC_VARS[@]}" do IFS=$'=' read KEY VALUE <<< $VAR @@ -289,14 +335,17 @@ do sed -i "s#<<${KEY}>>#${VALUE}#g" ${JOB_MIGRATION_YAML} fi # Verify that the value has been successfully propagated. - if grep -q '(JNDI|USERNAME|PASSWORD|DATABASE)' <<< "${KEY}" && - grep -q "<>" ${JOB_MIGRATION_YAML} + if + grep -q '(JNDI|USERNAME|PASSWORD|DATABASE)' <<< "${KEY}" && + pass:[grep -q "<<PREFIX${KEY#${PREFIX}}"] ${JOB_MIGRATION_YAML} || + grep -q "<<${KEY}>>" ${JOB_MIGRATION_YAML} then echo "Failed to update value of ${KEY%_VALUE}! Aborting." exit 1 else - printf '%-60s%-40s\n' "Successfully updated ${KEY%_VALUE} to:" "$VALUE" + printf '%-60s%-40s\n' \ + "Successfully updated ${KEY%_VALUE} to:" \ + "$VALUE" fi fi done @@ -305,6 +354,7 @@ done [[get-db-credentials]] Run the script. + +[subs="verbatim,macros,attributes"] ---- $ chmod +x ./mirror_sso_dc_db_vars.sh $ ./mirror_sso_dc_db_vars.sh @@ -317,14 +367,16 @@ Successfully updated TX_DATABASE_PREFIX_MAPPING to: sso-postgresql=DB ---- . Build the RH-SSO 7.2 database migration image using the link:https://github.com/iankko/openshift-examples/tree/sso_manual_db_migration[pre-configured source] and wait for the build to finish. + +[subs="verbatim,macros,attributes"] ---- -$ oc get is -n openshift | grep sso72 | cut -d ' ' -f1 -redhat-sso72-openshift +$ oc get is -n openshift | grep {project_templates_version} | cut -d ' ' -f1 +redhat-{project_templates_version}-openshift ---- + +[subs="verbatim,macros,attributes"] ---- -$ oc new-build redhat-sso72-openshift:1.1~https://github.com/jboss-openshift/openshift-examples --context-dir=sso-manual-db-migration --name=sso72-db-migration-image ---> Found image bf45ac2 (7 days old) in image stream "openshift/redhat-sso72-openshift" under tag "1.1" for "redhat-sso72-openshift:1.1" +$ oc new-build redhat-{project_templates_version}-openshift:{project_latest_image_tag}~https://github.com/jboss-openshift/openshift-examples --context-dir=sso-manual-db-migration --name={project_templates_version}-db-migration-image +--> Found image bf45ac2 (7 days old) in image stream "openshift/redhat-{project_templates_version}-openshift" under tag "{project_latest_image_tag}" for "redhat-{project_templates_version}-openshift:{project_latest_image_tag}" Red Hat SSO 7.2 --------------- @@ -333,40 +385,44 @@ $ oc new-build redhat-sso72-openshift:1.1~https://github.com/jboss-openshift/ope Tags: sso, sso7, keycloak * A source build using source code from https://github.com/jboss-openshift/openshift-examples will be created - * The resulting image will be pushed to image stream "sso72-db-migration-image:latest" + * The resulting image will be pushed to image stream "{project_templates_version}-db-migration-image:latest" * Use 'start-build' to trigger a new build ---> Creating resources with label build=sso72-db-migration-image ... - imagestream "sso72-db-migration-image" created - buildconfig "sso72-db-migration-image" created +--> Creating resources with label build={project_templates_version}-db-migration-image ... + imagestream "{project_templates_version}-db-migration-image" created + buildconfig "{project_templates_version}-db-migration-image" created --> Success - Build configuration "sso72-db-migration-image" created and build triggered. - Run 'oc logs -f bc/sso72-db-migration-image' to stream the build progress. + Build configuration "{project_templates_version}-db-migration-image" created and build triggered. + Run 'oc logs -f bc/{project_templates_version}-db-migration-image' to stream the build progress. ---- + +[subs="verbatim,macros,attributes"] ---- -$ oc logs -f bc/sso72-db-migration-image --follow +$ oc logs -f bc/{project_templates_version}-db-migration-image --follow Cloning "https://github.com/iankko/openshift-examples.git" ... ... Push successful ---- -. Update the template of the database migration job (`sso71-to-sso72-db-migrate-job.yaml`) with reference to the built `sso72-db-migration-image` image. +. Update the template of the database migration job (`{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml`) with reference to the built `{project_templates_version}-db-migration-image` image. .. Get the docker pull reference for the image. + +[subs="verbatim,macros,attributes"] ---- -$ PULL_REF=$(oc get istag -n $(oc project -q) --no-headers | grep sso72-db-migration-image | tr -s ' ' | cut -d ' ' -f 2) +$ PULL_REF=$(oc get istag -n $(oc project -q) --no-headers | grep {project_templates_version}-db-migration-image | tr -s ' ' | cut -d ' ' -f 2) ---- -.. Replace the \<> field in the job template with the pull specification. +.. Replace the pass:[<<SSO_IMAGE_VALUE>>] field in the job template with the pull specification. + +[subs="verbatim,macros,attributes"] ---- -$ sed -i "s#<>#$PULL_REF#g" sso71-to-sso72-db-migrate-job.yaml +$ sed -i "s#pass:[<<SSO_IMAGE_VALUE>>]#$PULL_REF#g" {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml ---- .. Verify that the field is updated. . Instantiate database migration job from the job template. + +[subs="verbatim,macros,attributes"] ---- -$ oc create -f sso71-to-sso72-db-migrate-job.yaml -job "sso71-to-sso72-db-migrate-job" created +$ oc create -f {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml +job "{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job" created ---- + [IMPORTANT] @@ -376,6 +432,7 @@ The database migration process handles the data schema update and performs manip + . Identify existing deployment config for RH-SSO 7.1 containers. + +[subs="verbatim,macros,attributes"] ---- $ oc get dc -o name --selector=application=sso deploymentconfig/sso @@ -383,29 +440,33 @@ deploymentconfig/sso-postgresql ---- . Stop all RH-SSO 7.1 containers in the current namespace. + +[subs="verbatim,macros,attributes"] ---- $ oc scale --replicas=0 dc/sso deploymentconfig "sso" scaled ---- . Run the database migration job and wait for the pod to be running correctly. + +[subs="verbatim,macros,attributes"] ---- $ oc get jobs NAME DESIRED SUCCESSFUL AGE -sso71-to-sso72-db-migrate-job 1 0 3m +{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job 1 0 3m ---- + +[subs="verbatim,macros,attributes"] ---- -$ oc scale --replicas=1 job/sso71-to-sso72-db-migrate-job -job "sso71-to-sso72-db-migrate-job" scaled +$ oc scale --replicas=1 job/{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job +job "{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job" scaled ---- + +[subs="verbatim,macros,attributes"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE sso-postgresql-1-n5p16 1/1 Running 1 19h -sso71-to-sso72-db-migrate-job-b87bb 1/1 Running 0 1m -sso72-db-migration-image-1-build 0/1 Completed 0 27m +{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job-b87bb 1/1 Running 0 1m +{project_templates_version}-db-migration-image-1-build 0/1 Completed 0 27m ---- + [NOTE] @@ -414,9 +475,10 @@ By default, the database migration job terminates automatically after `600 secon ==== . Get the dynamically generated SQL database migration file from the pod. + +[subs="verbatim,macros,attributes"] ---- $ mkdir -p ./db-update -$ oc rsync sso71-to-sso72-db-migrate-job-b87bb:/opt/eap/keycloak-database-update.sql ./db-update +$ oc rsync {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job-b87bb:/opt/eap/keycloak-database-update.sql ./db-update receiving incremental file list keycloak-database-update.sql @@ -425,9 +487,10 @@ total size is 29,621 speedup is 1.00 ---- . Inspect the `keycloak-database-update.sql` file for changes to be performed within manual RH-SSO 7.2 database update. . Apply the database update manually. -* Run the following commands for *_sso71-postgresql_* and *_sso71-postgresql-persistent_* templates (PostgreSQL database): +* Run the following commands for *_{project_previous_templates_version}-postgresql_* and *_{project_previous_templates_version}-postgresql-persistent_* templates (PostgreSQL database): ... Copy the generated SQL migration file to the PostgreSQL pod. + +[subs="verbatim,macros,attributes"] ---- $ oc rsync --no-perms=true ./db-update/ sso-postgresql-1-n5p16:/tmp sending incremental file list @@ -437,12 +500,14 @@ total size is 26,333 speedup is 299.24 ---- ... Start a shell session to the PostgreSQL pod. + +[subs="verbatim,macros,attributes"] ---- $ oc rsh sso-postgresql-1-n5p16 sh-4.2$ ---- ... Use the `psql` tool to apply database update manually. + +[subs="verbatim,macros,attributes"] ---- sh-4.2$ alias psql="/opt/rh/rh-postgresql95/root/bin/psql" sh-4.2$ psql --version @@ -459,18 +524,20 @@ INSERT 0 1 Replace `_USERNAME` and `_DATABASE` with the actual database credentials retrieved xref:get-db-credentials[in previous section]. Also use value of `_PASSWORD` as the password for the database, when prompted. ==== ... Close the shell session to the PostgreSQL pod. Continue with xref:image-change-trigger-update-step[updating image change trigger step]. -* Run the following commands for *_sso71-mysql_* and *_sso71-mysql-persistent_* templates (MySQL database): +* Run the following commands for *_{project_previous_templates_version}-mysql_* and *_{project_previous_templates_version}-mysql-persistent_* templates (MySQL database): ... Given pod situation similar to the following: + +[subs="verbatim,macros,attributes"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE sso-mysql-1-zvhk3 1/1 Running 0 1h -sso71-to-sso72-db-migrate-job-m202t 1/1 Running 0 11m -sso72-db-migration-image-1-build 0/1 Completed 0 13m +{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job-m202t 1/1 Running 0 11m +{project_templates_version}-db-migration-image-1-build 0/1 Completed 0 13m ---- ... Copy the generated SQL migration file to the MySQL pod. + +[subs="verbatim,macros,attributes"] ---- $ oc rsync --no-perms=true ./db-update/ sso-mysql-1-zvhk3:/tmp sending incremental file list @@ -481,12 +548,14 @@ total size is 24,594 speedup is 0.99 ---- ... Start a shell session to the MySQL pod. + +[subs="verbatim,macros,attributes"] ---- $ oc rsh sso-mysql-1-zvhk3 sh-4.2$ ---- ... Use the `mysql` tool to apply database update manually. + +[subs="verbatim,macros,attributes"] ---- sh-4.2$ alias mysql="/opt/rh/rh-mysql57/root/bin/mysql" sh-4.2$ mysql --version @@ -507,18 +576,21 @@ Replace `_USERNAME` and `_DATABASE` with the actual database cre [start=12] . Update image change trigger in the existing deployment config of RH-SSO 7.1 to reference the RH-SSO 7.2 image. + +[subs="verbatim,macros,attributes"] ---- -$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-sso72-openshift:1.1"}]' +$ oc patch dc/sso --type=json -p '[{"op": "replace", "path": "/spec/triggers/0/imageChangeParams/from/name", "value": "redhat-{project_templates_version}-openshift:{project_latest_image_tag}"}]' "sso" patched ---- . Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers. + +[subs="verbatim,macros,attributes"] ---- $ oc rollout latest dc/sso deploymentconfig "sso" rolled out ---- . Deploy RH-SSO 7.2 containers using the modified deployment config. + +[subs="verbatim,macros,attributes"] ---- $ oc scale --replicas=1 dc/sso deploymentconfig "sso" scaled @@ -532,7 +604,7 @@ This tutorial focuses on migrating the Red Hat Single Sign-On server database fr . Log in to the OpenShift web console and select the _sso-app-demo_ project space. . Click *Add to project* to list the default image streams and templates. . Use the *Filter by keyword* search bar to limit the list to those that match _sso_. You may need to click *See all* to show the desired application template. -. Select *_sso72-mysql_* RH-SSO application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value). +. Select *_{project_templates_version}-mysql_* RH-SSO application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value). + [IMPORTANT] ==== @@ -568,6 +640,7 @@ Upon their creation xref:sso-export-the-database[the database can be exported.] . Get the RH-SSO deployment config and scale it down to zero. + +[subs="verbatim,macros,attributes"] ---- $ oc get dc -o name deploymentconfig/sso @@ -578,17 +651,20 @@ deploymentconfig "sso" scaled ---- . Instruct the RH-SSO 7.2 server deployed on {project_openshift_product_name} image to perform database export at RH-SSO server boot time. + +[subs="verbatim,macros,attributes"] ---- oc env dc/sso -e "JAVA_OPTS_APPEND=-Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=/tmp/demorealm-export.json" ---- . Scale the RH-SSO deployment config back up. This will start the RH-SSO server and export its database. + +[subs="verbatim,macros,attributes"] ---- $ oc scale --replicas=1 dc sso deploymentconfig "sso" scaled ---- . (Optional) Verify that the export was successful. + +[subs="verbatim,macros,attributes"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE @@ -604,6 +680,7 @@ $ oc logs sso-4-ejr0k | grep 'Export' . Retrieve the JSON file of the RH-SSO database from the pod. + +[subs="verbatim,macros,attributes"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE @@ -701,6 +778,7 @@ Log in to the OpenShift master CLI. You must have the required permissions to ed . Edit the */etc/origin/master/master-config.yaml* file and find the *identityProviders*. The OpenShift master, which was deployed using the OpenShift Primer, is configured with HTPassword and shows the following: + +[subs="verbatim,macros,attributes"] ---- identityProviders: - challenge: true @@ -714,7 +792,7 @@ identityProviders: + Add RH-SSO as a secondary identity provider with content similar to the following snippet: + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- - name: rh_sso challenge: false @@ -743,7 +821,7 @@ Add RH-SSO as a secondary identity provider with content similar to the followin .. The RH-SSO *Secret* hash for the *clientSecret* can be found in the RH-SSO web console: *Clients* -> *_openshift-demo_* -> *Credentials* .. The endpoints for the *urls* can be found by making a request with the RH-SSO application. For example: + -[subs="verbatim,macros"] +[subs="verbatim,macros,attributes"] ---- ---- @@ -753,6 +831,7 @@ The response includes the *authorization_endpoint*, *token_endpoint*, and *useri .. This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. For this reason, the *ca* is provided as . This CA certificate must also be copied into the */etc/origin/master* folder. This is not necessary if using a certificate purchased from a verified Certificate Authority. . Save the configuration and restart the OpenShift master: + +[subs="verbatim,macros,attributes"] ---- $ systemctl restart atomic-openshift-master ---- @@ -764,6 +843,7 @@ Navigate to the OpenShift web console, which in this example is _https://openshi Select *rh-sso* and log in to OpenShift with the _testuser_ user created earlier in RH-SSO. No projects are visible to _testuser_ until they are added in the OpenShift CLI. This is the only way to provide user privileges in OpenShift because it currently does not accept external role mapping. To provide _testuser_ `view` privileges for the _sso-app-demo_, use the OpenShift CLI: +[subs="verbatim,macros,attributes"] ---- $ oadm policy add-role-to-user view testuser -n sso-app-demo ---- @@ -782,16 +862,19 @@ Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. . Create a new project: + +[subs="verbatim,macros,attributes"] ---- $ oc new-project eap-app-demo ---- //. Create a service account to be used for the RH-SSO deployment: //+ +//[subs="verbatim,macros,attributes"] //---- //$ oc create serviceaccount eap-service-account //---- . Add the `view` role to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. This enables the service account to view all the resources in the `eap-app-demo` namespace, which is necessary for managing the cluster. + +[subs="verbatim,macros,attributes"] ---- $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default ---- @@ -799,22 +882,26 @@ $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default This example uses `keytool`, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. The following commands will prompt for passwords. + .. Generate a secure key for the SSL keystore: + +[subs="verbatim,macros,attributes"] ---- $ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks ---- .. Generate a secure key for the JGroups keystore: + +[subs="verbatim,macros,attributes"] ---- $ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks ---- . Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files: + +[subs="verbatim,macros,attributes"] ---- $ oc secret new eap-ssl-secret eapkeystore.jks $ oc secret new eap-jgroup-secret eapjgroups.jceks ---- . Add the EAP secret to the `default` service account: + +[subs="verbatim,macros,attributes"] ---- $ oc secrets link default eap-ssl-secret eap-jgroup-secret ---- @@ -1023,16 +1110,19 @@ Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. . Create a new project: + +[subs="verbatim,macros,attributes"] ---- $ oc new-project eap-app-demo ---- //. Create a service account to be used for the SSO deployment: //+ +//[subs="verbatim,macros,attributes"] //---- //$ oc create serviceaccount app-service-account //---- . Add the `view` role to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. This enables the service account to view all the resources in the `eap-app-demo` namespace, which is necessary for managing the cluster. + +[subs="verbatim,macros,attributes"] ---- $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default ---- @@ -1041,22 +1131,26 @@ $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default This example uses `keytool`, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. The following commands will prompt for passwords. + .. Generate a secure key for the SSL keystore: + +[subs="verbatim,macros,attributes"] ---- $ keytool -genkeypair -alias https -storetype JKS -keystore eapkeystore.jks ---- .. Generate a secure key for the JGroups keystore: + +[subs="verbatim,macros,attributes"] ---- $ keytool -genseckey -alias jgroups -storetype JCEKS -keystore eapjgroups.jceks ---- . Generate the EAP for OpenShift secrets with the SSL and JGroup keystore files: + +[subs="verbatim,macros,attributes"] ---- $ oc secret new eap-ssl-secret eapkeystore.jks $ oc secret new eap-jgroup-secret eapjgroups.jceks ---- . Add the EAP application secret to the EAP service account created earlier: + +[subs="verbatim,macros,attributes"] ---- $ oc secrets link default eap-ssl-secret eap-jgroup-secret ---- @@ -1071,6 +1165,7 @@ The *keycloak-saml-subsystem.xml*, exported from the RH-SSO client in a previous . Replace the *SPECIFY YOUR LOGOUT PAGE!* value of the *logout page* tag with the url to redirect users when they log out of the application. This example uses */index.jsp*. . Delete the ** and ** tags and keys and replace it with keystore information: + +[subs="verbatim,macros,attributes"] ---- ... @@ -1087,6 +1182,7 @@ The mount path of the *keystore-saml.jks* (in this example *_/etc/eap-secret-vol The aliases and passwords for the *PrivateKey* and the *Certificate* were configured when the SAML Keys were exported from the RH-SSO client. . Delete the second ** tag and key and replace it with the the realm certificate information: + +[subs="verbatim,macros,attributes"] ---- ... @@ -1107,6 +1203,7 @@ The certificate alias and password were configured when the SAML Keys were expor The client type must also be specified by the ** key in the application *web.xml*. This file is read by the image at deployment. Open the application *web.xml* file and ensure it includes the following: +[subs="verbatim,macros,attributes"] ---- ... diff --git a/topics/templates/document-attributes-product.adoc b/topics/templates/document-attributes-product.adoc index 73c9e4481e..5a0be72ea8 100644 --- a/topics/templates/document-attributes-product.adoc +++ b/topics/templates/document-attributes-product.adoc @@ -11,6 +11,9 @@ ifeval::[{project_product_cd}==false] :project_name_full: Red Hat Single Sign-On :project_version: 7.3.0.GA :project_versionDoc: 7.3 +:project_previous_templates_version: sso-cd +:project_templates_version: sso73 +:project_latest_image_tag: 1.0 :project_doc_base_url: https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/{project_versionDoc}/html-single :maven_repository: https://maven.repository.redhat.com/ga/ endif::[] @@ -19,6 +22,9 @@ ifeval::[{project_product_cd}==true] :project_name_full: Red Hat Single Sign-On Continuous Delivery :project_version: 7.3.0.CD05 :project_versionDoc: 7.3.0.cd05 +:project_previous_templates_version: sso72 +:project_templates_version: sso-cd +:project_latest_image_tag: 1.0 :project_doc_base_url: https://access.redhat.com/documentation/en-us/red_hat_single_sign-on_continuous_delivery/{project_versionDoc}/html-single :maven_repository: https://maven.repository.redhat.com/earlyaccess/ endif::[]