libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

[KEYCLOAK-8234] Replace various fixed versioned strings

Browse source 
with their parametrized version

Also drop mention about EAP 7.0 images / templates, since
these are deprecated (see CLOUD-2699 / CLOUD-2678 for details)

Signed-off-by: Jan Lieskovsky <jlieskov@redhat.com>
This commit is contained in:
Jan Lieskovsky 2018-10-12 20:18:28 +02:00 committed by Stian Thorgersen
parent 389a22cc79
commit fe14ea90cc
7 changed files with 335 additions and 342 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

142
openshift/topics/advanced_concepts.adoc
View file

@ -1,8 +1,8 @@
== Advanced Concepts == Advanced Concepts
These cover additional configuration topics, such as seting up keystores and a truststore for the RH-SSO server, creating an administrator account, an overview of available RH-SSO client registration methods, and guidance on configuring clustering. These cover additional configuration topics, such as seting up keystores and a truststore for the {project_name_abbr} server, creating an administrator account, an overview of available {project_name_abbr} client registration methods, and guidance on configuring clustering.
=== Requirements and Deploying xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination] RH-SSO Templates === Requirements and Deploying xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination] {project_name_abbr} Templates
==== Preparing the Deployment ==== Preparing the Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
@ -21,22 +21,22 @@ $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
---- ----
[[advanced-concepts-Configuring-Keystores]] [[advanced-concepts-Configuring-Keystores]]
==== Creating HTTPS and JGroups Keystores, and Truststore for the RH-SSO Server ==== Creating HTTPS and JGroups Keystores, and Truststore for the {project_name_abbr} Server
The RH-SSO application templates using xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] require: The {project_name_abbr} application templates using xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] require:
* An xref:create-https-keystore[HTTPS keystore] used for encryption of https traffic, * An xref:create-https-keystore[HTTPS keystore] used for encryption of https traffic,
* The xref:create-jgroups-keystore[JGroups keystore] used for encryption of JGroups communications between nodes in the cluster, and * The xref:create-jgroups-keystore[JGroups keystore] used for encryption of JGroups communications between nodes in the cluster, and
* xref:create-server-truststore[RH-SSO server truststore] used for securing the RH-SSO requests * xref:create-server-truststore[{project_name_abbr} server truststore] used for securing the {project_name_abbr} requests
the {project_openshift_product_name} image to be deployed properly. the {project_openshift_product_name} image to be deployed properly.
[IMPORTANT] [IMPORTANT]
==== ====
The RH-SSO application templates using xref:../introduction/introduction.adoc#reencrypt-templates[re-encryption TLS termination] do not *require* or *expect* the aforementioned HTTPS and JGroups keystores and RH-SSO server truststore to be prepared beforehand. The templates use 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 and JGroups keystores. 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 create these cluster certificates. 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. The {project_name_abbr} application templates using xref:../introduction/introduction.adoc#reencrypt-templates[re-encryption TLS termination] do not *require* or *expect* the aforementioned HTTPS and JGroups keystores and {project_name_abbr} server truststore to be prepared beforehand. The templates use 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 and JGroups keystores. The {project_name_abbr} server truststore is also created automatically, containing the */var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt* CA certificate file, which is used to create these cluster certificates. Moreover, the truststore for the {project_name_abbr} server is pre-populated with the all known, trusted CA certificate files found in the Java system path.
==== ====
The *_openssl_* toolkit is used in the following example to generate a CA certificate to sign the HTTPS keystore, and create a truststore for the RH-SSO server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores. The *_openssl_* toolkit is used in the following example to generate a CA certificate to sign the HTTPS keystore, and create a truststore for the {project_name_abbr} server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores.
[WARNING] [WARNING]
==== ====
@ -100,7 +100,7 @@ $ keytool -genseckey -alias secret-key -storetype JCEKS -keystore jgroups.jceks
---- ----
[[create-server-truststore]] [[create-server-truststore]]
*_Import the CA certificate into a new RH-SSO server truststore:_* *_Import the CA certificate into a new {project_name_abbr} server truststore:_*
Provide `mykeystorepass` as the truststore password. Reply `yes` to `Trust this certificate? [no]:` question: Provide `mykeystorepass` as the truststore password. Reply `yes` to `Trust this certificate? [no]:` question:
@ -114,28 +114,28 @@ $ keytool -import -file xpaas.crt -alias xpaas.ca -keystore truststore.jks
OpenShift uses objects called link:https://docs.openshift.com/container-platform/latest/dev_guide/secrets.html[secrets] to hold sensitive information, such as passwords or keystores. OpenShift uses objects called link:https://docs.openshift.com/container-platform/latest/dev_guide/secrets.html[secrets] to hold sensitive information, such as passwords or keystores.
. Create the secrets for the HTTPS and JGroups keystores, and RH-SSO server truststore, generated in the xref:Configuring-Keystores[previous section]. . Create the secrets for the HTTPS and JGroups keystores, and {project_name_abbr} server truststore, generated in the xref:Configuring-Keystores[previous section].
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc secret new sso-app-secret keystore.jks jgroups.jceks truststore.jks $ 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. . 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 {project_name_abbr} pods.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc secrets link default sso-app-secret $ oc secrets link default sso-app-secret
---- ----
==== Deploying the Chosen RH-SSO Passthrough TLS Template via OpenShift CLI ==== Deploying the Chosen {project_name_abbr} Passthrough TLS Template via OpenShift CLI
After the aforementioned xref:Configuring-Keystores[keystores] and xref:Configuring-Secrets[secrets] are created, deploy some of the available xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] as follows: After the aforementioned xref:Configuring-Keystores[keystores] and xref:Configuring-Secrets[secrets] are created, deploy some of the available xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] as follows:
[WARNING] [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-{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 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_* {project_name_abbr} 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. 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 {project_name_abbr} server, and passwords for the HTTPS and JGroups keystores, and the truststore of the {project_name_abbr} 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-{project_templates_version}-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.
==== ====
@ -182,11 +182,11 @@ $ oc new-app --template={project_templates_version}-https \
-p SSO_TRUSTSTORE_SECRET="sso-app-secret" -p SSO_TRUSTSTORE_SECRET="sso-app-secret"
--> Deploying template "openshift/{project_templates_version}-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) {project_name} {project_version} (Ephemeral with passthrough TLS)
--------- ---------
An example RH-SSO 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates. An example {project_name_abbr} 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates.
A new RH-SSO service has been created in your project. The admin username/password for accessing the master realm via the RH-SSO console is admin/redhat. Please be sure to create the following secrets: "sso-app-secret" containing the keystore.jks file used for serving secure content; "sso-app-secret" containing the jgroups.jceks file used for securing JGroups communications; "sso-app-secret" containing the truststore.jks file used for securing RH-SSO requests. A new {project_name_abbr} service has been created in your project. The admin username/password for accessing the master realm via the {project_name_abbr} console is admin/redhat. Please be sure to create the following secrets: "sso-app-secret" containing the keystore.jks file used for serving secure content; "sso-app-secret" containing the jgroups.jceks file used for securing JGroups communications; "sso-app-secret" containing the truststore.jks file used for securing {project_name_abbr} requests.
* With parameters: * With parameters:
* Application Name=sso * Application Name=sso
@ -206,14 +206,14 @@ $ oc new-app --template={project_templates_version}-https \
* JGroups Keystore Password=password * JGroups Keystore Password=password
* JGroups Cluster Password=yeSppLfp # generated * JGroups Cluster Password=yeSppLfp # generated
* ImageStream Namespace=openshift * ImageStream Namespace=openshift
* RH-SSO Administrator Username=admin * {project_name_abbr} Administrator Username=admin
* RH-SSO Administrator Password=redhat * {project_name_abbr} Administrator Password=redhat
* RH-SSO Realm=demorealm * {project_name_abbr} Realm=demorealm
* RH-SSO Service Username= * {project_name_abbr} Service Username=
* RH-SSO Service Password= * {project_name_abbr} Service Password=
* RH-SSO Trust Store=truststore.jks * {project_name_abbr} Trust Store=truststore.jks
* RH-SSO Trust Store Password=mykeystorepass * {project_name_abbr} Trust Store Password=mykeystorepass
* RH-SSO Trust Store Secret=sso-app-secret * {project_name_abbr} Trust Store Secret=sso-app-secret
* Container Memory Limit=1Gi * Container Memory Limit=1Gi
--> Creating resources ... --> Creating resources ...
@ -227,7 +227,7 @@ $ oc new-app --template={project_templates_version}-https \
Run 'oc status' to view your app. Run 'oc status' to view your app.
---- ----
==== Accessing the Administrator Console of the RH-SSO Pod ==== Accessing the Administrator Console of the {project_name_abbr} Pod
After the template got deployed, identify the available routes: After the template got deployed, identify the available routes:
@ -257,7 +257,7 @@ $ oc get routes
|None |None
|=== |===
and access the RH-SSO administrator console at: and access the {project_name_abbr} administrator console at:
* *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin* * *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
* *\http://sso-sso-app-demo.openshift.example.com/auth/admin* * *\http://sso-sso-app-demo.openshift.example.com/auth/admin*
@ -325,8 +325,8 @@ Red Hat Single Sign-On does not provide any pre-configured management account ou
The administrator account can be created: 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 providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the {project_name_abbr} application template, or
* By xref:sso-admin-remote-shell[a remote shell session to particular RH-SSO pod], if the {project_openshift_product_name} image is deployed without an application template. * By xref:sso-admin-remote-shell[a remote shell session to particular {project_name_abbr} pod], if the {project_openshift_product_name} image is deployed without an application template.
[NOTE] [NOTE]
==== ====
@ -334,9 +334,9 @@ Red Hat Single Sign-On allows an initial administrator account to be created via
==== ====
[[advanced-concepts-sso-admin-template-parameters]] [[advanced-concepts-sso-admin-template-parameters]]
==== Creating RH-SSO Administrator Account via Template Parameters ==== Creating {project_name_abbr} 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. When deploying {project_name_abbr} application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the {project_name_abbr} server's administrator account to be created for the `master` realm.
[NOTE] [NOTE]
==== ====
@ -345,25 +345,25 @@ When deploying RH-SSO application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADM
[IMPORTANT] [IMPORTANT]
==== ====
The lifespan of the RH-SSO server's administrator account depends upon the storage type used to store the RH-SSO server's database: The lifespan of the {project_name_abbr} server's administrator account depends upon the storage type used to store the {project_name_abbr} server's database:
* 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 in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates) the account exists throughout the lifecycle of the particular {project_name_abbr} 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 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 {project_name_abbr} 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. * 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 {project_name_abbr} 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). It is a common practice to deploy an {project_name_abbr} application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new {project_name_abbr} application needs to be instantiated).
==== ====
[WARNING] [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. 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 {project_name_abbr} applications.
==== ====
[IMPORTANT] [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: Run the following commands to prepare the previously created deployment config of the {project_name_abbr} application for reuse after the administrator account has been created:
. Identify the deployment config of the RH-SSO application. . Identify the deployment config of the {project_name_abbr} application.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -380,11 +380,11 @@ $ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD=""
==== ====
[[advanced-concepts-sso-admin-remote-shell]] [[advanced-concepts-sso-admin-remote-shell]]
==== Creating RH-SSO Administrator Account via Remote Shell Session to RH-SSO Pod ==== Creating {project_name_abbr} Administrator Account via Remote Shell Session to {project_name_abbr} Pod
Run following commands to create an administrator account for the `master` realm of the RH-SSO server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the RH-SSO application pod has been started: Run following commands to create an administrator account for the `master` realm of the {project_name_abbr} server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the {project_name_abbr} application pod has been started:
. Identify the RH-SSO application pod. . Identify the {project_name_abbr} application pod.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -400,7 +400,7 @@ sso-mysql-6-d97pf 1/1 Running 0 2m
$ oc rsh sso-12-pt93n $ oc rsh sso-12-pt93n
sh-4.2$ 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. . Create the {project_name_abbr} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -426,27 +426,27 @@ sh-4.2$ ./jboss-cli.sh --connect ':reload'
+ +
[WARNING] [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. This is because restarting the whole container will recreate it from scratch, without the RH-SSO server administration account for the `master` realm. When restarting the server it is important to restart just the JBoss EAP process within the running {project_name_abbr} container, and not the whole container. This is because restarting the whole container will recreate it from scratch, without the {project_name_abbr} server administration account for the `master` realm.
==== ====
. Log in to the `master` realm's administration console of the RH-SSO server using the credentials created in the steps above. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the RH-SSO web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted RH-SSO web server, and specify the user name and password used to create the administrator user. . Log in to the `master` realm's administration console of the {project_name_abbr} server using the credentials created in the steps above. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the {project_name_abbr} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name_abbr} web server, and specify the user name and password used to create the administrator user.
=== Deployment Process === Deployment Process
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. 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 {project_name_abbr} 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 {project_name_abbr} 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: After the {project_name_abbr} web server pod has started, it can be accessed from its custom configured hostnames, or from the default hostnames:
* *\http://sso-_<project-name>_._<hostname>_/auth/admin*: for the RH-SSO web server, and * *\http://sso-_<project-name>_._<hostname>_/auth/admin*: for the {project_name_abbr} web server, and
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted RH-SSO web server. * *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted {project_name_abbr} web server.
Use the xref:../advanced_concepts/advanced_concepts.adoc#advanced-concepts-sso-administrator-setup[administrator user credentials] to log in into the `master` realm’s administration console. Use the xref:../advanced_concepts/advanced_concepts.adoc#advanced-concepts-sso-administrator-setup[administrator user credentials] to log in into the `master` realm’s administration console.
[[advanced-concepts-SSO-Clients]] [[advanced-concepts-SSO-Clients]]
=== RH-SSO Clients === {project_name_abbr} 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 make 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. Clients are {project_name_abbr} entities that request user authentication. A client can be an application requesting {project_name_abbr} to provide user authentication, or it can make 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. + {project_name_abbr} 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: 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. - *public*: Useful for JavaScript applications that run directly in the browser and require no server configuration.
@ -470,16 +470,16 @@ The following is an example snippet for the application *web.xml* to configure a
---- ----
[[advanced-concepts-Auto-Man-Client-Reg]] [[advanced-concepts-Auto-Man-Client-Reg]]
==== Automatic and Manual RH-SSO Client Registration Methods ==== Automatic and Manual {project_name_abbr} 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. A client application can be automatically registered to an {project_name_abbr} realm by using credentials passed in variables specific to the *_eap64-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. Alternatively, you can manually register the client application by configuring and exporting the {project_name_abbr} client adapter and including it in the client application configuration.
===== Automatic RH-SSO Client Registration ===== Automatic {project_name_abbr} 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. Automatic {project_name_abbr} client registration is determined by {project_name_abbr} environment variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. The {project_name_abbr} credentials supplied in the template are then used to register the client to the {project_name_abbr} 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: The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
@ -492,10 +492,10 @@ The RH-SSO environment variables included in the *_eap64-sso-s2i_*, *_eap70-sso
|Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix> |Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>
|*_SSO_URL_* |*_SSO_URL_*
|The RH-SSO web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth |The {project_name_abbr} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|*_SSO_REALM_* |*_SSO_REALM_*
|The RH-SSO realm created for this procedure. |The {project_name_abbr} realm created for this procedure.
|*_SSO_USERNAME_* |*_SSO_USERNAME_*
|The name of the _realm management user_. |The name of the _realm management user_.
@ -504,16 +504,16 @@ The RH-SSO environment variables included in the *_eap64-sso-s2i_*, *_eap70-sso
| The password of the user. | The password of the user.
|*_SSO_PUBLIC_KEY_* |*_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. |The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name_abbr} console.
|*_SSO_BEARER_ONLY_* |*_SSO_BEARER_ONLY_*
|If set to *true*, the OpenID Connect client is registered as bearer-only. |If set to *true*, the OpenID Connect client is registered as bearer-only.
|*_SSO_ENABLE_CORS_* |*_SSO_ENABLE_CORS_*
|If set to *true*, the RH-SSO adapter enables Cross-Origin Resource Sharing (CORS). |If set to *true*, the {project_name_abbr} adapter enables Cross-Origin Resource Sharing (CORS).
|=== |===
If the RH-SSO client uses the SAML protocol, the following additional variables need to be configured: If the {project_name_abbr} client uses the SAML protocol, the following additional variables need to be configured:
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
@ -532,29 +532,29 @@ If the RH-SSO client uses the SAML protocol, the following additional variables
|Alias for keys/certificate to use for SAML. The default is _jboss_. |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. See xref:Example-EAP-Auto[Example Workflow: Automatically Registering EAP Application in {project_name_abbr} 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 {project_name_abbr} 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: Manual {project_name_abbr} 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 {project_name_abbr} web console. The name of this file is different for OpenID-Connect and SAML clients:
[horizontal] [horizontal]
*OpenID-Connect*:: _../configuration/secure-deployments_ *OpenID-Connect*:: _../configuration/secure-deployments_
*SAML*:: _../configuration/secure-saml-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. These files are copied to the {project_name_abbr} 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: There are two methods for passing the {project_name_abbr} 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 * Modify the deployment file to contain the {project_name_abbr} 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. * 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. See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {project_name_abbr} Authentication, Using SAML Client] for an end-to-end example of the manual {project_name_abbr} client registration method using a SAML client.
=== Limitations === 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. OpenShift does not currently accept OpenShift role mapping from external providers. If {project_name_abbr} is used as an authentication gateway for OpenShift, users created in {project_name_abbr} 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: For example, to allow an {project_name_abbr}-created user to view a project namespace in OpenShift:
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]> oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]>

