From 0661424bd3116bed279599e35a7d0d950fe1a616 Mon Sep 17 00:00:00 2001 From: Jan Lieskovsky Date: Mon, 21 Jan 2019 20:04:00 +0100 Subject: [PATCH] [KEYCLOAK-9361] Multiple changes: * Move 'Example Deploying SSO' back from Tutorials to Get Started section to: * Align with the form this section has in RH-SSO 7.2 image doc, * Bring the getting_started.adoc changes from this commit: https://github.com/keycloak/keycloak-documentation/commit/f61cfad51ef3e6370f47026612c5826d24234dd7#diff-74a6baa8904aeee687e9db2c263b9b47 back to the get_started.adoc file, which is now used instead of the getting_started.adoc one * Drop duplicate 'Accessing the Administrator Console' section from Advanced Concepts * Comment out the Keystores, Secrets sections in Get Started since it's covered in Advanced Concepts now Signed-off-by: Jan Lieskovsky --- openshift/topics/advanced_concepts.adoc | 39 +------- openshift/topics/before_you_begin.adoc | 2 +- openshift/topics/get_started.adoc | 124 +++++++++++++++++++++++- openshift/topics/tutorials.adoc | 23 ++--- 4 files changed, 133 insertions(+), 55 deletions(-) diff --git a/openshift/topics/advanced_concepts.adoc b/openshift/topics/advanced_concepts.adoc index 0a8adb003a..4ee9ff5c19 100644 --- a/openshift/topics/advanced_concepts.adoc +++ b/openshift/topics/advanced_concepts.adoc @@ -20,7 +20,7 @@ $ oc new-project sso-app-demo $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default ---- -[[advanced-concepts-Configuring-Keystores]] +[[Configuring-Keystores]] ==== Creating HTTPS and JGroups Keystores, and Truststore for the {project_name} Server The {project_name} application templates using xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] require: @@ -227,43 +227,6 @@ $ oc new-app --template={project_templates_version}-https \ Run 'oc status' to view your app. ---- -==== Accessing the Administrator Console of the {project_name} Pod - -After the template got deployed, identify the available routes: - -[source,bash,subs="attributes+,macros+"] ----- -$ oc get routes ----- - -[cols="7",options="header"] -|=== -|NAME |HOST/PORT |PATH |SERVICES |PORT |TERMINATION |WILDCARD - -|secure-sso -|secure-sso-sso-app-demo.openshift.example.com -| -|secure-sso -| -|passthrough -|None - -|sso -|sso-sso-app-demo.openshift.example.com -| -|sso -| -| -|None -|=== - -and access the {project_name} administrator console at: - -* *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin* -* *\http://sso-sso-app-demo.openshift.example.com/auth/admin* - -using the xref:sso-administrator-setup[administrator account]. - [[advanced-concepts-sso-hostname-spi-setup]] === Customizing Hostname for the {project_name} Server diff --git a/openshift/topics/before_you_begin.adoc b/openshift/topics/before_you_begin.adoc index f49ee42c11..23f5f7a20a 100644 --- a/openshift/topics/before_you_begin.adoc +++ b/openshift/topics/before_you_begin.adoc @@ -22,5 +22,5 @@ The Tutorials in this guide follow on from and assume an OpenShift instance simi [IMPORTANT] ==== -For information related to updating the existing database when migrating {project_openshift_product_name} image from previous versions to version {project_version}, see the xref:../tutorials/tutorials.adoc#upgrading-sso-db-from-previous-to-{project_version}[Updating Existing Database when Migrating {project_openshift_product_name} Image to a new version] section. +For information related to updating the existing database when migrating {project_openshift_product_name} image from previous versions to version {project_version}, see the xref:upgrading-sso-db-from-previous-version[Updating Existing Database when Migrating {project_openshift_product_name} Image to a new version] section. ==== diff --git a/openshift/topics/get_started.adoc b/openshift/topics/get_started.adoc index 1b3b717dfe..03163f4fdd 100644 --- a/openshift/topics/get_started.adoc +++ b/openshift/topics/get_started.adoc @@ -53,6 +53,123 @@ done $ oc -n openshift import-image redhat-{project_templates_version}-openshift:{project_latest_image_tag} ---- +[[Example-Deploying-SSO]] +=== Deploying the {project_name} Image +[[Preparing-SSO-Authentication-for-OpenShift-Deployment]] +==== Preparing the Deployment +Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. + +. Create a new project: ++ +[source,bash,subs="attributes+,macros+"] +---- +$ oc new-project 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. ++ +[source,bash,subs="attributes+,macros+"] +---- +$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default +---- + +==== Deploying the {project_name} Image using Application Template + +===== Deploying the Template via OpenShift CLI + +. List the available {project_name} application templates: ++ +[source,bash,subs="attributes+,macros+"] +---- +$ oc get templates -n openshift -o name | grep -o '{project_templates_version}.\+' +{project_templates_version}-https +{project_templates_version}-mysql +{project_templates_version}-mysql-persistent +{project_templates_version}-postgresql +{project_templates_version}-postgresql-persistent +{project_templates_version}-x509-https +{project_templates_version}-x509-mysql-persistent +{project_templates_version}-x509-postgresql-persistent +---- +. Deploy the selected one: ++ +[source,bash,subs="attributes+,macros+"] +---- +$ oc new-app --template={project_templates_version}-x509-https +--> Deploying template "openshift/{project_templates_version}-x509-https" to project sso-app-demo + + {project_name} {project_versionDoc} (Ephemeral) + --------- + An example {project_name} 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates. + + A new {project_name} service has been created in your project. The admin username/password for accessing the master realm via the {project_name} console is IACfQO8v/nR7llVSVb4Dye3TNRbXoXhRpAKTmiCRc. The HTTPS keystore used for serving secure content, the JGroups keystore used for securing JGroups communications, and server truststore used for securing {project_name} requests were automatically created via OpenShift's service serving x509 certificate secrets. + + * With parameters: + * Application Name=sso + * JGroups Cluster Password=jg0Rssom0gmHBnooDF3Ww7V4Mu5RymmB # generated + * Datasource Minimum Pool Size= + * Datasource Maximum Pool Size= + * Datasource Transaction Isolation= + * ImageStream Namespace=openshift + * {project_name} Administrator Username=IACfQO8v # generated + * {project_name} Administrator Password=nR7llVSVb4Dye3TNRbXoXhRpAKTmiCRc # generated + * {project_name} Realm= + * {project_name} Service Username= + * {project_name} Service Password= + * Container Memory Limit=1Gi + +--> Creating resources ... + service "sso" created + service "secure-sso" created + service "sso-ping" created + route "sso" created + route "secure-sso" created + deploymentconfig "sso" created +--> Success + Run 'oc status' to view your app. +---- + +===== Deploying the Template via OpenShift Web Console + +Alternatively, perform the following steps to deploy the {project_name} template via OpenShift web console: + +. Log in to the OpenShift web console and select the _sso-app-demo_ project space. +. Click *Add to Project*, then *Browse Catalog* to list the default image streams and templates. +. Use the *Filter by Keyword* search bar to limit the list to those that match _sso_. You may need to click *Middleware*, then *Integration* to show the desired application template. +. Select an {project_name} application template. This example uses *_{project_name} {project_versionDoc} (Ephemeral)_*. +. Click *Next* in the *Information* step. +. From the *Add to Project* drop-down menu, select the _sso-app-demo_ project space. Then click *Next*. +. Select *Do not bind at this time* radio button in the *Binding* step. Click *Create* to continue. +. In the *Results* step, click the *Continue to the project overview* link to verify the status of the deployment. + +==== Accessing the Administrator Console of the {project_name} Pod + +After the template got deployed, identify the available routes: + +[source,bash,subs="attributes+,macros+"] +---- +$ oc get routes +---- + +[cols="7",options="header"] +|=== +|NAME |HOST/PORT |PATH |SERVICES |PORT |TERMINATION |WILDCARD + +|sso +|sso-sso-app-demo.openshift.example.com +| +|sso +| +|reencrypt +|None +|=== + +and access the {project_name} administrator console at: + +* *\https://sso-sso-app-demo.openshift.example.com/auth/admin* + +using the xref:sso-administrator-setup[administrator account]. + +//// === Preparing and Deploying the {project_openshift_product_name} Application Templates [[Configuring-Keystores]] @@ -81,6 +198,7 @@ Use the SSL and JGroups keystore files to create secrets for the project: $ oc secret new $ oc secret new ---- +//// //// ==== Creating the Service Account @@ -107,7 +225,6 @@ $ oc policy add-role-to-user view system:serviceaccount: ---- -//// ==== Using the OpenShift Web Console Log in to the OpenShift web console: @@ -175,6 +292,8 @@ The {project_openshift_product_name} templates use TLS passthrough termination f 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. +//// + === 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. @@ -281,7 +400,8 @@ $ oc new-project eap-app-demo + [source,bash,subs="attributes+,macros+"] ---- -$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default +$ 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). diff --git a/openshift/topics/tutorials.adoc b/openshift/topics/tutorials.adoc index cf8bfde4e2..a135f7de1f 100644 --- a/openshift/topics/tutorials.adoc +++ b/openshift/topics/tutorials.adoc @@ -1,14 +1,7 @@ +//// [[{project_name}-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 {project_openshift_product_name} image -[[Preparing-SSO-Authentication-for-OpenShift-Deployment]] -==== Preparing {project_name} 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.1 JSP Service Invocation Application and Secure it Using Red Hat Single Sign-On @@ -43,9 +36,11 @@ Use the xref:sso-administrator-setup[credentials of the {project_name} administr . 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*. +//// +== Tutorials -[[upgrading-sso-db-from-previous-to-{project_version}]] +[[upgrading-sso-db-from-previous-version]] === Example Workflow: Updating Existing Database when Migrating {project_openshift_product_name} Image to a new version [IMPORTANT] ==== @@ -586,10 +581,10 @@ $ oc scale --replicas=1 dc/sso deploymentconfig "sso" scaled ---- -=== Example Workflow: Migrating Entire {project_name} Server Database Across The Environments +==== Migrating The Entire {project_name} Server Database Across The Environments This tutorial focuses on migrating the Red Hat Single Sign-On server database from one environment to another or migrating to a different database. It assumes steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already. -==== Deploying the {project_name} MySQL Application Template +===== Deploying the {project_name} MySQL Application Template . Log in to the OpenShift web console and select the _sso-app-demo_ project space. . Click *Add to project* to list the default image streams and templates. @@ -616,7 +611,7 @@ This example workflow uses a self-generated CA to provide an end-to-end workflow For production environments, Red Hat recommends that you use an SSL certificate purchased from a verified Certificate Authority. ==== -==== (Optional) Creating additional {project_name} link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported +===== (Optional) Creating additional {project_name} link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported When performing link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[{project_name} {project_version} server database export] only {project_name} realms and users currently present in the database will be exported. If the exported JSON file should include also additional {project_name} realms and users, these need to be created first: @@ -626,7 +621,7 @@ When performing link:https://access.redhat.com/documentation/en-us/red_hat_singl Upon their creation xref:sso-export-the-database[the database can be exported.] [[sso-export-the-database]] -==== Export the {project_name} database as a JSON file on the OpenShift pod +===== Export the {project_name} database as a JSON file on the OpenShift pod . Get the {project_name} deployment config and scale it down to zero. + @@ -670,7 +665,7 @@ $ oc logs sso-4-ejr0k | grep 'Export' 09:24:59,998 INFO [org.keycloak.services] (ServerService Thread Pool -- 57) KC-SERVICES0035: Export finished successfully ---- -==== Retrieve and import the exported JSON file +===== Retrieve and import the exported JSON file . Retrieve the JSON file of the {project_name} database from the pod. +