6
openshift/topics/before_you_begin.adoc
View file

@ -1,9 +1,9 @@
== Before You Begin == Before You Begin
=== Comparison: {project_openshift_product_name} Image and Red Hat Single Sign-On === Comparison: {project_openshift_product_name} Image and Red Hat Single Sign-On
The {project_openshift_product_name} image version number 7.2 is based on Red Hat Single Sign-On 7.2. There are some differences in functionality between the {project_openshift_product_name} image and Red Hat Single Sign-On: The {project_openshift_product_name} image version number {project_version} is based on {project_name} {project_version}. There are some differences in functionality between the {project_openshift_product_name} image and {project_name}:
* The {project_openshift_product_name} image includes all of the functionality of Red Hat Single Sign-On. In addition, the RH-SSO-enabled JBoss EAP image automatically handles OpenID Connect or SAML client registration and configuration for *_.war_* deployments that contain *<auth-method>KEYCLOAK</auth-method>* or *<auth-method>KEYCLOAK-SAML</auth-method>* in their respective *web.xml* files. * The {project_openshift_product_name} image includes all of the functionality of {project_name}. In addition, the {project_name_abbr}-enabled JBoss EAP image automatically handles OpenID Connect or SAML client registration and configuration for *_.war_* deployments that contain *<auth-method>KEYCLOAK</auth-method>* or *<auth-method>KEYCLOAK-SAML</auth-method>* in their respective *web.xml* files.
=== Version Compatibility and Support === Version Compatibility and Support
See the xPaaS part of the https://access.redhat.com/articles/2176281[OpenShift and Atomic Platform Tested Integrations page] for details about OpenShift image version compatibility. See the xPaaS part of the https://access.redhat.com/articles/2176281[OpenShift and Atomic Platform Tested Integrations page] for details about OpenShift image version compatibility.
@ -22,5 +22,5 @@ The Tutorials in this guide follow on from and assume an OpenShift instance simi
[IMPORTANT] [IMPORTANT]
==== ====
For information related to updating the existing database when migrating {project_openshift_product_name} image from RH-SSO 7.0 to RH-SSO 7.1, or from RH-SSO 7.1 to RH-SSO 7.2, see the xref:../tutorials/tutorials.adoc#upgrading-sso-db-from-70-to-71[Updating Existing Database when Migrating {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:../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.
==== ====

210
openshift/topics/get_started.adoc
View file

@ -28,7 +28,7 @@ To update to the latest {project_openshift_product_name} images, run the followi
---- ----
$ oc login -u system:admin $ 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: . Run the following commands to update the core set of {project_name_abbr} {project_version} resources for OpenShift in the `openshift` project:
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -46,7 +46,7 @@ do
https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/{project_templates_version}-dev/templates/${resource} https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/{project_templates_version}-dev/templates/${resource}
done done
---- ----
. Run the following command to install the RH-SSO 7.2 OpenShift image streams in the `openshift` project: . Run the following command to install the {project_name_abbr} {project_version} OpenShift image streams in the `openshift` project:
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -110,24 +110,24 @@ $ oc secrets link <pass:quotes[_service-account-name_]> <pass:quotes[_sso-ssl-se
//// ////
[[sso-administrator-setup]] [[sso-administrator-setup]]
==== Creating Administrator Account for Red Hat Single Sign-On Server ==== Creating Administrator Account for {project_name} 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. {project_name} 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 {project_name}.
The administrator account can be created: 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 providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the {project_name_abbr} application template, or
* By xref:sso-admin-remote-shell[a remote shell session to particular RH-SSO pod], if the {project_openshift_product_name} image is deployed without an application template. * By xref:sso-admin-remote-shell[a remote shell session to particular {project_name_abbr} pod], if the {project_openshift_product_name} image is deployed without an application template.
[NOTE] [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 {project_openshift_product_name} image. {project_name} 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 {project_openshift_product_name} image.
==== ====
[[sso-admin-template-parameters]] [[sso-admin-template-parameters]]
===== Creating RH-SSO Administrator Account via Template Parameters ===== Creating {project_name_abbr} 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. When deploying {project_name_abbr} application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the {project_name_abbr} server's administrator account to be created for the `master` realm.
[NOTE] [NOTE]
==== ====
@ -136,25 +136,25 @@ When deploying RH-SSO application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADM
[IMPORTANT] [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: The lifespan of the {project_name_abbr} server's administrator account depends upon the the storage type used to store the {project_name_abbr} server's database:
* 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 in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates) the account exist throughout the lifecycle of the particular {project_name_abbr} 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 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 {project_name_abbr} 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. * 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 {project_name_abbr} 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). It is a common practice to deploy an {project_name_abbr} application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new {project_name_abbr} application needs to be instantiated).
==== ====
[WARNING] [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. 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 {project_name_abbr} applications.
==== ====
[IMPORTANT] [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: Run the following commands to prepare the previously created deployment config of the {project_name_abbr} application for reuse after the administrator account has been created:
. Identify the deployment config of the RH-SSO application. . Identify the deployment config of the {project_name_abbr} application.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -171,11 +171,11 @@ $ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD=""
==== ====
[[sso-admin-remote-shell]] [[sso-admin-remote-shell]]
===== Creating RH-SSO Administrator Account via Remote Shell Session to RH-SSO Pod ===== Creating {project_name_abbr} Administrator Account via Remote Shell Session to {project_name_abbr} Pod
Run following commands to create administrator account for the `master` realm of the RH-SSO server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the RH-SSO application pod has been started: Run following commands to create administrator account for the `master` realm of the {project_name_abbr} server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the {project_name_abbr} application pod has been started:
. Identify the RH-SSO application pod. . Identify the {project_name_abbr} application pod.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -191,7 +191,7 @@ sso-mysql-6-d97pf 1/1 Running 0 2m
$ oc rsh sso-12-pt93n $ oc rsh sso-12-pt93n
sh-4.2$ 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. . Create the {project_name_abbr} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -217,9 +217,9 @@ sh-4.2$ ./jboss-cli.sh --connect ':reload'
+ +
[WARNING] [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. When restarting the server it is important to restart just the JBoss EAP process within the running {project_name_abbr} container, and not the whole container. Because restarting the whole container recreates it from scratch, without the {project_name_abbr} 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-<project-name>.<hostname>/auth/admin* for the RH-SSO web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted RH-SSO web server, and specify user name and password used to create the administrator user. . Log into the `master` realm's administration console of the {project_name_abbr} server using the the credentials created in the steps above. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the {project_name_abbr} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name_abbr} web server, and specify user name and password used to create the administrator user.
==== Using the OpenShift Web Console ==== Using the OpenShift Web Console
Log in to the OpenShift web console: Log in to the OpenShift web console:
@ -229,14 +229,14 @@ Log in to the OpenShift web console:
. Select an application template and configure the deployment parameters as required. . Select an application template and configure the deployment parameters as required.
. Click *Create* to deploy the application template. . Click *Create* to deploy the application template.
These are some of the more common variables to configure an RH-SSO deployment: These are some of the more common variables to configure an {project_name_abbr} deployment:
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
|Description |Description
|*_APPLICATION_NAME_* |*_APPLICATION_NAME_*
|The name for the RH-SSO application. |The name for the {project_name_abbr} application.
|*_HOSTNAME_HTTPS_* |*_HOSTNAME_HTTPS_*
|Custom hostname for https service route. Leave blank for default hostname of _<application-name>.<project>.<default-domain-suffix>_ |Custom hostname for https service route. Leave blank for default hostname of _<application-name>.<project>.<default-domain-suffix>_
@ -263,47 +263,47 @@ These are some of the more common variables to configure an RH-SSO deployment:
|The name of the secret containing the JGroups keystore file. |The name of the secret containing the JGroups keystore file.
|*_SSO_ADMIN_USERNAME_* |*_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. |Username of the administrator account for the `master` realm of the {project_name_abbr} 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_* |*_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. |Password of the administrator account for the `master` realm of the {project_name_abbr} 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_* |*_SSO_REALM_*
|The name of an additional RH-SSO realm to create during deployment. |The name of an additional {project_name_abbr} realm to create during deployment.
|*_SSO_SERVICE_USERNAME_* |*_SSO_SERVICE_USERNAME_*
|RH-SSO service user name to manage the realm. |{project_name_abbr} service user name to manage the realm.
|*_SSO_SERVICE_PASSWORD_* |*_SSO_SERVICE_PASSWORD_*
|RH-SSO service user password. |{project_name_abbr} service user password.
|=== |===
See the xref:env_vars[Reference chapter] for a more comprehensive list of the RH-SSO environment variables. See the xref:env_vars[Reference chapter] for a more comprehensive list of the {project_name_abbr} environment variables.
See the xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} Image] for an end-to-end example of RH-SSO deployment. See the xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} Image] for an end-to-end example of {project_name_abbr} deployment.
==== Routes ==== Routes
The {project_openshift_product_name} 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. The {project_openshift_product_name} 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 {project_name_abbr} 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. 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 ==== Deployment Process
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. 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 {project_name_abbr} 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 {project_name_abbr} 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: After the {project_name_abbr} web server pod has started, it can be accessed at its custom configured hostnames, or at the default hostnames:
* *\http://sso-_<project-name>_._<hostname>_/auth/admin*: for the RH-SSO web server, and * *\http://sso-_<project-name>_._<hostname>_/auth/admin*: for the {project_name_abbr} web server, and
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted RH-SSO web server. * *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted {project_name_abbr} 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. 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]] [[SSO-Clients]]
==== RH-SSO Clients ==== {project_name_abbr} 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. Clients are {project_name_abbr} entities that request user authentication. A client can be an application requesting {project_name_abbr} 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 {project_name} 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. + {project_name_abbr} 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: 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. - *public*: Useful for JavaScript applications that run directly in the browser and require no server configuration.
@ -327,16 +327,16 @@ The following is an example snippet for the application *web.xml* to configure a
---- ----
[[Auto-Man-Client-Reg]] [[Auto-Man-Client-Reg]]
==== Automatic and Manual RH-SSO Client Registration Methods ==== Automatic and Manual {project_name_abbr} 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. A client application can be automatically registered to an {project_name_abbr} realm by using credentials passed in variables specific to the *_eap64-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. Alternatively, you can manually register the client application by configuring and exporting the {project_name_abbr} client adapter and including it in the client application configuration.
==== Automatic RH-SSO Client Registration ==== Automatic {project_name_abbr} 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. Automatic {project_name_abbr} client registration is determined by {project_name_abbr} environment variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. The {project_name_abbr} credentials supplied in the template are then used to register the client to the {project_name_abbr} 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: The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
@ -349,10 +349,10 @@ The RH-SSO environment variables included in the *_eap64-sso-s2i_*, *_eap70-sso
|Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix> |Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>
|*_SSO_URL_* |*_SSO_URL_*
|The RH-SSO web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth |The {project_name_abbr} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|*_SSO_REALM_* |*_SSO_REALM_*
|The RH-SSO realm created for this procedure. |The {project_name_abbr} realm created for this procedure.
|*_SSO_USERNAME_* |*_SSO_USERNAME_*
|The name of the _realm management user_. |The name of the _realm management user_.
@ -361,16 +361,16 @@ The RH-SSO environment variables included in the *_eap64-sso-s2i_*, *_eap70-sso
| The password of the user. | The password of the user.
|*_SSO_PUBLIC_KEY_* |*_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. |The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name_abbr} console.
|*_SSO_BEARER_ONLY_* |*_SSO_BEARER_ONLY_*
|If set to *true*, the OpenID Connect client is registered as bearer-only. |If set to *true*, the OpenID Connect client is registered as bearer-only.
|*_SSO_ENABLE_CORS_* |*_SSO_ENABLE_CORS_*
|If set to *true*, the RH-SSO adapter enables Cross-Origin Resource Sharing (CORS). |If set to *true*, the {project_name_abbr} adapter enables Cross-Origin Resource Sharing (CORS).
|=== |===
If the RH-SSO client uses the SAML protocol, the following additional variables need to be configured: If the {project_name_abbr} client uses the SAML protocol, the following additional variables need to be configured:
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
@ -389,29 +389,29 @@ If the RH-SSO client uses the SAML protocol, the following additional variables
|Alias for keys/certificate to use for SAML. The default is _jboss_. |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. See xref:Example-EAP-Auto[Example Workflow: Automatically Registering EAP Application in {project_name_abbr} 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 {project_name_abbr} 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: Manual {project_name_abbr} 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 {project_name_abbr} web console. The name of this file is different for OpenID-Connect and SAML clients:
[horizontal] [horizontal]
*OpenID-Connect*:: _../configuration/secure-deployments_ *OpenID-Connect*:: _../configuration/secure-deployments_
*SAML*:: _../configuration/secure-saml-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. These files are copied to the {project_name_abbr} 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: There are two methods for passing the {project_name_abbr} 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 * Modify the deployment file to contain the {project_name_abbr} 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. * 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. See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {project_name_abbr} Authentication, Using SAML Client] for an end-to-end example of the manual {project_name_abbr} client registration method using a SAML client.
==== Limitations ==== 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. OpenShift does not currently accept OpenShift role mapping from external providers. If {project_name_abbr} is used as an authentication gateway for OpenShift, users created in {project_name_abbr} 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: For example, to allow an {project_name_abbr}-created user to view a project namespace in OpenShift:
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]> oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]>
@ -421,9 +421,9 @@ oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_pr
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. 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 ==== Deploy Binary Build of EAP 6.4 / 7.1 JSP Service Invocation Application that Authenticates Using {project_name}
The following example uses both link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstarts to deploy EAP 6.4 / 7.0 JSP service application that authenticates using the 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.1 JSP service application that authenticates using the {project_name}.
*Prerequisite:* *Prerequisite:*
@ -439,38 +439,33 @@ This guide assumes the {project_openshift_product_name} image has been previousl
* *_{project_templates_version}-x509-postgresql-persistent_* * *_{project_templates_version}-x509-postgresql-persistent_*
==== ====
===== Create RH-SSO Realm, Roles, and User for the EAP 6.4 / 7.0 JSP Application ===== Create {project_name_abbr} Realm, Roles, and User for the EAP 6.4 / 7.1 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 {project_openshift_product_name} image has been deployed: The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name_abbr} realm, username, and password to be able to authenticate using {project_name}. Perform the following steps after the {project_openshift_product_name} image has been deployed:
*Create the RH-SSO Realm* *Create the {project_name_abbr} Realm*
. Login to the administration console of the RH-SSO server. . Login to the administration console of the {project_name_abbr} server.
+ +
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin* *\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]. Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name_abbr} administrator user].
. Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*. . Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*.
. Enter a realm name (this example uses `demo`) and click *Create*. . Enter a realm name (this example uses `demo`) and click *Create*.
[[copy-rsa-public-key]] [[copy-rsa-public-key]]
*Copy the 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. In the newly created `demo` realm, click the *Keys* tab, then select *Active* tab, and copy the public key of type *RSA* that has been generated.
[NOTE] [NOTE]
==== ====
RH-SSO 7.1 and RH-SSO 7.2 images generate two keys by default: The {project_openshift_product_name} image version {project_version} generates multiple keys by default, for example *HS256*, *RS256*, or *AES*. To copy the public key information for the {project_openshift_product_name} {project_version} image, click the *Keys* tab, then select *Active* tab, and click the *Public key* button of that row in the keys table, where type of the key matches *RSA*. Then select and copy the content of the pop-up window that appears.
* 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. The information about the public key is necessary xref:sso-public-key-details[later to deploy] the {project_name_abbr}-enabled EAP 6.4 / 7.1 JSP application.
*Create RH-SSO Roles* *Create {project_name_abbr} Roles*
[NOTE] [NOTE]
==== ====
@ -481,22 +476,20 @@ The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-je
* `admin` - Can be invoked by users with the `admin` 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. Create `user` and `admin` roles in {project_name_abbr}. These roles will be assigned to an {project_name_abbr} application user to authenticate access to user applications.
. Click *Roles* in the *Configure* sidebar to list the roles for this realm. . Click *Roles* in the *Configure* sidebar to list the roles for this realm.
+ +
[NOTE] [NOTE]
==== ====
This is a new realm, so there should only be the default roles: This is a new realm, so there should only be the default (`offline_access` and `uma_authorization`) roles.
* `offline_access` and `uma_authorization` role for the RH-SSO 7.1 and RH-SSO 7.2 images.
==== ====
. Click *Add Role*. . Click *Add Role*.
. Enter the role name (`user`) and click *Save*. . Enter the role name (`user`) and click *Save*.
Repeat these steps for the `admin` role. Repeat these steps for the `admin` role.
*Create the RH-SSO Realm Management User* *Create the {project_name_abbr} Realm Management User*
. Click *Users* in the *Manage* sidebar to view the user information for the realm. . Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User.* . Click *Add User.*
@ -505,9 +498,9 @@ Repeat these steps for the `admin` role.
.. Click the *Credentials* tab in the user space and enter a password for the user (this example uses the password `apppassword`). .. 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. .. 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 ===== Assign `user` {project_name_abbr} Role to the Realm Management User
Perform the following steps to tie the previously created `appuser` with the `user` RH-SSO role: Perform the following steps to tie the previously created `appuser` with the `user` {project_name_abbr} 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 *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. . Click *Client Roles*, select *realm-management* entry from the list, select each record in the *Available Roles* list.
@ -518,9 +511,9 @@ You can select multiple items at once by holding the *Ctrl* key and simultaneous
==== ====
. Click *Add selected>* to assign the roles to the client. . 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 ===== Prepare {project_name_abbr} Authentication for OpenShift Deployment of the EAP 6.4 / 7.1 JSP Application
. Create a new project for the EAP 6.4 / 7.0 JSP application. . Create a new project for the EAP 6.4 / 7.1 JSP application.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -552,7 +545,7 @@ $ keytool -genseckey \
-storetype JCEKS \ -storetype JCEKS \
-keystore eapjgroups.jceks -keystore eapjgroups.jceks
---- ----
.. Generate the EAP 6.4 / 7.0 for OpenShift secrets with the SSL and JGroup keystore files. .. Generate the EAP 6.4 / 7.1 for OpenShift secrets with the SSL and JGroup keystore files.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -570,7 +563,7 @@ $ oc secret new eap-jgroup-secret eapjgroups.jceks
$ oc secrets link default eap-ssl-secret eap-jgroup-secret $ oc secrets link default eap-ssl-secret eap-jgroup-secret
---- ----
===== Deploy Binary Build of the EAP 6.4 / 7.0 JSP Application ===== Deploy Binary Build of the EAP 6.4 / 7.1 JSP Application
. Clone the source code. . Clone the source code.
+ +
@ -642,7 +635,7 @@ app-jee-jsp]$ mvn clean package -DskipTests
+ +
[IMPORTANT] [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. 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.1 for OpenShift image, it is not necessary to specify the form of `keycloak.json` adapter configuration file at this moment.
==== ====
[[directory-structure-binary-builds]] [[directory-structure-binary-builds]]
@ -696,7 +689,7 @@ Location of the standard deployments directory depends on the underlying base im
|=== |===
| Name of the Underlying Base Image(s) | Standard Location of the Deployments Directory | 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_* | EAP for OpenShift 6.4 and 7.1 | *_$JBOSS_HOME/standalone/deployments_*
| Java S2I for OpenShift | *_/deployments_* | Java S2I for OpenShift | *_/deployments_*
@ -704,13 +697,12 @@ Location of the standard deployments directory depends on the underlying base im
|=== |===
==== ====
. Identify the image stream for EAP 6.4 / 7.0 image. . Identify the image stream for EAP 6.4 / 7.1 image.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc get is -n openshift | grep eap | cut -d ' ' -f 1 $ oc get is -n openshift | grep eap | cut -d ' ' -f 1
jboss-eap64-openshift jboss-eap64-openshift
jboss-eap70-openshift
jboss-eap71-openshift jboss-eap71-openshift
---- ----
@ -720,19 +712,19 @@ jboss-eap71-openshift
+ +
[NOTE] [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. Replace `--image-stream=jboss-eap71-openshift` parameter with the `--image-stream=jboss-eap64-openshift` one in the following oc command to deploy the JSP application on top of JBoss EAP 6.4 for OpenShift image.
==== ====
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc new-build --binary=true \ $ oc new-build --binary=true \
--image-stream=jboss-eap70-openshift \ --image-stream=jboss-eap71-openshift \
--name=eap-app --name=eap-app
--> Found image 31895a4 (3 months old) in image stream "openshift/jboss-eap70-openshift" under tag "latest" for "jboss-eap70-openshift" --> Found image 31895a4 (3 months old) in image stream "openshift/jboss-eap71-openshift" under tag "latest" for "jboss-eap71-openshift"
JBoss EAP 7.0 JBoss EAP 7.1
------------- -------------
Platform for building and running JavaEE applications on JBoss EAP 7.0 Platform for building and running JavaEE applications on JBoss EAP 7.1
Tags: builder, javaee, eap, eap7 Tags: builder, javaee, eap, eap7
@ -779,7 +771,7 @@ $ oc new-app eap-app
eap-app-demo/eap-app-1:aa2574d9 eap-app-demo/eap-app-1:aa2574d9
------------------------------- -------------------------------
Platform for building and running JavaEE applications on JBoss EAP 7.0 Platform for building and running JavaEE applications on JBoss EAP 7.1
Tags: builder, javaee, eap, eap7 Tags: builder, javaee, eap, eap7
@ -793,7 +785,7 @@ $ oc new-app eap-app
--> Success --> Success
Run 'oc status' to view your app. Run 'oc status' to view your app.
---- ----
. Stop all running containers of the EAP 6.4 / 7.0 JSP application in the current namespace. . Stop all running containers of the EAP 6.4 / 7.1 JSP application in the current namespace.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -806,9 +798,9 @@ deploymentconfig/eap-app
$ oc scale dc/eap-app --replicas=0 $ oc scale dc/eap-app --replicas=0
deploymentconfig "eap-app" scaled deploymentconfig "eap-app" scaled
---- ----
. Further configure the EAP 6.4 / 7.0 JSP application prior the deployment. . Further configure the EAP 6.4 / 7.1 JSP application prior the deployment.
[[sso-public-key-details]] [[sso-public-key-details]]
.. Configure the application with proper details about the RH-SSO server instance. .. Configure the application with proper details about the {project_name_abbr} server instance.
+ +
[WARNING] [WARNING]
==== ====
@ -872,7 +864,7 @@ $ oc patch dc/eap-app --type=json \
-p '[{"op": "add", "path": "/spec/template/spec/serviceAccountName", "value": "default"}]' -p '[{"op": "add", "path": "/spec/template/spec/serviceAccountName", "value": "default"}]'
"eap-app" patched "eap-app" patched
---- ----
. Deploy container of the EAP 6.4 / 7.0 JSP application using the modified deployment config. . Deploy container of the EAP 6.4 / 7.1 JSP application using the modified deployment config.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -911,16 +903,16 @@ eap-app eap-app-eap-app-demo.openshift.example.com eap-app 8080
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: 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] [.text-center]
image:images/sso_app_jee_jsp.png[RH-SSO Example JSP Application] image:images/sso_app_jee_jsp.png[{project_name_abbr} Example JSP Application]
Perform the following to test the application: Perform the following to test the application:
* Click the *INVOKE PUBLIC* button to access the `public` endpoint that doesn't require authentication. * Click the *INVOKE PUBLIC* button to access the `public` endpoint that doesn't require authentication.
+ +
You should see the *Message: public* output. 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. * Click the *LOGIN* button to be redirected for user authentication to the {project_name_abbr} 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: Specify username and password of the {project_name_abbr} user configured earlier (`appuser` / `apppassword`). Click *Log in*. The look of the application changes as detailed in the following image:
+ +
[.text-center] [.text-center]
image:images/sso_app_jee_jsp_logged_in.png[] image:images/sso_app_jee_jsp_logged_in.png[]
@ -934,23 +926,23 @@ You should see *403 Forbidden* output.
+ +
[NOTE] [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. The `admin` endpoint requires users with `admin` {project_name_abbr} 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: Perform the following steps to add the `appuser` to the `admin` {project_name_abbr} role:
+ +
. Access the administration console of the RH-SSO server's instance. . Access the administration console of the {project_name_abbr} server's instance.
+ +
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*. *\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]. Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name_abbr} administrator user].
. Click *Users* in the *Manage* sidebar to view the user information for the `demo` realm. . Click *Users* in the *Manage* sidebar to view the user information for the `demo` realm.
. Click *View all users* button. . Click *View all users* button.
. Click the ID link for the *appuser* or alternatively click the *Edit* button in the *Actions* column. . Click the ID link for the *appuser* or alternatively click the *Edit* button in the *Actions* column.
. Click the *Role Mappings* tab. . Click the *Role Mappings* tab.
. Select `admin` entry from the *Available Roles* list in the *Realm Roles* row. . 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. . Click *Add selected>* button to add the `admin` role to the user.
. Return to EAP 6.4 / 7.0 JSP service application. . Return to EAP 6.4 / 7.1 JSP service application.
+ +
*\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*. *\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*.
. Click the *LOGOUT* button to reload role mappings for the `appuser`. . Click the *LOGOUT* button to reload role mappings for the `appuser`.

37
openshift/topics/introduction.adoc
View file

@ -1,34 +1,33 @@
== Introduction == Introduction
=== What Is Red Hat Single Sign-On? === 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 {project_openshift_product_name} 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. Red Hat Single Sign-On ({project_name_abbr}) is an integrated sign-on solution available as a Red Hat JBoss Middleware for OpenShift containerized image. The {project_openshift_product_name} image provides an authentication server for users to centrally log in, log out, register, and manage user accounts for web applications, mobile applications, and RESTful web services.
[[sso-templates]] [[sso-templates]]
Red Hat offers multiple OpenShift application templates utilizing the {project_openshift_product_name} image version number 7.2. These define the resources needed to develop Red Hat Single Sign-On 7.2 server based deployment and can be split into the following two categories: Red Hat offers multiple OpenShift application templates utilizing the {project_openshift_product_name} image version number {project_version}. These define the resources needed to develop {project_name} {project_version} server based deployment and can be split into the following two categories:
[[passthrough-templates]] [[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]: * Templates using HTTPS and JGroups keystores and a truststore for the {project_name_abbr} 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]:
** *_{project_templates_version}-https_*: RH-SSO 7.2 backed by internal H2 database on the same pod. ** *_{project_templates_version}-https_*: {project_name_abbr} {project_version} 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_*: {project_name_abbr} {project_version} 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}-mysql-persistent_*: {project_name_abbr} {project_version} 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_*: {project_name_abbr} {project_version} 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. ** *_{project_templates_version}-postgresql-persistent_*: {project_name_abbr} {project_version} backed by persistent PostgreSQL database on a separate pod.
[[reencrypt-templates]] [[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]: * 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 {project_name_abbr} 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 {project_name_abbr} 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]:
** *_{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-https_*: {project_name_abbr} {project_version} with auto-generated HTTPS keystore and {project_name_abbr} 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-mysql-persistent_*: {project_name_abbr} {project_version} with auto-generated HTTPS keystore and {project_name_abbr} 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. ** *_{project_templates_version}-x509-postgresql-persistent_*: {project_name_abbr} {project_version} with auto-generated HTTPS keystore and {project_name_abbr} 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: Other templates that integrate with {project_name_abbr} are also available:
* *_eap64-sso-s2i_*: RH-SSO-enabled Red Hat JBoss Enterprise Application Platform 6.4. * *_eap64-sso-s2i_*: {project_name_abbr}-enabled Red Hat JBoss Enterprise Application Platform 6.4.
* *_eap70-sso-s2i_*: RH-SSO-enabled Red Hat JBoss Enterprise Application Platform 7.0. * *_eap71-sso-s2i_*: {project_name_abbr}-enabled Red Hat JBoss Enterprise Application Platform 7.1.
* *_eap71-sso-s2i_*: RH-SSO enabled Red Hat JBoss Enterprise Application Platform 7.1. * *_datavirt63-secure-s2i_*: {project_name_abbr}-enabled Red Hat JBoss Data Virtualization 6.3.
* *_datavirt63-secure-s2i_*: RH-SSO-enabled Red Hat JBoss Data Virtualization 6.3.
These templates contain environment variables specific to RH-SSO that enable automatic RH-SSO client registration when deployed. These templates contain environment variables specific to {project_name_abbr} that enable automatic {project_name_abbr} client registration when deployed.
See xref:Auto-Man-Client-Reg[Automatic and Manual RH-SSO Client Registration Methods] for more information. See xref:Auto-Man-Client-Reg[Automatic and Manual {project_name_abbr} Client Registration Methods] for more information.

72
openshift/topics/reference.adoc
View file

@ -306,14 +306,14 @@ option, printing the commands and their arguments as they are executed.
|*_true_* |*_true_*
|*_SSO_ADMIN_PASSWORD_* |*_SSO_ADMIN_PASSWORD_*
|Password of the administrator account for the `master` realm of the RH-SSO |Password of the administrator account for the `master` realm of the {project_name_abbr}
server. *Required.* If no value is specified, it is auto generated and server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift Instructional message when the template is displayed as an OpenShift Instructional message when the template is
instantiated. instantiated.
|*_adm-password_* |*_adm-password_*
|*_SSO_ADMIN_USERNAME_* |*_SSO_ADMIN_USERNAME_*
|Username of the administrator account for the `master` realm of the RH-SSO |Username of the administrator account for the `master` realm of the {project_name_abbr}
server. *Required.* If no value is specified, it is auto generated and server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift Instructional message when the template is displayed as an OpenShift Instructional message when the template is
instantiated. instantiated.
@ -331,17 +331,17 @@ is set.
|*_rh-sso-server.openshift.example.com_* |*_rh-sso-server.openshift.example.com_*
|*_SSO_REALM_* |*_SSO_REALM_*
|Name of the realm to be created in the RH-SSO server if this environment variable |Name of the realm to be created in the {project_name_abbr} server if this environment variable
is provided. is provided.
|*_demo_* |*_demo_*
|*_SSO_SERVICE_PASSWORD_* |*_SSO_SERVICE_PASSWORD_*
|The password for the RH-SSO service user. |The password for the {project_name_abbr} service user.
|*_mgmt-password_* |*_mgmt-password_*
|*_SSO_SERVICE_USERNAME_* |*_SSO_SERVICE_USERNAME_*
|The username used to access the RH-SSO service. This is used by clients to create |The username used to access the {project_name_abbr} service. This is used by clients to create
the application client(s) within the specified RH-SSO realm. This user is created the application client(s) within the specified {project_name_abbr} realm. This user is created
if this environment variable is provided. if this environment variable is provided.
|*_sso-mgmtuser_* |*_sso-mgmtuser_*
@ -371,13 +371,13 @@ configuration variables] with common OpenShift variables (for example
(e.g. *_HORNETQ_CLUSTER_PASSWORD_*), or configuration variables typical to (e.g. *_HORNETQ_CLUSTER_PASSWORD_*), or configuration variables typical to
database images (e.g. *_MYSQL_FT_MAX_WORD_LEN_*) yet. All of these different database images (e.g. *_MYSQL_FT_MAX_WORD_LEN_*) yet. All of these different
types of configuration variables can be adjusted as desired to achieve the types of configuration variables can be adjusted as desired to achieve the
deployed RH-SSO-enabled application will align with the intended use case as much deployed {project_name_abbr}-enabled application will align with the intended use case as much
as possible. The list of configuration variables, available for each category as possible. The list of configuration variables, available for each category
of application templates for RH-SSO-enabled applications, is described below. of application templates for {project_name_abbr}-enabled applications, is described below.
==== Template variables for all RH-SSO images ==== Template variables for all {project_name_abbr} images
.Configuration Variables Available For All RH-SSO Images .Configuration Variables Available For All {project_name_abbr} Images
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
@ -445,28 +445,28 @@ ImageStreams in a different namespace/project.
|The name of the secret containing the keystore file. |The name of the secret containing the keystore file.
|*_SSO_ADMIN_USERNAME_* |*_SSO_ADMIN_USERNAME_*
|Username of the administrator account for the `master` realm of the RH-SSO |Username of the administrator account for the `master` realm of the {project_name_abbr}
server. *Required.* If no value is specified, it is auto generated and server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift instructional message when the template is displayed as an OpenShift instructional message when the template is
instantiated. instantiated.
|*_SSO_ADMIN_PASSWORD_* |*_SSO_ADMIN_PASSWORD_*
|Password of the administrator account for the `master` realm of the RH-SSO |Password of the administrator account for the `master` realm of the {project_name_abbr}
server. *Required.* If no value is specified, it is auto generated and server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift instructional message when the template is displayed as an OpenShift instructional message when the template is
instantiated. instantiated.
|*_SSO_REALM_* |*_SSO_REALM_*
|Name of the realm to be created in the RH-SSO server if this environment variable |Name of the realm to be created in the {project_name_abbr} server if this environment variable
is provided. is provided.
|*_SSO_SERVICE_USERNAME_* |*_SSO_SERVICE_USERNAME_*
|The username used to access the RH-SSO service. This is used by clients to create |The username used to access the {project_name_abbr} service. This is used by clients to create
the application client(s) within the specified RH-SSO realm. This user is created the application client(s) within the specified {project_name_abbr} realm. This user is created
if this environment variable is provided. if this environment variable is provided.
|*_SSO_SERVICE_PASSWORD_* |*_SSO_SERVICE_PASSWORD_*
|The password for the RH-SSO service user. |The password for the {project_name_abbr} service user.
|*_SSO_TRUSTSTORE_* |*_SSO_TRUSTSTORE_*
|The name of the truststore file within the secret. |The name of the truststore file within the secret.
@ -481,7 +481,7 @@ if this environment variable is provided.
==== Template variables specific to *_{project_templates_version}-mysql_*, *_{project_templates_version}-mysql-persistent_*, and *_{project_templates_version}-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 .Configuration Variables Specific To {project_name_abbr}-enabled MySQL Applications With Ephemeral Or Persistent Storage
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
@ -515,7 +515,7 @@ broken.
==== Template variables specific to *_{project_templates_version}-postgresql_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-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 .Configuration Variables Specific To {project_name_abbr}-enabled PostgreSQL Applications With Ephemeral Or Persistent Storage
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
@ -540,7 +540,7 @@ number of prepared transactions.
==== 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_* ==== 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 .Configuration Variables Specific To {project_name_abbr}-enabled MySQL / PostgreSQL Applications With Persistent Storage
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
@ -549,7 +549,7 @@ number of prepared transactions.
|Size of persistent storage for database volume. |Size of persistent storage for database volume.
|=== |===
==== Template variables for general *eap64*, *eap70*, and *eap71* S2I images ==== Template variables for general *eap64* and *eap71* S2I images
.Configuration Variables For EAP 6.4 and EAP 7 Applications Built Via S2I .Configuration Variables For EAP 6.4 and EAP 7 Applications Built Via S2I
[cols="2*", options="header"] [cols="2*", options="header"]
@ -640,37 +640,37 @@ ImageStreams in a different namespace/project.
|Git source URI for application. |Git source URI for application.
|=== |===
==== Template variables specific to *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, and *_eap71-sso-s2i_* for automatic client registration ==== Template variables specific to *_eap64-sso-s2i_* and *_eap71-sso-s2i_* for automatic client registration
.Configuration Variables For EAP 6.4 and EAP 7 RH-SSO-enabled Applications Built Via S2I .Configuration Variables For EAP 6.4 and EAP 7 {project_name_abbr}-enabled Applications Built Via S2I
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
|Description |Description
|*_SSO_URL_* |*_SSO_URL_*
|RH-SSO server location. |{project_name_abbr} server location.
|*_SSO_REALM_* |*_SSO_REALM_*
|Name of the realm to be created in the RH-SSO server if this environment variable |Name of the realm to be created in the {project_name_abbr} server if this environment variable
is provided. is provided.
|*_SSO_USERNAME_* |*_SSO_USERNAME_*
|The username used to access the RH-SSO service. This is used to create the |The username used to access the {project_name_abbr} service. This is used to create the
application client(s) within the specified RH-SSO realm. This should match the application client(s) within the specified {project_name_abbr} realm. This should match the
*_SSO_SERVICE_USERNAME_* specified through one of the *{project_templates_version}-* templates. *_SSO_SERVICE_USERNAME_* specified through one of the *{project_templates_version}-* templates.
|*_SSO_PASSWORD_* |*_SSO_PASSWORD_*
|The password for the RH-SSO service user. |The password for the {project_name_abbr} service user.
|*_SSO_PUBLIC_KEY_* |*_SSO_PUBLIC_KEY_*
|RH-SSO public key. Public key is recommended to be passed into the template to |{project_name_abbr} public key. Public key is recommended to be passed into the template to
avoid man-in-the-middle security attacks. avoid man-in-the-middle security attacks.
|*_SSO_SECRET_* |*_SSO_SECRET_*
|The RH-SSO client secret for confidential access. |The {project_name_abbr} client secret for confidential access.
|*_SSO_SERVICE_URL_* |*_SSO_SERVICE_URL_*
|RH-SSO service location. |{project_name_abbr} service location.
|*_SSO_TRUSTSTORE_SECRET_* |*_SSO_TRUSTSTORE_SECRET_*
|The name of the secret containing the truststore file. Used for |The name of the secret containing the truststore file. Used for
@ -683,19 +683,19 @@ avoid man-in-the-middle security attacks.
|The password for the truststore and certificate. |The password for the truststore and certificate.
|*_SSO_BEARER_ONLY_* |*_SSO_BEARER_ONLY_*
|RH-SSO client access type. |{project_name_abbr} client access type.
|*_SSO_DISABLE_SSL_CERTIFICATE_VALIDATION_* |*_SSO_DISABLE_SSL_CERTIFICATE_VALIDATION_*
|If true SSL communication between EAP and the RH-SSO Server is insecure |If true SSL communication between EAP and the {project_name_abbr} Server is insecure
(i.e. certificate validation is disabled with curl) (i.e. certificate validation is disabled with curl)
|*_SSO_ENABLE_CORS_* |*_SSO_ENABLE_CORS_*
|Enable CORS for RH-SSO applications. |Enable CORS for {project_name_abbr} applications.
|=== |===
==== Template variables specific to *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, and *_eap71-sso-s2i_* for automatic client registration with SAML clients ==== Template variables specific to *_eap64-sso-s2i_* and *_eap71-sso-s2i_* for automatic client registration with SAML clients
.Configuration Variables For EAP 6.4 and EAP 7 RH-SSO-enabled Applications Built Via S2I Using SAML Protocol .Configuration Variables For EAP 6.4 and EAP 7 {project_name_abbr}-enabled Applications Built Via S2I Using SAML Protocol
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
|Variable |Variable
@ -713,7 +713,7 @@ avoid man-in-the-middle security attacks.
|The name of the secret containing the keystore file. |The name of the secret containing the keystore file.
|*_SSO_SAML_LOGOUT_PAGE_* |*_SSO_SAML_LOGOUT_PAGE_*
|RH-SSO logout page for SAML applications. |{project_name_abbr} logout page for SAML applications.
|=== |===
=== Exposed Ports === Exposed Ports

208
openshift/topics/tutorials.adoc
View file

@ -1,4 +1,4 @@
[[RH-SSO-Binary-Builds-Tutorial]] [[{project_name_abbr}-Binary-Builds-Tutorial]]
=== Example Workflow: Creating OpenShift Application from Existing Maven Binaries and Securing it Using Red Hat Single Sing-On === Example Workflow: Creating OpenShift Application from Existing Maven Binaries and Securing it Using Red Hat Single Sing-On
== Tutorials == Tutorials
@ -6,14 +6,14 @@
[[Example-Deploying-SSO]] [[Example-Deploying-SSO]]
=== Example Workflow: Preparing and Deploying the {project_openshift_product_name} image === Example Workflow: Preparing and Deploying the {project_openshift_product_name} image
[[Preparing-SSO-Authentication-for-OpenShift-Deployment]] [[Preparing-SSO-Authentication-for-OpenShift-Deployment]]
==== Preparing RH-SSO Authentication for OpenShift Deployment ==== Preparing {project_name_abbr} Authentication for OpenShift Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. 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. 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 ==== Deploy Binary Build of EAP 6.4 / 7.1 JSP Service Invocation Application and Secure it 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. The following example uses both link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstarts to deploy EAP 6.4 / 7.1 JSP service application that authenticates using the Red Hat Single Sign-On.
*Prerequisite:* *Prerequisite:*
@ -29,55 +29,55 @@ This guide assumes the {project_openshift_product_name} image has been previousl
* *_{project_templates_version}-x509-postgresql-persistent_* * *_{project_templates_version}-x509-postgresql-persistent_*
==== ====
===== Create RH-SSO Realm, Roles, and User for the EAP 6.4 / 7.0 JSP Application ===== Create {project_name_abbr} Realm, Roles, and User for the EAP 6.4 / 7.1 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 {project_openshift_product_name} image has been deployed: The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name_abbr} realm, username, and password to be able to authenticate using Red Hat Single Sign-On. Perform the following steps after the {project_openshift_product_name} image has been deployed:
*Create the RH-SSO Realm* *Create the {project_name_abbr} Realm*
. Login to the administration console of the RH-SSO server. . Login to the administration console of the {project_name_abbr} server.
+ +
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin* *\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]. Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name_abbr} administrator user].
. Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*. . Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*.
. Enter a realm name (this example uses `demo`) and click *Create*. . Enter a realm name (this example uses `demo`) and click *Create*.
[[upgrading-sso-db-from-70-to-71]] [[upgrading-sso-db-from-previous-to-{project_version}]]
=== Example Workflow: Updating Existing Database when Migrating {project_openshift_product_name} Image to a new version === Example Workflow: Updating Existing Database when Migrating {project_openshift_product_name} Image to a new version
[IMPORTANT] [IMPORTANT]
==== ====
* Rolling updates from {project_openshift_product_name} 7.0 / 7.1 to 7.2 are not supported as databases and caches are not backward compatible. * Rolling updates from previous versions of {project_openshift_product_name} to version {project_version} are not supported as databases and caches are not backward compatible.
* Stop all {project_openshift_product_name} 7.0 / 7.1 instances before upgrading, they cannot run concurrently against the same database. * Stop all instances running some of previous versions of the {project_openshift_product_name} before upgrading. They cannot run concurrently against the same database.
* Pre-generated scripts are not available, they are generated dynamically depending on the database. * Pre-generated scripts are not available, they are generated dynamically depending on the database.
==== ====
Red Hat Single Sign-On 7.2 can xref:automatic-db-migration[automatically migrate the database schema], or you can choose to do it xref:manual-db-migration[manually]. {project_name} {project_version} can xref:automatic-db-migration[automatically migrate the database schema], or you can choose to do it xref:manual-db-migration[manually].
[NOTE] [NOTE]
==== ====
By default the database is automatically migrated when you start RH-SSO 7.2 for the first time. By default the database is automatically migrated when you start {project_name_abbr} {project_version} for the first time.
==== ====
[[automatic-db-migration]] [[automatic-db-migration]]
==== Automatic Database 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_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates]: This process assumes that you are running {project_openshift_product_name} {project_previous_version} 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_* * *_{project_previous_templates_version}-mysql_*
* *_sso71-postgresql_* * *_{project_previous_templates_version}-postgresql_*
* *_sso71-mysql-persistent_* * *_{project_previous_templates_version}-mysql-persistent_*
* *_sso71-postgresql-persistent_* * *_{project_previous_templates_version}-postgresql-persistent_*
[IMPORTANT] [IMPORTANT]
==== ====
Stop all RH-SSO 7.1 pods before upgrading to RH-SSO 7.2, as they cannot run concurrently against the same database. Stop all {project_name_abbr} {project_previous_version} pods before upgrading to {project_name_abbr} {project_version}, as they cannot run concurrently against the same database.
==== ====
Use the following steps to automatically migrate the database schema: Use the following steps to automatically migrate the database schema:
. Identify existing deployment config for RH-SSO 7.1 containers. . Identify existing deployment config for {project_name_abbr} {project_previous_version} containers.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -85,28 +85,28 @@ $ oc get dc -o name --selector=application=sso
deploymentconfig/sso deploymentconfig/sso
deploymentconfig/sso-postgresql deploymentconfig/sso-postgresql
---- ----
. Stop all RH-SSO 7.1 containers in the current namespace. . Stop all {project_name_abbr} {project_previous_version} containers in the current namespace.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc scale --replicas=0 dc/sso $ oc scale --replicas=0 dc/sso
deploymentconfig "sso" scaled deploymentconfig "sso" scaled
---- ----
. Update the image change trigger in the existing deployment config to reference the RH-SSO 7.2 image. . Update the image change trigger in the existing deployment config to reference the {project_name_abbr} {project_version} image.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ 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}"}]' $ 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 "sso" patched
---- ----
. Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers. . Start rollout of the new {project_name_abbr} {project_version} images based on the latest image defined in the image change triggers.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc rollout latest dc/sso $ oc rollout latest dc/sso
deploymentconfig "sso" rolled out deploymentconfig "sso" rolled out
---- ----
. Deploy RH-SSO 7.2 containers using the modified deployment config. . Deploy {project_name_abbr} {project_version} containers using the modified deployment config.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -134,20 +134,20 @@ $ oc logs sso-4-vg21r | grep 'Updating'
[IMPORTANT] [IMPORTANT]
==== ====
Pre-generated scripts are not available. They are generated dynamically depending on the database. With RH-SSO 7.2 one can generate and export these to an SQL file that can be manually applied to the database afterwards. To dynamically generate the SQL migration file for the database: Pre-generated scripts are not available. They are generated dynamically depending on the database. With {project_name_abbr} {project_version} one can generate and export these to an SQL file that can be manually applied to the database afterwards. To dynamically generate the SQL migration file for the database:
. Configure RH-SSO 7.2 with the correct datasource, . Configure {project_name_abbr} {project_version} with the correct datasource,
. Set following configuration options in the `standalone-openshift.xml` file: . Set following configuration options in the `standalone-openshift.xml` file:
.. `initializeEmpty=false`, .. `initializeEmpty=false`,
.. `migrationStrategy=manual`, and .. `migrationStrategy=manual`, and
.. `migrationExport` to the location on the file system of the pod, where the output SQL migration file should be stored (e.g. `migrationExport="${jboss.home.dir}/keycloak-database-update.sql"`). .. `migrationExport` to the location on the file system of the pod, where the output SQL migration file should be stored (e.g. `migrationExport="${jboss.home.dir}/keycloak-database-update.sql"`).
See link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_installation_and_configuration_guide/database-1#database_configuration[database configuration of RH-SSO 7.2] for further details. See link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_installation_and_configuration_guide/database-1#database_configuration[database configuration of {project_name_abbr} {project_version}] for further details.
The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all RH-SSO 7.1 instances before dynamic generation of the SQL migration file. The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all {project_name_abbr} {project_previous_version} 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_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:] This guide assumes the {project_openshift_product_name} image version {project_previous_version} 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:]
* *_{project_previous_templates_version}-mysql_* * *_{project_previous_templates_version}-mysql_*
* *_{project_previous_templates_version}-mysql-persistent_* * *_{project_previous_templates_version}-mysql-persistent_*
@ -210,13 +210,13 @@ spec:
$ cp {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml.orig \ $ 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 {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. . Copy the datasource definition and database access credentials from {project_name_abbr} {project_version} 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 (`<PREFIX>_JNDI`, `<PREFIX>_USERNAME`, `<PREFIX>_PASSWORD`, and `<PREFIX>_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`. 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 (`<PREFIX>_JNDI`, `<PREFIX>_USERNAME`, `<PREFIX>_PASSWORD`, and `<PREFIX>_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] [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 *<name>-<database_type>=<PREFIX>* 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.1/html-single/red_hat_jboss_enterprise_application_platform_for_openshift/#datasources[comma-separated list of *<name>-<database_type>=<PREFIX>* 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"] [source,bash,subs="verbatim,macros,attributes"]
@ -365,7 +365,7 @@ Successfully updated DB_PASSWORD to: tsWNhQHK
Successfully updated DB_DATABASE to: root Successfully updated DB_DATABASE to: root
Successfully updated TX_DATABASE_PREFIX_MAPPING to: sso-postgresql=DB 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. . Build the {project_name_abbr} {project_version} 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"] [subs="verbatim,macros,attributes"]
---- ----
@ -427,10 +427,10 @@ job "{project_previous_templates_version}-to-{project_templates_version}-db-migr
+ +
[IMPORTANT] [IMPORTANT]
==== ====
The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all RH-SSO 7.1 instances before dynamic generation of the SQL migration file. The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all {project_name_abbr} {project_version} instances before dynamic generation of the SQL migration file.
==== ====
+ +
. Identify existing deployment config for RH-SSO 7.1 containers. . Identify existing deployment config for {project_name_abbr} {project_version} containers.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -438,7 +438,7 @@ $ oc get dc -o name --selector=application=sso
deploymentconfig/sso deploymentconfig/sso
deploymentconfig/sso-postgresql deploymentconfig/sso-postgresql
---- ----
. Stop all RH-SSO 7.1 containers in the current namespace. . Stop all {project_name_abbr} {project_version} containers in the current namespace.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -485,7 +485,7 @@ keycloak-database-update.sql
sent 30 bytes received 29,726 bytes 59,512.00 bytes/sec sent 30 bytes received 29,726 bytes 59,512.00 bytes/sec
total size is 29,621 speedup is 1.00 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. . Inspect the `keycloak-database-update.sql` file for changes to be performed within manual {project_name_abbr} {project_version} database update.
. Apply the database update manually. . Apply the database update manually.
* Run the following commands for *_{project_previous_templates_version}-postgresql_* and *_{project_previous_templates_version}-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. ... Copy the generated SQL migration file to the PostgreSQL pod.
@ -574,21 +574,21 @@ Replace `<PREFIX>_USERNAME` and `<PREFIX>_DATABASE` with the actual database cre
[[image-change-trigger-update-step]] [[image-change-trigger-update-step]]
[start=12] [start=12]
. Update image change trigger in the existing deployment config of RH-SSO 7.1 to reference the RH-SSO 7.2 image. . Update image change trigger in the existing deployment config of {project_name_abbr} {project_version} to reference the {project_name_abbr} {project_version} image.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ 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}"}]' $ 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 "sso" patched
---- ----
. Start rollout of the new RH-SSO 7.2 images based on the latest image defined in the image change triggers. . Start rollout of the new {project_name_abbr} {project_version} images based on the latest image defined in the image change triggers.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
$ oc rollout latest dc/sso $ oc rollout latest dc/sso
deploymentconfig "sso" rolled out deploymentconfig "sso" rolled out
---- ----
. Deploy RH-SSO 7.2 containers using the modified deployment config. . Deploy {project_name_abbr} {project_version} containers using the modified deployment config.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -596,39 +596,39 @@ $ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled deploymentconfig "sso" scaled
---- ----
=== Example Workflow: Migrating Entire RH-SSO Server Database Across The Environments === Example Workflow: Migrating Entire {project_name_abbr} Server Database Across The Environments
This tutorial focuses on migrating the Red Hat Single Sign-On server database from one environment to another or migrating to a different database. It assumes steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing RH-SSO Authentication for OpenShift Deployment] section have been performed already. 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_abbr} Authentication for OpenShift Deployment] section have been performed already.
==== Deploying the RH-SSO MySQL Application Template ==== Deploying the {project_name_abbr} MySQL Application Template
. Log in to the OpenShift web console and select the _sso-app-demo_ project space. . 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. . 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. . Use the *Filter by keyword* search bar to limit the list to those that match _sso_. You may need to click *See all* to show the desired application template.
. Select *_{project_templates_version}-mysql_* RH-SSO application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value). . Select *_{project_templates_version}-mysql_* {project_name_abbr} application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value).
+ +
[IMPORTANT] [IMPORTANT]
==== ====
Export and import of Red Hat Single Sign-On 7.2 database link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[is triggered at RH-SSO server boot time and its paramaters are passed in via Java system properties.] This means during one RH-SSO server boot only one of the possible migration actions (either *_export_*, or *_import_*) can be performed. Export and import of {project_name} {project_version} database link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[is triggered at {project_name_abbr} server boot time and its paramaters are passed in via Java system properties.] This means during one {project_name_abbr} server boot only one of the possible migration actions (either *_export_*, or *_import_*) can be performed.
==== ====
+ +
[WARNING] [WARNING]
==== ====
When the *_SSO_REALM_* configuration variable is set on the {project_openshift_product_name} image, a database import is performed in order to create the RH-SSO server realm requested in the variable. For the database export to be performed correctly, the *_SSO_REALM_* configuration variable cannot be simultaneously defined on such image. When the *_SSO_REALM_* configuration variable is set on the {project_openshift_product_name} image, a database import is performed in order to create the {project_name_abbr} server realm requested in the variable. For the database export to be performed correctly, the *_SSO_REALM_* configuration variable cannot be simultaneously defined on such image.
==== ====
+ +
. Click *Create* to deploy the application template and start pod deployment. This may take a couple of minutes. . Click *Create* to deploy the application template and start pod deployment. This may take a couple of minutes.
+ +
Then access the RH-SSO web console at *$$https://secure-sso-$$_<sso-app-demo>_._<openshift32.example.com>_/auth/admin* using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account]. Then access the {project_name_abbr} web console 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].
+ +
[NOTE] [NOTE]
==== ====
This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. Accessing the RH-SSO web console will prompt an insecure connection warning. + This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. Accessing the {project_name_abbr} web console will prompt an insecure connection warning. +
For production environments, Red Hat recommends that you use an SSL certificate purchased from a verified Certificate Authority. For production environments, Red Hat recommends that you use an SSL certificate purchased from a verified Certificate Authority.
==== ====
==== (Optional) Creating additional RH-SSO link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported ==== (Optional) Creating additional {project_name_abbr} link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported
When performing link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[Red Hat Single Sign-On 7.2 server database export] only RH-SSO realms and users currently present in the database will be exported. If the exported JSON file should include also additional RH-SSO realms and users, these need to be created first: 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_abbr} realms and users currently present in the database will be exported. If the exported JSON file should include also additional {project_name_abbr} realms and users, these need to be created first:
. link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#create-realm[Create a new realm] . link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#create-realm[Create a new realm]
. link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#create-new-user[Create new users] . link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#create-new-user[Create new users]
@ -636,9 +636,9 @@ 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.] Upon their creation xref:sso-export-the-database[the database can be exported.]
[[sso-export-the-database]] [[sso-export-the-database]]
==== Export the RH-SSO database as a JSON file on the OpenShift pod ==== Export the {project_name_abbr} database as a JSON file on the OpenShift pod
. Get the RH-SSO deployment config and scale it down to zero. . Get the {project_name_abbr} deployment config and scale it down to zero.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -649,13 +649,13 @@ deploymentconfig/sso-mysql
$ oc scale --replicas=0 dc sso $ oc scale --replicas=0 dc sso
deploymentconfig "sso" scaled 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. . Instruct the {project_name_abbr} {project_version} server deployed on {project_openshift_product_name} image to perform database export at {project_name_abbr} server boot time.
+ +
[subs="verbatim,macros,attributes"] [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" 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. . Scale the {project_name_abbr} deployment config back up. This will start the {project_name_abbr} server and export its database.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -678,7 +678,7 @@ $ oc logs sso-4-ejr0k | grep 'Export'
==== Retrieve and import the exported JSON file ==== Retrieve and import the exported JSON file
. Retrieve the JSON file of the RH-SSO database from the pod. . Retrieve the JSON file of the {project_name_abbr} database from the pod.
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -690,20 +690,20 @@ sso-mysql-1-ozzl0 1/1 Running 0 4h
$ oc rsync sso-4-ejr0k:/tmp/demorealm-export.json . $ oc rsync sso-4-ejr0k:/tmp/demorealm-export.json .
---- ----
. (Optional) Import the JSON file of the RH-SSO database into an RH-SSO server running in another environment. . (Optional) Import the JSON file of the {project_name_abbr} database into an {project_name_abbr} server running in another environment.
+ +
[NOTE] [NOTE]
==== ====
For importing into an RH-SSO server not running on OpenShift, see the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/export_import[Export and Import section] of the RH SSO Server Administration Guide. For importing into an {project_name_abbr} server not running on OpenShift, see the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/export_import[Export and Import section] of the RH SSO Server Administration Guide.
==== ====
+ +
Use the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#admin_console_export_import[administration console] of the RH-SSO server to import the resources from previously exported JSON file into the RH-SSO server's database, when the RH-SSO server is running as a Red Hat Single Sign-On 7.2 container on OpenShift: Use the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#admin_console_export_import[administration console] of the {project_name_abbr} server to import the resources from previously exported JSON file into the {project_name_abbr} server's database, when the {project_name_abbr} server is running as a {project_name} {project_version} container on OpenShift:
.. Log into the `master` realm's administration console of the RH-SSO server using the credentials used to create the administrator user. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the RH-SSO web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted RH-SSO web server. .. Log into the `master` realm's administration console of the {project_name_abbr} server using the credentials used to create the administrator user. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the {project_name_abbr} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name_abbr} web server.
.. At the top of the sidebar choose the name of the RH-SSO realm, the users, clients, realm roles, and client roles should be imported to. This example uses `master` realm. .. At the top of the sidebar choose the name of the {project_name_abbr} realm, the users, clients, realm roles, and client roles should be imported to. This example uses `master` realm.
.. Click the *Import* link under *Manage* section at the bottom of the sidebar. .. Click the *Import* link under *Manage* section at the bottom of the sidebar.
.. In the page that opens, click *Select file* and then specify the location of the exported `demorealm-export.json` JSON file on the local file system. .. In the page that opens, click *Select file* and then specify the location of the exported `demorealm-export.json` JSON file on the local file system.
.. From the *Import from realm* drop-down menu, select the name of the RH-SSO realm from which the data should be imported. This example uses `master` realm. .. From the *Import from realm* drop-down menu, select the name of the {project_name_abbr} realm from which the data should be imported. This example uses `master` realm.
.. Choose which of users, clients, realm roles, and client roles should be imported (all of them are imported by default). .. Choose which of users, clients, realm roles, and client roles should be imported (all of them are imported by default).
.. Choose a strategy to perform, when a resource already exists (one of *Fail*, *Skip*, or *Overwrite*). .. Choose a strategy to perform, when a resource already exists (one of *Fail*, *Skip*, or *Overwrite*).
+ +
@ -721,7 +721,7 @@ When importing objects from a non-master realm to `master` realm or vice versa,
[.text-center] [.text-center]
image:images/import_realm_error.png[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. In such cases, it is necessary first to create the missing clients, having the *Access Type* set to *bearer-only*. These clients can be created by manual copy of their characteristics from the source {project_name_abbr} server, on which the export JSON file was created, to the target {project_name_abbr} server, where the JSON file is imported. After creation of the necessary clients, click the *Import* button again.
To suppress the xref:realm-import-error-message[above] error message, it is needed to create the missing `realm-management` client, of the *bearer-only* *Access Type*, and click the *Import* button again. To suppress the xref:realm-import-error-message[above] error message, it is needed to create the missing `realm-management` client, of the *bearer-only* *Access Type*, and click the *Import* button again.
==== ====
@ -737,13 +737,13 @@ The administration console import allows you to *overwrite* resources if you cho
==== ====
[[OSE-SSO-AUTH-TUTE]] [[OSE-SSO-AUTH-TUTE]]
=== Example Workflow: Configuring OpenShift to use RH-SSO for Authentication === Example Workflow: Configuring OpenShift to use {project_name_abbr} 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 {project_openshift_product_name} image], in which RH-SSO was deployed on OpenShift. Configure OpenShift to use the {project_name_abbr} deployment as the authorization gateway for OpenShift. This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name_abbr} 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-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. This example adds {project_name_abbr} 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 ==== Configuring {project_name_abbr} 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. Log in to the encrypted {project_name_abbr} 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 {project_name_abbr} deployment.
*Create a Realm* *Create a Realm*
@ -752,7 +752,7 @@ Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$_sso-app-de
*Create a User* *Create a User*
Create a test user that can be used to demonstrate the RH-SSO-enabled OpenShift login: Create a test user that can be used to demonstrate the {project_name_abbr}-enabled OpenShift login:
. Click *Users* in the *Manage* sidebar to view the user information for the realm. . Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*. . Click *Add User*.
@ -790,7 +790,7 @@ identityProviders:
kind: HTPasswdPasswordIdentityProvider kind: HTPasswdPasswordIdentityProvider
---- ----
+ +
Add RH-SSO as a secondary identity provider with content similar to the following snippet: Add {project_name_abbr} as a secondary identity provider with content similar to the following snippet:
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -818,8 +818,8 @@ Add RH-SSO as a secondary identity provider with content similar to the followin
email: email:
- email - email
---- ----
.. The RH-SSO *Secret* hash for the *clientSecret* can be found in the RH-SSO web console: *Clients* -> *_openshift-demo_* -> *Credentials* .. The {project_name_abbr} *Secret* hash for the *clientSecret* can be found in the {project_name_abbr} 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: .. The endpoints for the *urls* can be found by making a request with the {project_name_abbr} application. For example:
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
---- ----
@ -840,7 +840,7 @@ $ systemctl restart atomic-openshift-master
Navigate to the OpenShift web console, which in this example is _https://openshift.example.com:8443/console_. The OpenShift login page now has the option to use either *htpasswd_auth* or *rh-sso*. The former is still available because it is present in the */etc/origin/master/master-config.yaml*. Navigate to the OpenShift web console, which in this example is _https://openshift.example.com:8443/console_. The OpenShift login page now has the option to use either *htpasswd_auth* or *rh-sso*. The former is still available because it is present in the */etc/origin/master/master-config.yaml*.
Select *rh-sso* and log in to OpenShift with the _testuser_ user created earlier in RH-SSO. No projects are visible to _testuser_ until they are added in the OpenShift CLI. This is the only way to provide user privileges in OpenShift because it currently does not accept external role mapping. Select *rh-sso* and log in to OpenShift with the _testuser_ user created earlier in {project_name_abbr}. 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: To provide _testuser_ `view` privileges for the _sso-app-demo_, use the OpenShift CLI:
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
@ -849,15 +849,15 @@ $ oadm policy add-role-to-user view testuser -n sso-app-demo
---- ----
[[Example-EAP-Auto]] [[Example-EAP-Auto]]
=== Example Workflow: Automatically Registering EAP Application in RH-SSO with OpenID-Connect Client === Example Workflow: Automatically Registering EAP Application in {project_name_abbr} with OpenID-Connect Client
This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which RH-SSO was deployed on OpenShift. This example prepares RH-SSO realm, role, and user credentials for an EAP project using an OpenID-Connect client adapter. These credentials are then provided in the EAP for OpenShift template for automatic RH-SSO client registration. Once deployed, the RH-SSO user can be used to authenticate and access JBoss EAP. This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name_abbr} was deployed on OpenShift. This example prepares {project_name_abbr} realm, role, and user credentials for an EAP project using an OpenID-Connect client adapter. These credentials are then provided in the EAP for OpenShift template for automatic {project_name_abbr} client registration. Once deployed, the {project_name_abbr} user can be used to authenticate and access JBoss EAP.
[NOTE] [NOTE]
==== ====
This example uses a OpenID-Connect client but an SAML client could also be used. See xref:SSO-Clients[RH-SSO Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual RH-SSO Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients. This example uses a OpenID-Connect client but an SAML client could also be used. See xref:SSO-Clients[{project_name_abbr} Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual {project_name_abbr} Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients.
==== ====
==== Preparing RH-SSO Authentication for OpenShift Deployment ==== Preparing {project_name_abbr} Authentication for OpenShift Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
. Create a new project: . Create a new project:
@ -866,7 +866,7 @@ Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
---- ----
$ oc new-project eap-app-demo $ oc new-project eap-app-demo
---- ----
//. Create a service account to be used for the RH-SSO deployment: //. Create a service account to be used for the {project_name_abbr} deployment:
//+ //+
//[subs="verbatim,macros,attributes"] //[subs="verbatim,macros,attributes"]
//---- //----
@ -906,8 +906,8 @@ $ oc secret new eap-jgroup-secret eapjgroups.jceks
$ oc secrets link default eap-ssl-secret eap-jgroup-secret $ oc secrets link default eap-ssl-secret eap-jgroup-secret
---- ----
==== Preparing the RH-SSO Credentials ==== Preparing the {project_name_abbr} Credentials
Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the RH-SSO deployment. Log in to the encrypted {project_name_abbr} web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the {project_name_abbr} deployment.
*Create a Realm* *Create a Realm*
@ -916,11 +916,11 @@ Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$_<project-n
*Copy the Public Key* *Copy the Public Key*
In the newly created _eap-demo_ realm, click the *Keys* tab and copy the generated public key. This example uses the variable _<realm-public-key>_ for brevity. This is used later to deploy the RH-SSO-enabled JBoss EAP image. In the newly created _eap-demo_ realm, click the *Keys* tab and copy the generated public key. This example uses the variable _<realm-public-key>_ for brevity. This is used later to deploy the {project_name_abbr}-enabled JBoss EAP image.
*Create a Role* *Create a Role*
Create a role in RH-SSO with a name that corresponds to the JEE role defined in the *web.xml* of the example EAP application. This role is assigned to an RH-SSO _application user_ to authenticate access to user applications. Create a role in {project_name_abbr} with a name that corresponds to the JEE role defined in the *web.xml* of the example EAP application. This role is assigned to an {project_name_abbr} _application user_ to authenticate access to user applications.
. Click *Roles* in the *Configure* sidebar to list the roles for this realm. This is a new realm, so there should only be the default _offline_access_ role. . Click *Roles* in the *Configure* sidebar to list the roles for this realm. This is a new realm, so there should only be the default _offline_access_ role.
. Click *Add Role*. . Click *Add Role*.
@ -929,7 +929,7 @@ Create a role in RH-SSO with a name that corresponds to the JEE role defined in
*Create Users and Assign Roles* *Create Users and Assign Roles*
Create two users: Create two users:
- Assign the _realm management user_ the *realm-management* roles to handle automatic RH-SSO client registration in the RH-SSO server. - Assign the _realm management user_ the *realm-management* roles to handle automatic {project_name_abbr} client registration in the {project_name_abbr} server.
- Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications. - Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications.
Create the _realm management user_: Create the _realm management user_:
@ -938,7 +938,7 @@ Create the _realm management user_:
. Click *Add User*. . Click *Add User*.
. Enter a valid *Username* (this example uses the user _eap-mgmt-user_) and click *Save*. . Enter a valid *Username* (this example uses the user _eap-mgmt-user_) and click *Save*.
. Edit the user configuration. Click the *Credentials* tab in the user space and enter a password for the user. After the password has been confirmed you can click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation. . Edit the user configuration. Click the *Credentials* tab in the user space and enter a password for the user. After the password has been confirmed you can click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation.
. Click *Role Mappings* to list the realm and client role configuration. In the *Client Roles* drop-down menu, select *realm-management* and add all of the available roles to the user. This provides the user RH-SSO server rights that can be used by the JBoss EAP image to create clients. . Click *Role Mappings* to list the realm and client role configuration. In the *Client Roles* drop-down menu, select *realm-management* and add all of the available roles to the user. This provides the user {project_name_abbr} server rights that can be used by the JBoss EAP image to create clients.
Create the _application user_: Create the _application user_:
@ -948,11 +948,11 @@ Create the _application user_:
. Edit the user configuration. Click the *Credentials* tab in the user space and enter a password for the user. After the password has been confirmed you can click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation. . Edit the user configuration. Click the *Credentials* tab in the user space and enter a password for the user. After the password has been confirmed you can click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation.
. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, add the role created earlier. . Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, add the role created earlier.
==== Deploy the RH-SSO-enabled JBoss EAP Image ==== Deploy the {project_name_abbr}-enabled JBoss EAP Image
. Return to the OpenShift web console and click *Add to project* to list the default image streams and templates. . Return to the OpenShift web console and click *Add to project* to list the default image streams and templates.
. Use the *Filter by keyword* search bar to limit the list to those that match _sso_. You may need to click *See all* to show the desired application template. . Use the *Filter by keyword* search bar to limit the list to those that match _sso_. You may need to click *See all* to show the desired application template.
. Select the *_eap71-sso-s2i_* image to list all of the deployment parameters. Include the following RH-SSO parameters to configure the RH-SSO credentials during the EAP build: . Select the *_eap71-sso-s2i_* image to list all of the deployment parameters. Include the following {project_name_abbr} parameters to configure the {project_name_abbr} credentials during the EAP build:
+ +
[cols="2*", options="header"] [cols="2*", options="header"]
|=== |===
@ -1007,25 +1007,25 @@ Create the _application user_:
It may take several minutes for the JBoss EAP image to deploy. It may take several minutes for the JBoss EAP image to deploy.
==== Log in to the JBoss EAP Server Using RH-SSO ==== Log in to the JBoss EAP Server Using {project_name_abbr}
. Access the JBoss EAP application server and click *Login*. You are redirected to the RH-SSO login. . Access the JBoss EAP application server and click *Login*. You are redirected to the {project_name_abbr} login.
. Log in using the RH-SSO user created in the example. You are authenticated against the RH-SSO server and returned to the JBoss EAP application server. . Log in using the {project_name_abbr} user created in the example. You are authenticated against the {project_name_abbr} server and returned to the JBoss EAP application server.
[[Example-EAP-Manual]] [[Example-EAP-Manual]]
=== Example Workflow: Manually Registering EAP Application in RH-SSO with SAML Client === Example Workflow: Manually Registering EAP Application in {project_name_abbr} with SAML Client
This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which RH-SSO was deployed on OpenShift. This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name_abbr} was deployed on OpenShift.
This example prepares RH-SSO realm, role, and user credentials for an EAP project and configures an EAP for OpenShift deployment. Once deployed, the RH-SSO user can be used to authenticate and access JBoss EAP. This example prepares {project_name_abbr} realm, role, and user credentials for an EAP project and configures an EAP for OpenShift deployment. Once deployed, the {project_name_abbr} user can be used to authenticate and access JBoss EAP.
[NOTE] [NOTE]
==== ====
This example uses a SAML client but an OpenID-Connect client could also be used. See xref:SSO-Clients[RH-SSO Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual RH-SSO Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients. This example uses a SAML client but an OpenID-Connect client could also be used. See xref:SSO-Clients[{project_name_abbr} Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual {project_name_abbr} Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients.
==== ====
==== Preparing the RH-SSO Credentials ==== Preparing the {project_name_abbr} Credentials
Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the RH-SSO deployment. Log in to the encrypted {project_name_abbr} web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the {project_name_abbr} deployment.
*Create a Realm* *Create a Realm*
@ -1034,11 +1034,11 @@ Log in to the encrypted RH-SSO web server at *$$https://secure-sso-$$_<project-n
*Copy the Public Key* *Copy the Public Key*
In the newly created _saml-demo_ realm, click the *Keys* tab and copy the generated public key. This example uses the variable _realm-public-key_ for brevity. This is needed later to deploy the RH-SSO-enabled JBoss EAP image. In the newly created _saml-demo_ realm, click the *Keys* tab and copy the generated public key. This example uses the variable _realm-public-key_ for brevity. This is needed later to deploy the {project_name_abbr}-enabled JBoss EAP image.
*Create a Role* *Create a Role*
Create a role in RH-SSO with a name that corresponds to the JEE role defined in the *web.xml* of the example EAP application. This role will be assigned to an RH-SSO _application user_ to authenticate access to user applications. Create a role in {project_name_abbr} with a name that corresponds to the JEE role defined in the *web.xml* of the example EAP application. This role will be assigned to an {project_name_abbr} _application user_ to authenticate access to user applications.
. Click *Roles* in the *Configure* sidebar to list the roles for this realm. This is a new realm, so there should only be the default _offline_access_ role. . Click *Roles* in the *Configure* sidebar to list the roles for this realm. This is a new realm, so there should only be the default _offline_access_ role.
. Click *Add Role*. . Click *Add Role*.
@ -1047,7 +1047,7 @@ Create a role in RH-SSO with a name that corresponds to the JEE role defined in
*Create Users and Assign Roles* *Create Users and Assign Roles*
Create two users: Create two users:
- Assign the _realm management user_ the *realm-management* roles to handle automatic RH-SSO client registration in the RH-SSO server. - Assign the _realm management user_ the *realm-management* roles to handle automatic {project_name_abbr} client registration in the {project_name_abbr} server.
- Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications. - Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications.
Create the _realm management user_: Create the _realm management user_:
@ -1058,7 +1058,7 @@ Create the _realm management user_:
. Edit the user configuration. Click the *Credentials* tab in the user space and enter a password for the user. After the password has been confirmed you can click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation. . Edit the user configuration. Click the *Credentials* tab in the user space and enter a password for the user. After the password has been confirmed you can click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation.
//// ////
Need for the SAML? Need for the SAML?
. Click *Role Mappings* to list the realm and client role configuration. In the *Client Roles* drop-down menu, select *realm-management* and add all of the available roles to the user. This provides the user RH-SSO server rights that can be used by the JBoss EAP image to create clients. . Click *Role Mappings* to list the realm and client role configuration. In the *Client Roles* drop-down menu, select *realm-management* and add all of the available roles to the user. This provides the user {project_name_abbr} server rights that can be used by the JBoss EAP image to create clients.
//// ////
Create the _application user_: Create the _application user_:
@ -1071,7 +1071,7 @@ Create the _application user_:
*Create and Configure a SAML Client*: *Create and Configure a SAML Client*:
Clients are RH-SSO entities that request user authentication. This example configures a SAML client to handle authentication for the EAP application. This section saves two files, *keystore.jks* and *keycloak-saml-subsystem.xml* that are needed later in the procedure. Clients are {project_name_abbr} entities that request user authentication. This example configures a SAML client to handle authentication for the EAP application. This section saves two files, *keystore.jks* and *keycloak-saml-subsystem.xml* that are needed later in the procedure.
Create the SAML Client: Create the SAML Client:
@ -1105,7 +1105,7 @@ Download the Client Adapter:
The *keystore-saml.jks* will be used with the other EAP keystores in the next section to create an OpenShift secret for the EAP application project. Copy the *keystore-saml.jks* file to an OpenShift node. + The *keystore-saml.jks* will be used with the other EAP keystores in the next section to create an OpenShift secret for the EAP application project. Copy the *keystore-saml.jks* file to an OpenShift node. +
The *keycloak-saml-subsystem.xml* will be modified and used in the application deployment. Copy it into the */configuration* folder of the application as *secure-saml-deployments*. The *keycloak-saml-subsystem.xml* will be modified and used in the application deployment. Copy it into the */configuration* folder of the application as *secure-saml-deployments*.
==== Preparing RH-SSO Authentication for OpenShift Deployment ==== Preparing {project_name_abbr} Authentication for OpenShift Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role. Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
. Create a new project: . Create a new project:
@ -1158,7 +1158,7 @@ $ oc secrets link default eap-ssl-secret eap-jgroup-secret
[[modified-saml-xml]] [[modified-saml-xml]]
==== Modifying the *secure-saml-deployments* File ==== Modifying the *secure-saml-deployments* File
The *keycloak-saml-subsystem.xml*, exported from the RH-SSO client in a previous section, should have been copied into the */configuration* folder of the application and renamed *secure-saml-deployments*. EAP searches for this file when it starts and copies it to the *standalone-openshift.xml* file inside the RH-SSO SAML adapter configuration. The *keycloak-saml-subsystem.xml*, exported from the {project_name_abbr} client in a previous section, should have been copied into the */configuration* folder of the application and renamed *secure-saml-deployments*. EAP searches for this file when it starts and copies it to the *standalone-openshift.xml* file inside the {project_name_abbr} SAML adapter configuration.
. Open the */configuration/secure-saml-deployments* file in a text editor. . Open the */configuration/secure-saml-deployments* file in a text editor.
. Replace the *YOUR-WAR.war* value of the *secure-deployment name* tag with the application *.war* file. This example uses _sso-saml-demo.war_. . Replace the *YOUR-WAR.war* value of the *secure-deployment name* tag with the application *.war* file. This example uses _sso-saml-demo.war_.
@ -1179,7 +1179,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 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. The aliases and passwords for the *PrivateKey* and the *Certificate* were configured when the SAML Keys were exported from the {project_name_abbr} client.
. Delete the second *<CertificatePem>* tag and key and replace it with the the realm certificate information: . Delete the second *<CertificatePem>* tag and key and replace it with the the realm certificate information:
+ +
[subs="verbatim,macros,attributes"] [subs="verbatim,macros,attributes"]
@ -1195,7 +1195,7 @@ The aliases and passwords for the *PrivateKey* and the *Certificate* were config
... ...
---- ----
+ +
The certificate alias and password were configured when the SAML Keys were exported from the RH-SSO client. The certificate alias and password were configured when the SAML Keys were exported from the {project_name_abbr} client.
. Save and close the */configuration/secure-saml-deployments* file. . Save and close the */configuration/secure-saml-deployments* file.
==== Configuring SAML Client Registration in the Application *web.xml* ==== Configuring SAML Client Registration in the Application *web.xml*
@ -1214,4 +1214,4 @@ Open the application *web.xml* file and ensure it includes the following:
==== Deploying the Application ==== Deploying the Application
You do not need to include any RH-SSO configuration for the image because that has been configured in the application itself. Navigating to the application login page redirects you to the RH-SSO login. Log in to the application through RH-SSO using the _application user_ user created earlier. You do not need to include any {project_name_abbr} configuration for the image because that has been configured in the application itself. Navigating to the application login page redirects you to the {project_name_abbr} login. Log in to the application through {project_name_abbr} using the _application user_ user created earlier.

2
topics/templates/document-attributes-product.adoc
View file

@ -11,6 +11,7 @@ ifeval::[{project_product_cd}==false]
:project_name_full: Red Hat Single Sign-On :project_name_full: Red Hat Single Sign-On
:project_version: 7.3.0.GA :project_version: 7.3.0.GA
:project_versionDoc: 7.3 :project_versionDoc: 7.3
:project_previous_version: 7.2
:project_previous_templates_version: sso-cd :project_previous_templates_version: sso-cd
:project_templates_version: sso73 :project_templates_version: sso73
:project_latest_image_tag: 1.0 :project_latest_image_tag: 1.0
@ -22,6 +23,7 @@ ifeval::[{project_product_cd}==true]
:project_name_full: Red Hat Single Sign-On Continuous Delivery :project_name_full: Red Hat Single Sign-On Continuous Delivery
:project_version: 7.3.0.CD05 :project_version: 7.3.0.CD05
:project_versionDoc: 7.3.0.cd05 :project_versionDoc: 7.3.0.cd05
:project_previous_version: 7.2
:project_previous_templates_version: sso72 :project_previous_templates_version: sso72
:project_templates_version: sso-cd :project_templates_version: sso-cd
:project_latest_image_tag: 1.0 :project_latest_image_tag: 1.0