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

Fixing a broken link

Browse source
This commit is contained in:
AndyMunro 2021-10-08 11:48:44 -04:00 committed by Bruno Oliveira da Silva
parent a6b5d35508
commit 6fe1e55c53
7 changed files with 392 additions and 255 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
openshift/topics.adoc
View file

@ -2,8 +2,6 @@ include::topics/templates/making-open-source-more-inclusive.adoc[]
include::topics/introduction.adoc[leveloffset=+0]
include::topics/before_you_begin.adoc[leveloffset=+0]
include::topics/get_started.adoc[leveloffset=+0]
include::topics/advanced_concepts.adoc[leveloffset=+0]

162
openshift/topics/advanced_concepts.adoc
View file

@ -1,11 +1,16 @@
== Advanced Concepts
== Performing advanced procedures
These cover additional configuration topics, such as seting up keystores and a truststore for the {project_name} server, creating an administrator account, an overview of available {project_name} client registration methods, and guidance on configuring clustering.
[role="_abstract"]
This chapter describes advanced procedures, such as setting up keystores and a truststore for the {project_name} server, creating an administrator account, as well as an overview of available {project_name} client registration methods, and guidance on configuring clustering.
=== Requirements and Deploying xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination] {project_name} Templates
=== Deploying passthrough TLS termination templates
==== Preparing the Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
You can deploy using these templates. They require HTTPS, JGroups keystores and the {project_name} server truststore to already exist, and therefore can be used to instantiate the {project_name} server pod using your custom HTTPS, JGroups keystores and {project_name} server truststore.
==== Preparing the deployment
.Procedure
. Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
. Create a new project:
+
@ -23,22 +28,28 @@ $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
[[Configuring-Keystores]]
==== Creating HTTPS and JGroups Keystores, and Truststore for the {project_name} Server
The {project_name} application templates using xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] require:
In this procedure, the *_openssl_* toolkit is used to generate a CA certificate to sign the HTTPS keystore, and create a truststore for the {project_name} server. The *_keytool_*, a package *included with the Java Development Kit*, is then used to generate self-signed certificates for these keystores.
The {project_name} application templates using xref:../introduction/introduction.adoc#reencrypt-templates[re-encryption TLS termination] do not *require* or *expect* the HTTPS and JGroups keystores and {project_name} server truststore to be prepared beforehand.
====
[NOTE]
If you want to provision the {project_name} server using existing HTTPS / JGroups keystores, use some of the passthrough templates instead.
====
The re-encryption templates use OpenShift's internal link:{ocpdocs_serving_x509_secrets_link}[service serving x509 certificate secrets] to automatically create the HTTPS and JGroups keystores.
The {project_name} 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} server is pre-populated with the all known, trusted CA certificate files found in the Java system path.
.Prerequisites
The {project_name} application templates using passthrough TLS termination require the following to be deployed:
* 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
* xref:create-server-truststore[{project_name} server truststore] used for securing the {project_name} requests
the {project_openshift_product_name} image to be deployed properly.
[IMPORTANT]
====
The {project_name} 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} server truststore to be prepared beforehand. The templates use OpenShift's internal link:{ocpdocs_serving_x509_secrets_link}[service serving x509 certificate secrets] to automatically create the HTTPS and JGroups keystores. The {project_name} 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} 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 {project_name} server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores.
[WARNING]
[NOTE]
====
For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS).
@ -49,7 +60,10 @@ See the https://access.redhat.com/documentation/en-us/jboss_enterprise_applicati
*_Create the HTTPS keystore:_*
[[generate-ca-certificate]]
.. Generate a CA certificate. Pick and remember the password. Provide identical password, when xref:signing-csr-with-ca-certificate[signing the certificate sign request with the CA certificate] below:
.Procedure
. Generate a CA certificate. Pick and remember the password. Provide identical password, when xref:signing-csr-with-ca-certificate[signing the certificate sign request with the CA certificate] below:
+
[source,bash,subs="attributes+,macros+"]
----
@ -61,7 +75,7 @@ $ openssl req -new -newkey rsa:4096 -x509 -keyout xpaas.key -out xpaas.crt -days
----
$ keytool -genkeypair -keyalg RSA -keysize 2048 -dname "CN=secure-sso-sso-app-demo.openshift.example.com" -alias jboss -keystore keystore.jks
----
.. Generate a certificate sign request for the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
. Generate a certificate sign request for the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
+
[source,bash,subs="attributes+,macros+"]
----
@ -70,19 +84,19 @@ $ keytool -certreq -keyalg rsa -alias jboss -keystore keystore.jks -file sso.csr
[[signing-csr-with-ca-certificate]]
[start=4]
.. Sign the certificate sign request with the CA certificate. Provide the same password that was used to xref:generate-ca-certificate[generate the CA certificate]:
. Sign the certificate sign request with the CA certificate. Provide the same password that was used to xref:generate-ca-certificate[generate the CA certificate]:
+
[source,bash,subs="attributes+,macros+"]
----
$ openssl x509 -req -CA xpaas.crt -CAkey xpaas.key -in sso.csr -out sso.crt -days 365 -CAcreateserial
----
.. Import the CA certificate into the HTTPS keystore. Provide `mykeystorepass` as the keystore password. Reply `yes` to `Trust this certificate? [no]:` question:
. Import the CA certificate into the HTTPS keystore. Provide `mykeystorepass` as the keystore password. Reply `yes` to `Trust this certificate? [no]:` question:
+
[source,bash,subs="attributes+,macros+"]
----
$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore keystore.jks
----
.. Import the signed certificate sign request into the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
. Import the signed certificate sign request into the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
+
[source,bash,subs="attributes+,macros+"]
----
@ -110,9 +124,11 @@ $ keytool -import -file xpaas.crt -alias xpaas.ca -keystore truststore.jks
----
[[Configuring-Secrets]]
==== Secrets
==== Creating secrets
OpenShift uses objects called link:{ocpdocs_secrets_link}[secrets] to hold sensitive information, such as passwords or keystores.
.Procedure
You create objects called secrets that OpenShift uses to hold sensitive information, such as passwords or keystores.
. Create the secrets for the HTTPS and JGroups keystores, and {project_name} server truststore, generated in the xref:Configuring-Keystores[previous section].
+
@ -120,29 +136,32 @@ OpenShift uses objects called link:{ocpdocs_secrets_link}[secrets] to hold sensi
----
$ oc create secret generic sso-app-secret --from-file=keystore.jks --from-file=jgroups.jceks --from-file=truststore.jks
----
. Link these secrets to the link:{ocpdocs_default_service_accounts_link}[default] service account, which is used to run {project_name} pods.
. Link these secrets to the default service account, which is used to run {project_name} pods.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc secrets link default sso-app-secret
----
==== Deploying the Chosen {project_name} Passthrough TLS Template via OpenShift CLI
[role="_additional-resources"]
.Additional resources
* link:{ocpdocs_secrets_link}[What is a secret?]
* link:{ocpdocs_default_service_accounts_link}[Default project service accounts and roles]
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:
==== Deploying a Passthrough TLS template using the OpenShift CLI
[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_* {project_name} application template.
After you create xref:Configuring-Keystores[keystores] and xref:Configuring-Secrets[secrets], deploy a passthrough TLS termination template by using the `oc` command.
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} server, and passwords for the HTTPS and JGroups keystores, and the truststore of the {project_name} server.
===== `oc` command guidelines
In the following `oc` command, the values of *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, *_HTTPS_PASSWORD_*, *_JGROUPS_ENCRYPT_PASSWORD_*, and *_SSO_TRUSTSTORE_PASSWORD_* variables match the default values in the *_{project_templates_version}-https_* {project_name} application template.
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.
====
For production environments, Red Hat recommends that you consult the on-site policy for your organization for guidance on generating a strong user name and password for the administrator user account of the {project_name} server, and passwords for the HTTPS and JGroups keystores, and the truststore of the {project_name} server.
Also, when you create the template, make the passwords match the passwords provided when you created the keystores. If you used a different username or password, modify the values of the parameters in your template to match your environment.
[NOTE]
====
The following commands using the *_keytool_*, a package *included with the Java Development Kit*, can be used to determine the names associated with the certificate:
You can determine the alias names associated with the certificate by using the following *_keytool_* commands. The *_keytool_* is a package included with the Java Development Kit.
[source,bash,subs="attributes+,macros+"]
----
@ -159,10 +178,11 @@ Enter keystore password: password
Alias name: secret-key
----
Finally, the *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, and the *_SSO_REALM_* template parameters in the following command are optional.
The *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, and the *_SSO_REALM_* template parameters in the following command are optional.
====
[[advanced-topics-deploy-{project_templates_version}-https-template]]
===== Sample `oc` command
[source,bash,subs="attributes+,macros+"]
----
$ oc new-app --template={project_templates_version}-https \
@ -227,6 +247,10 @@ $ oc new-app --template={project_templates_version}-https \
Run 'oc status' to view your app.
----
[role="_additional-resources"]
.Additional resources
* xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination]
[[advanced-concepts-sso-hostname-spi-setup]]
=== Customizing the Hostname for the {project_name} Server
@ -241,6 +265,8 @@ For backward compatibility, `SSO_FRONTEND_URL` settings is ignored if `SSO_HOSTN
Another option of hostname provider is `fixed`, which allows configuring a fixed hostname. The latter makes sure that only valid hostnames can be used and allows internal applications to invoke the {project_name} server through an alternative URL.
.Procedure
Run the following commands to set the `fixed` hostname SPI provider for the {project_name} server:
. Deploy the {project_openshift_product_name} image with *_SSO_HOSTNAME_* environment variable set to the desired hostname of the {project_name} server.
@ -282,7 +308,7 @@ route "sso" patched
{project_name} can be configured to connect to an external (to OpenShift cluster) database. In order to achieve this, you need to modify the `sso-{database name}` Endpoints object to point to the proper address. The procedure is described in the link:{ocpdocs_ingress_service_external_ip_link}[OpenShift manual].
Tip: The easiest way to get started is to deploy {project_name} from a template and then modify the Endpoints object. You might also need to update some of the datasource configuration variables in the DeploymentConfig. Once you're done, just roll a new deployment out.
The easiest way to get started is to deploy {project_name} from a template and then modify the Endpoints object. You might also need to update some of the datasource configuration variables in the DeploymentConfig. Once you're done, just roll a new deployment out.
[[sso-using-custom-jdbc-driver]]
=== Using Custom JDBC Driver
@ -293,6 +319,8 @@ database, you need to extend the {project_name} image with a custom JDBC driver
it and set up the connection properties. The following steps illustrate how to do that, taking MariaDB driver
as an example. Update the example for other database drivers accordingly.
.Procedure
. Create an empty directory.
. Download the JDBC driver binaries into this directory.
. Create a new `Dockerfile` file in this directory with the following contents. For other databases, replace `mariadb-java-client-2.5.4.jar` with the filename of the respective driver:
@ -351,7 +379,7 @@ podman build -t docker-registry-default/project/name:tag .
[[sso-administrator-setup]]
=== Creating the Administrator Account for {project_name} Server
{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}.
{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 performing 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:
@ -360,21 +388,16 @@ The administrator account can be created:
[NOTE]
====
{project_name} allows an initial administrator account to be created 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 localhost; this method of administrator account creation is not applicable for the {project_openshift_product_name} image.
{project_name} allows an initial administrator account to be created by the link:{project_doc_base_url}/getting_started_guide/index#create-admin_[Welcome Page] web form, but only if the Welcome Page is accessed from localhost; this method of administrator account creation is not applicable for the {project_openshift_product_name} image.
====
[[sso-admin-template-parameters]]
==== Creating the Administrator Account Using Template Parameters
==== Creating the Administrator Account using template parameters
When deploying {project_name} application template, the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the {project_name} server's administrator account to be created for the `master` realm.
[NOTE]
====
*Both of these parameters are required.* If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated.
====
[IMPORTANT]
====
The lifespan of the {project_name} server's administrator account depends upon the storage type used to store the {project_name} 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 {project_name} pod (stored account data is lost upon pod destruction),
@ -382,15 +405,11 @@ The lifespan of the {project_name} server's administrator account depends upon t
* For persistent database mode (*_{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} and the database pods are destructed.
It is a common practice to deploy an {project_name} 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} application needs to be instantiated).
====
[WARNING]
====
In the case of *ephemeral or persistent database mode*, after creating the RH_SSO server's administrator account, remove the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables from the deployment config before deploying new {project_name} applications.
====
[IMPORTANT]
====
.Procedure
Run the following commands to prepare the previously created deployment config of the {project_name} application for reuse after the administrator account has been created:
. Identify the deployment config of the {project_name} application.
@ -409,12 +428,17 @@ $ oc set env dc/sso \
-e SSO_ADMIN_USERNAME="" \
-e SSO_ADMIN_PASSWORD=""
----
====
[[sso-admin-remote-shell]]
==== Creating the Administrator Account via Remote Shell Session to {project_name} Pod
==== Creating the Administrator Account via a remote shell session to {project_name} Pod
Run following commands to create an administrator account for the `master` realm of the {project_name} 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} application pod has been started:
You use the following commands to create an administrator account for the `master` realm of the {project_name} server, when deploying the {project_openshift_product_name} image directly from the image stream without using a template.
.Prerequisite
* {project_name} application pod has been started.
.Procedure
. Identify the {project_name} application pod.
+
@ -463,8 +487,11 @@ sh-4.2$ ./jboss-cli.sh --connect ':reload'
====
When restarting the server it is important to restart just the JBoss EAP process within the running {project_name} container, and not the whole container. This is because restarting the whole container will recreate it from scratch, without the {project_name} server administration account for the `master` realm.
====
. Log in to the `master` realm's administration console of the {project_name} 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} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server, and specify the user name and password used to create the administrator user.
. Log in to the `master` realm's Admin Console of the {project_name} 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} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server, and specify the user name and password used to create the administrator user.
[role="_additional-resources"]
.Additional resources
* xref:../introduction/introduction.adoc#sso-templates[Templates for use with this software]
=== Customizing the default behavior of the {project_name} image
@ -472,7 +499,7 @@ You can change the default behavior of the {project_name} image such as enabling
.Prerequisites
This procedure assumes that the {project_openshift_product_name} image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:]
This procedure assumes that the {project_openshift_product_name} image has been previously xref:Example-Deploying-SSO[deployed using one of the following templates:]
* *_{project_templates_version}-postgresql_*
* *_{project_templates_version}-postgresql-persistent_*
@ -530,7 +557,7 @@ deploymentconfig "sso" scaled
. Test a TechPreview feature of your choice.
=== 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 {project_name} servers. The *_{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} web server.
@ -539,15 +566,16 @@ After the {project_name} web server pod has started, it can be accessed at its c
* *\http://sso-_<project-name>_._<hostname>_/auth/admin*: for the {project_name} web server, and
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted {project_name} web server.
Use the xref:sso-administrator-setup[administrator user credentials] to log in into the `master` realm's administration console.
Use the xref:sso-administrator-setup[administrator user credentials] to log in into the `master` realm's Admin Console.
[[SSO-Clients]]
=== {project_name} Clients
=== {project_name} clients
Clients are {project_name} entities that request user authentication. A client can be an application requesting {project_name} 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.
Clients are {project_name} entities that request user authentication. A client can be an application requesting {project_name} 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:{project_doc_base_url}/server_administration_guide/index#assembly-managing-clients_server_administration_guide[Managing Clients chapter of the {project_name} documentation] for more information.
{project_name} 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:
{project_name} provides link:{project_doc_base_url}/server_administration_guide/clients#oidc_clients[OpenID-Connect] and link:{project_doc_base_url}/server_administration_guide/index#client-saml-configuration[SAML] client protocols.
+
OpenID-Connect is the preferred protocol and uses three different access types:
- *public*: Useful for JavaScript applications that run directly in the browser and require no server configuration.
- *confidential*: Useful for server-side clients, such as EAP web applications, that need to perform a browser login.
@ -570,12 +598,12 @@ The following is an example snippet for the application *web.xml* to configure a
----
[[Auto-Man-Client-Reg]]
==== Automatic and Manual {project_name} Client Registration Methods
==== Automatic and manual {project_name} client registration methods
A client application can be automatically registered to an {project_name} 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 {project_name} client adapter and including it in the client application configuration.
===== Automatic {project_name} Client Registration
===== Automatic {project_name} client registration
Automatic {project_name} client registration is determined by {project_name} environment variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. The {project_name} credentials supplied in the template are then used to register the client to the {project_name} realm during deployment of the client application.
@ -634,7 +662,7 @@ If the {project_name} client uses the SAML protocol, the following additional va
See xref:Example-EAP-Auto[Example Workflow: Automatically Registering EAP Application in {project_name} with OpenID-Connect Client] for an end-to-end example of the automatic client registration method using an OpenID-Connect client.
===== Manual {project_name} Client Registration
===== Manual {project_name} client registration
Manual {project_name} 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} web console. The name of this file is different for OpenID-Connect and SAML clients:
@ -654,9 +682,11 @@ See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application
=== Using {project_name} vault with OpenShift secrets
Several fields in the {project_name} administration support obtaining the value
of a secret from an external vault, see link:{adminguide_link}#_vault-administration[{adminguide_name}].
The following example shows how to set up the files plaintext vault in OpenShift
The following example shows how to set up the file-based plaintext vault in OpenShift
and set it up to be used for obtaining an SMTP password.
.Procedure
. Specify a directory for the vault using the *_SSO_VAULT_DIR_* environment variable.
You can introduce the *_SSO_VAULT_DIR_* environment variable directly in the environment in your deployment configuration. It can also be included in the template by addding the following snippets at the appropriate places in the template:
+
@ -712,8 +742,6 @@ created in this tutorial, you can use `${vault.smtp-password}` within the `maste
realm in the configuration of the smtp password and it will be replaced by `mySMTPPsswd` when used.
=== Limitations
OpenShift does not currently accept OpenShift role mapping from external providers. If {project_name} is used as an authentication gateway for OpenShift, users created in {project_name} must have the roles added using the OpenShift Administrator `oc adm policy` command.

26
openshift/topics/before_you_begin.adoc
View file

@ -1,26 +0,0 @@
== Before You Begin
=== Comparison: {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 {project_name}. In addition, the {project_name}-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
See the xPaaS part of the https://access.redhat.com/articles/2176281[OpenShift and Atomic Platform Tested Integrations page] for details about OpenShift image version compatibility.
=== Deprecated Image Streams and Application Templates for {project_openshift_product_name}
[IMPORTANT]
====
The {project_openshift_product_name} image version number between 7.0 and 7.3 are deprecated and they will no longer receive updates of image and application templates.
*To deploy new applications, it is recommended to use the version 7.4 or {project_version} of the {project_openshift_product_name} image along with the application templates specific to these image versions.*
====
=== Initial Setup
The Tutorials in this guide follow on from and assume an OpenShift instance similar to that created by performing link:{ocpdocs_install_cluster_link}[the installation of the OpenShift Container Platform cluster].
[IMPORTANT]
====
For information related to updating the existing database when migrating {project_openshift_product_name} image from previous versions to version {project_version}, see the xref:upgrading-sso-db-from-previous-version[Updating Existing Database when Migrating {project_openshift_product_name} Image to a new version] section.
====

85
openshift/topics/get_started.adoc
View file

@ -1,15 +1,16 @@
== Get Started
== Configuring {project_openshift_product_name}
[id="image-streams-applications-templates"]
=== Using the {project_openshift_product_name} Image Streams and Application Templates
=== Using the {project_openshift_product_name} Image Streams and application templates
[IMPORTANT]
====
Red Hat JBoss Middleware for OpenShift images are pulled on demand from the secured Red Hat Registry: link:https://catalog.redhat.com[registry.redhat.io], which requires authentication. To retrieve content, you will need to log into the registry using the Red Hat account.
[role="_abstract"]
Red Hat JBoss Middleware for OpenShift images are pulled on demand from the secured Red Hat Registry: link://https://catalog.redhat.com/[registry.redhat.io], which requires authentication. To retrieve content, you will need to log into the registry using the Red Hat account.
To consume container images from *_registry.redhat.io_* in shared environments such as OpenShift, it is recommended for an administrator to use a Registry Service Account, also referred to as authentication tokens, in place of an individual person's Red Hat Customer Portal credentials.
To create a Registry Service Account, navigate to the link:https://access.redhat.com/terms-based-registry/[Registry Service Account Management Application], and log in if necessary.
.Procedure
. To create a Registry Service Account, navigate to the link:https://access.redhat.com/terms-based-registry/[Registry Service Account Management Application], and log in if necessary.
. From the *_Registry Service Accounts_* page, click *_Create Service Account_*.
. Provide a name for the Service Account, for example *_registry.redhat.io-sa_*. It will be prepended with a fixed, random string.
@ -19,9 +20,10 @@ To create a Registry Service Account, navigate to the link:https://access.redhat
. Finally, click the *_OpenShift Secret_* tab, and perform all steps listed on that page.
See the link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication] article for more information.
====
. Ensure that you are logged in as a cluster administrator or a user with project administrator access to the global openshift project:
.Procedure
. Ensure that you are logged in as a cluster administrator or a user with project administrator access to the global `openshift` project:
. Choose a command based on your version of OpenShift Container Platform.
@ -63,8 +65,11 @@ $ oc -n openshift import-image {openshift_image_repository}:{project_latest_imag
[[Example-Deploying-SSO]]
=== Deploying the {project_name} Image
[[Preparing-SSO-Authentication-for-OpenShift-Deployment]]
==== Preparing the Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
==== Preparing for the deployment
.Procedure
. Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
. Create a new project:
+
@ -72,17 +77,30 @@ Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
----
$ oc new-project sso-app-demo
----
. Add the `view` role to the link:{ocpdocs_default_service_accounts_link}[`default`] service account. This enables the service account to view all the resources in the sso-app-demo namespace, which is necessary for managing the cluster.
. Add the `view` role to the link:{ocpdocs_default_service_accounts_link}[`default`] service account. This enables the service account to view all the resources in the *sso-app-demo* namespace, which is necessary for managing the cluster.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
----
==== Deploying the {project_name} Image using the Application Template
==== Deploying the {project_name} Image using the application template
You can deploy the template using one of these interfaces:
* xref:deploy_cli[OpenShift CLI]
* xref:deploy3x[OpenShift 3.x web console]
* xref:deploy4x[OpenShift 4.x web console]
[id="deploy_cli"]
===== Deploying the Template using OpenShift CLI
.Prerequisites
* Perform the steps described in xref:image-streams-applications-templates[Using the {project_openshift_product_name} Image Streams and application templates].
.Procedure
. List the available {project_name} application templates:
+
[source,bash,subs="attributes+,macros+"]
@ -132,11 +150,16 @@ $ oc new-app --template={project_templates_version}-x509-https
Run 'oc status' to view your app.
----
Alternatively, perform one of the following procedures to deploy the {project_name} template by using the OpenShift 3.x or 4.x web console.
[id="deploy3x"]
===== Deploying the Template using the OpenShift 3.x Web Console
. Log in to the OpenShift web console and select the _sso-app-demo_ project space.
.Prerequisites
* Perform the steps described in xref:image-streams-applications-templates[Using the {project_openshift_product_name} Image Streams and application templates].
.Procedure
. Log in to the OpenShift web console and select the *sso-app-demo* project space.
. Click *Add to Project*, then *Browse Catalog* to list the default image streams and templates.
. Use the *Filter by Keyword* search bar to limit the list to those that match _sso_. You may need to click *Middleware*, then *Integration* to show the desired application template.
. Select an {project_name} application template. This example uses *_{project_name} {project_versionDoc} (Ephemeral)_*.
@ -145,46 +168,49 @@ Alternatively, perform one of the following procedures to deploy the {project_na
. Select *Do not bind at this time* radio button in the *Binding* step. Click *Create* to continue.
. In the *Results* step, click the *Continue to the project overview* link to verify the status of the deployment.
[id="deploy4x"]
===== Deploying the Template using the OpenShift 4.x Web Console
.Prerequisites
* Perform the steps described in xref:image-streams-applications-templates[Using the {project_openshift_product_name} Image Streams and Application Templates].
* Perform the steps described in xref:image-streams-applications-templates[Using the {project_openshift_product_name} Image Streams and application templates].
.Procedure
. Log in to the OpenShift web console and select the _sso-app-demo_ project space.
. On the left sidebar, click the `Administrator` tab and then click `</> Developer`.
. On the left sidebar, click the *Administrator* tab and then click *</> Developer*.
+
image:images/choose_developer_role.png[]
. Click `From Catalog`.
. Click *From Catalog*.
+
image:images/add_from_catalog.png[]
. Search for `sso`.
. Search for *sso*.
+
image:images/sso_keyword.png[]
. Choose a template such as `Red Hat Single Sign-On 7.4 on OpenJDK (Ephemeral)`.
. Choose a template such as *Red Hat Single Sign-On {project_version_base} on OpenJDK (Ephemeral)*.
+
image:images/choose_template.png[]
. Click `Instantiate Template`.
. Click *Instantiate Template*.
+
image:images/instantiate_template.png[]
. Adjust the template parameters if necessary and click `Create`.
. Adjust the template parameters if necessary and click *Create*.
. Verify the Red Hat Single Sign-On for OpenShift image was deployed.
+
image:images/verify_deployment.png[]
==== Accessing the Administrator Console of the {project_name} Pod
=== Accessing the Administrator Console of the {project_name} Pod
After the template is deployed, identify the available routes:
.Procedure
. After the template is deployed, identify the available routes.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get routes
@ -192,8 +218,11 @@ NAME HOST/PORT
sso sso-sso-app-demo.openshift.example.com
----
and access the {project_name} administrator console at:
. Access the {project_name} Admin Console.
+
[source,bash,subs="attributes+,macros+"]
----
\https://sso-sso-app-demo.openshift.example.com/auth/admin
----
* *\https://sso-sso-app-demo.openshift.example.com/auth/admin*
using the xref:sso-administrator-setup[administrator account].
. Provide the login credentials for the xref:sso-administrator-setup[administrator account].

61
openshift/topics/introduction.adoc
View file

@ -1,35 +1,66 @@
== Introduction
== Introduction to {project_openshift_product_name}
=== What Is {project_name}?
=== What is {project_name}?
[role="_abstract"]
{project_name} 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.
{openshift_name} is only available on the following platforms: *{openshift_image_platforms}*. For other available platforms, see link:{openshift_link_other}[{openshift_name_other}].
{openshift_name} is available only on *{openshift_image_platforms}*. For other available platforms, see link:{openshift_link_other}[{openshift_name_other}].
=== Comparison: {project_openshift_product_name} Image versus 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 important differences in functionality between the {project_openshift_product_name} image and {project_name} that should be considered:
The {project_openshift_product_name} image includes all of the functionality of {project_name}. In addition, the {project_name}-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.
[[sso-templates]]
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:
=== Templates for use with this software
Red Hat offers multiple OpenShift application templates using the {project_openshift_product_name} image version number {project_version}. These templates define the resources needed to develop {project_name} {project_version} server based deployment. The templates can mainly be split into two categories: passthrough templates and reencryption templates. Some other miscellaneous templates also exist.
[[passthrough-templates]]
* Templates using HTTPS and JGroups keystores and a truststore for the {project_name} server, all prepared beforehand. These secure the TLS communication using link:{ocp311docs_passthrough_route_link}[passthrough TLS termination]:
==== Passthrough templates
** *_{project_templates_version}-https_*: {project_name} {project_version} backed by internal H2 database on the same pod.
** *_{project_templates_version}-postgresql_*: {project_name} {project_version} backed by ephemeral PostgreSQL database on a separate pod.
** *_{project_templates_version}-postgresql-persistent_*: {project_name} {project_version} backed by persistent PostgreSQL database on a separate pod.
These templates require that HTTPS, JGroups keystores, and a truststore for the {project_name} server exist beforehand. They secure the TLS communication using passthrough TLS termination.
* _{project_templates_version}-https_*: {project_name} {project_version} backed by internal H2 database on the same pod.
* _{project_templates_version}-postgresql_*: {project_name} {project_version} backed by ephemeral PostgreSQL database on a separate pod.
* _{project_templates_version}-postgresql-persistent_*: {project_name} {project_version} backed by persistent PostgreSQL database on a separate pod.
[NOTE]
Templates for using {project_name} with MySQL / MariaDB databases have been removed and are not available since {project_name} version 7.4.
==== Re-encryption templates
[[reencrypt-templates]]
* Templates using OpenShift's internal link:{ocpdocs_serving_x509_secrets_link}[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} 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} 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:{ocp311docs_reencrypt_route_link}[re-encryption TLS termination]:
** *_{project_templates_version}-x509-https_*: {project_name} {project_version} with auto-generated HTTPS keystore and {project_name} truststore, backed by internal H2 database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic.
** *_{project_templates_version}-x509-postgresql-persistent_*: {project_name} {project_version} with auto-generated HTTPS keystore and {project_name} truststore, backed by persistent PostgreSQL database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic.
These templates use OpenShift's internal link:{ocpdocs_serving_x509_secrets_link}[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} 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} 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 re-encryption TLS termination.
* _{project_templates_version}-x509-https_*: {project_name} {project_version} with auto-generated HTTPS keystore and {project_name} truststore, backed by internal H2 database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic.
* _{project_templates_version}-x509-postgresql-persistent_*: {project_name} {project_version} with auto-generated HTTPS keystore and {project_name} truststore, backed by persistent PostgreSQL database. The `ASYM_ENCRYPT` JGroups protocol is used for encryption of cluster traffic.
==== Other templates
Other templates that integrate with {project_name} are also available:
* *_eap64-sso-s2i_*: {project_name}-enabled Red Hat JBoss Enterprise Application Platform 6.4.
* *_eap71-sso-s2i_*: {project_name}-enabled Red Hat JBoss Enterprise Application Platform 7.1.
* *_datavirt63-secure-s2i_*: {project_name}-enabled Red Hat JBoss Data Virtualization 6.3.
* _eap64-sso-s2i_*: {project_name}-enabled Red Hat JBoss Enterprise Application Platform 6.4.
* _eap71-sso-s2i_*: {project_name}-enabled Red Hat JBoss Enterprise Application Platform 7.1.
* _datavirt63-secure-s2i_*: {project_name}-enabled Red Hat JBoss Data Virtualization 6.3.
These templates contain environment variables specific to {project_name} that enable automatic {project_name} client registration when deployed.
See xref:Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information.
[role="_additional-resources"]
.Additional resources
* xref:Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods]
* link:{ocp311docs_passthrough_route_link}[passthrough TLS termination]
* link:{ocp311docs_reencrypt_route_link}[re-encryption TLS termination]
=== Version compatibility and support
For details about OpenShift image version compatibility, see the https://access.redhat.com/articles/2342861[Supported Configurations] page.
NOTE: The {project_openshift_product_name} image version number between 7.0 and 7.3 are deprecated and they will no longer receive updates of image and application templates.
To deploy new applications, use the version 7.4 or {project_version} of the {project_openshift_product_name} image along with the application templates specific to these image versions.

27
openshift/topics/reference.adoc
View file

@ -1,11 +1,12 @@
== Reference
[[sso-artifact-repository-mirrors-section]]
=== Artifact Repository Mirrors
=== Artifact repository mirrors
// This page describes MAVEN_MIRROR_URL variable usage
// It requires 'bcname' attribute to be set to the name of the product
[role="_abstract"]
A repository in Maven holds build artifacts and dependencies of various types
(all the project jars, library jar, plugins or any other project specific
artifacts). It also specifies locations from where to download artifacts from,
@ -25,17 +26,19 @@ Often, a repository manager can serve as local cache to a mirror. Assuming that
the repository manager is already deployed and reachable externally at
*_pass:[http://10.0.0.1:8080/repository/internal/]_*, the S2I build can then use this
manager by supplying the `MAVEN_MIRROR_URL` environment variable to the
build configuration of the application as follows:
build configuration of the application using the following procedure:
.Procedure
. Identify the name of the build configuration to apply `MAVEN_MIRROR_URL`
variable against:
variable against.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get bc -o name
buildconfig/sso
----
. Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable
. Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable.
+
[source,bash,subs="attributes+,macros+"]
----
@ -43,7 +46,7 @@ $ oc set env bc/sso \
-e MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/"
buildconfig "sso" updated
----
. Verify the setting
. Verify the setting.
+
[source,bash,subs="attributes+,macros+"]
----
@ -51,7 +54,7 @@ $ oc set env bc/sso --list
# buildconfigs sso
MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/
----
. Schedule new build of the application
. Schedule new build of the application.
NOTE: During application build, you will notice that Maven dependencies are
pulled from the repository manager, instead of the default public repositories.
@ -59,9 +62,9 @@ Also, after the build is finished, you will see that the mirror is filled with
all the dependencies that were retrieved and used during the build.
[[env_vars]]
=== Environment Variables
=== Environment variables
==== Information Environment Variables
==== Information environment variables
The following information environment variables are designed to convey
information about the image and should not be modified by the user:
@ -95,7 +98,7 @@ information about the image and should not be modified by the user:
|===
==== Configuration Environment Variables
==== Configuration environment variables
Configuration environment variables are designed to conveniently adjust the
image without requiring a rebuild, and should be set by the user as desired.
@ -607,7 +610,7 @@ avoid man-in-the-middle security attacks.
|{project_name} logout page for SAML applications.
|===
=== Exposed Ports
=== Exposed ports
[cols="2",options="header"]
|===
|Port Number | Description
@ -624,13 +627,13 @@ avoid man-in-the-middle security attacks.
=== Clustering
=== Security Domains
=== Security domains
=== HTTPS
=== Source-to-Image (S2I)
=== Known Issues
=== Known issues
* There is a known issue with the EAP6 Adapter _HttpServletRequest.logout()_ in which the adapter does not log out from the application, which can create a login loop. The workaround is to call _HttpSession.invalidate();_ after _request.logout()_ to clear the Keycloak token from the session. For more information, see https://issues.redhat.com/browse/KEYCLOAK-2665[KEYCLOAK-2665].
* The SSO logs throw a duplication error if the SSO pod is restarted while backed by a database pod. This error can be safely ignored.
* Setting _adminUrl_ to a "https://..." address in an OpenID Connect client will cause *javax.net.ssl.SSLHandshakeException* exceptions on the SSO server if the default secrets (*sso-app-secret* and *eap-app-secret*) are used. The application server must use either CA-signed certificates or configure the SSO trust store to trust the self-signed certificates.

284
openshift/topics/tutorials.adoc
View file

@ -1,15 +1,21 @@
== Tutorials
[[upgrading-sso-db-from-previous-version]]
=== Example Workflow: Updating Existing Database to Migrate to New {project_openshift_product_name} Image Version
[IMPORTANT]
====
* 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 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.
====
[role="_abstract"]
The tutorials in this chapter assume that you have an OpenShift instance similar to the one created by performing link:{ocpdocs_install_cluster_link}[the installation of the OpenShift Container Platform cluster].
{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].
[[upgrading-sso-db-from-previous-version]]
=== Updating a database for a new {project_openshift_product_name} image version
Note the following points related to the update:
* Rolling updates from a previous versions of {project_openshift_product_name} to version {project_version} are not supported as databases and caches are not backward compatible.
* Instances from versions of the {project_openshift_product_name} cannot be runnng before upgrade. They cannot run concurrently against the same database.
* Pre-generated scripts are not available. They are generated dynamically depending on the database.
You have two choices for updating the database:
* Allow {project_name} {project_version} to xref:automatic-db-migration[automatically migrate the database schema]
* Update the database xref:manual-db-migration[manually]
[NOTE]
====
@ -17,14 +23,14 @@ By default the database is automatically migrated when you start {project_name}
====
[[automatic-db-migration]]
==== Automatic Database Migration
This process assumes that you are link:{openshift_link}#Example-Deploying-SSO[running] some previous version of the {project_openshift_product_name} image, backed by a PostgreSQL database (deployed in ephemeral or persistent mode), running in a separate pod.
==== Automatic database migration
This process assumes that you are running a previous version of the {project_openshift_product_name} image, backed by a PostgreSQL database (deployed in ephemeral or persistent mode) that is running in a separate pod.
[IMPORTANT]
====
Stop all pods running the previous version of the {project_openshift_product_name} image before upgrading to {project_name} {project_version}, as they cannot run concurrently against the same database.
====
.Prerequisites
* Perform the steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment].
.Procedure
Use the following steps to automatically migrate the database schema:
. Identify the deployment config used to deploy the containers, running previous version of the {project_openshift_product_name} image.
@ -35,7 +41,7 @@ $ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql
----
. Stop all pods running the previous version of the {project_openshift_product_name} image in the current namespace.
. Stop all pods running the previous version of the {project_openshift_product_name} image in the current namespace. They cannot run concurrently against the same database.
+
[source,bash,subs="attributes+,macros+"]
----
@ -80,26 +86,32 @@ $ oc logs sso-4-vg21r | grep 'Updating'
----
[[manual-db-migration]]
==== Manual Database Migration
==== Manual database migration
[IMPORTANT]
The database migration process updates the data schema and performs manipulation of the data. This process also stops all pods running the previous version of the {project_openshift_product_name} image before dynamic generation of the SQL migration file.
[NOTE]
====
Pre-generated scripts are not available. They are generated dynamically depending on the database. With {project_name} {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:
This process assumes that you are running a previous version of the {project_openshift_product_name} image that is backed by a PostgreSQL database (deployed in ephemeral or persistent mode) and is running on a separate pod.
====
.Procedure
Prepare your environment for script generation.
. Configure {project_name} {project_version} with the correct datasource,
. Set following configuration options in the `standalone-openshift.xml` file:
. Set the following configuration options in the `standalone-openshift.xml` file:
.. `initializeEmpty=false`,
.. `migrationStrategy=manual`, and
.. `migrationExport` to the location on the file system of the pod, where the output SQL migration file should be stored (e.g. `migrationExport="${jboss.home.dir}/keycloak-database-update.sql"`).
.. `migrationExport` to the location on the file system of the pod, where the output SQL migration file should be stored (for example, `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 {project_name} {project_version}] for further details.
The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all pods running the previous version of the {project_openshift_product_name} image before dynamic generation of the SQL migration file.
====
[role="_additional-resources"]
.Additional resources
This process assumes that you are link:{openshift_link}#Example-Deploying-SSO[running] some previous version of the {project_openshift_product_name} image, backed by a PostgreSQL database (deployed in ephemeral or persistent mode), running on a separate pod.
* link:{project_doc_base_url}/server_installation_and_configuration_guide/database-1#database_configuration[Database configuration]
Perform the following to generate and get the SQL migration file for the database:
.Procedure
Perform the following to generate the SQL migration file for the database:
. Prepare template of OpenShift link:{ocpdocs_jobs_link}[database migration job] to generate the SQL file.
+
@ -159,7 +171,7 @@ Use the following script to copy `DB_SERVICE_PREFIX_MAPPING` and `TX_DATABASE_PR
+
[NOTE]
====
Although the `DB_SERVICE_PREFIX_MAPPING` environment variable allows a link:https://access.redhat.com/documentation/en-us/red_hat_jboss_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.
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/index#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"]
@ -494,21 +506,22 @@ $ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled
----
=== Example Workflow: Migrating The {project_name} Server's Database Across Environments
This tutorial focuses on migrating the Red Hat Single Sign-On server database from one environment to another or migrating to a different database. It assumes steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
=== Migrating the {project_name} server's database across environments
This tutorial focuses on migrating the {project_name} server database from one environment to another or migrating to a different database.
==== Deploying the {project_name} PostgreSQL Application Template
Export and import of {project_name} {project_version} database is triggered at {project_name} server boot time and its parameters are passed in via Java system properties. This means during one {project_name} server boot, only one of the possible migration actions, *_export_* or *_import_*, is performed.
. Log in to the OpenShift web console and select the _sso-app-demo_ project space.
==== Deploying the {project_name} PostgreSQL application template
.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
.Procedure
. Log in to the OpenShift web console and select the *sso-app-demo* project space.
. Click *Add to project* to list the default image streams and templates.
. Use the *Filter by keyword* search bar to limit the list to those that match _sso_. You may need to click *See all* to show the desired application template.
. Select *_{project_templates_version}-postgresql_* {project_name} application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value).
+
[IMPORTANT]
====
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} server boot time and its paramaters are passed in via Java system properties.] This means during one {project_name} server boot only one of the possible migration actions (either *_export_*, or *_import_*) can be performed.
====
+
[WARNING]
====
When the *_SSO_REALM_* configuration variable is set on the {project_openshift_product_name} image, a database import is performed in order to create the {project_name} 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.
@ -524,18 +537,31 @@ This example workflow uses a self-generated CA to provide an end-to-end workflow
For production environments, Red Hat recommends that you use an SSL certificate purchased from a verified Certificate Authority.
====
==== (Optional) Creating additional {project_name} link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported
[role="_additional-resources"]
.Additional resources
* link:{project_doc_base_url}/server_administration_guide/#assembly-exporting-importing_server_administration_guide[Importing and exporting the database]
When performing link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[{project_name} {project_version} server database export] only {project_name} realms and users currently present in the database will be exported. If the exported JSON file should include also additional {project_name} realms and users, these need to be created first:
==== (Optional) Creating additional realms and users to be exported
. 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]
When performing {project_name} {project_version} server database export, only realms and users currently in the database are exported. If the exported JSON file should include also additional {project_name} realms and users, these need to be created. Use these procedures.
Upon their creation xref:sso-export-the-database[the database can be exported.]
. link:{project_doc_base_url}//server_administration_guide/index#proc-creating-a-realm_server_administration_guide[Create a realm]
. link:{project_doc_base_url}//server_administration_guide/index#proc-creating-user_server_administration_guide[Create a user]
Upon their creation, the database can be exported.
[role="_additional-resources"]
.Additional resources
* link:{project_doc_base_url}//server_administration_guide/#assembly-exporting-importing_server_administration_guide[Importing and exporting the database]
[[sso-export-the-database]]
==== Export the {project_name} database as a JSON file on the OpenShift pod
.Prerequisites
* New realms and users are created.
.Procedure
. Get the {project_name} deployment config and scale it down to zero.
+
[source,bash,subs="attributes+,macros+"]
@ -580,6 +606,8 @@ $ oc logs sso-4-ejr0k | grep 'Export'
==== Retrieve and import the exported JSON file
.Procedure
. Retrieve the JSON file of the {project_name} database from the pod.
+
[source,bash,subs="attributes+,macros+"]
@ -596,12 +624,13 @@ $ oc rsync sso-4-ejr0k:/tmp/demorealm-export.json .
+
[NOTE]
====
For importing into an {project_name} 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} server not running on OpenShift, see the link:{project_doc_base_url}/server_administration_guide/#assembly-exporting-importing_server_administration_guide[Importing and exporting the database].
====
+
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} server to import the resources from previously exported JSON file into the {project_name} server's database, when the {project_name} server is running as a {project_name} {project_version} container on OpenShift:
When the {project_name} server is running as a {project_name} {project_version} container on OpenShift, use the
link:{project_doc_base_url}/server_administration_guide/#assembly-exporting-importing_server_administration_guide[Admin Console Export/Import] function to import the resources from a previously exported JSON file into the {project_name} server's database.
.. Log into the `master` realm's administration console of the {project_name} 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} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server.
.. Log into the `master` realm's Admin Console of the {project_name} 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} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server.
.. At the top of the sidebar choose the name of the {project_name} realm, the users, clients, realm roles, and client roles should be imported to. This example uses `master` realm.
.. Click the *Import* link under *Manage* section at the bottom of the sidebar.
.. In the page that opens, click *Select file* and then specify the location of the exported `demorealm-export.json` JSON file on the local file system.
@ -615,37 +644,39 @@ The attempt to import an object (user, client, realm role, or client role) fails
====
.. Click *Import* to perform the import.
+
[NOTE]
====
When importing objects from a non-master realm to `master` realm or vice versa, after clicking the *Import* button, it is sometimes possible to encounter an error like the following one:
+
[[realm-import-error-message]]
[.text-center]
image:images/import_realm_error.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 {project_name} server, on which the export JSON file was created, to the target {project_name} server, where the JSON file is imported. After creation of the necessary clients, click the *Import* button again.
+
To suppress the xref:realm-import-error-message[above] error message, it is needed to create the missing `realm-management` client, of the *bearer-only* *Access Type*, and click the *Import* button again.
====
+
[NOTE]
====
For *Skip* import strategy, the newly added objects are marked as *ADDED* and the object which were skipped are marked as *SKIPPED*, in the *Action* column on the import result page.
====
+
[IMPORTANT]
====
The administration console import allows you to *overwrite* resources if you choose (*Overwrite* strategy). On a production system use this feature with caution.
====
The Admin Console import allows you to *overwrite* resources if you choose (*Overwrite* strategy). On a production system use this feature with caution.
[[OSE-SSO-AUTH-TUTE]]
=== Example Workflow: Configuring OpenShift 3.11 to use {project_name} for Authentication
Configure OpenShift 3.11 to use the {project_name} 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} was deployed on OpenShift.
=== Configuring OpenShift 3.11 to use {project_name} for Authentication
Configure OpenShift 3.11 to use the {project_name} deployment as the authorization gateway for OpenShift.
This example adds {project_name} as an authentication method alongside link:{ocpdocs_idp_config_link}[the identity providers] configured during link:{ocpdocs_install_cluster_link}[the installation of the OpenShift Container Platform cluster]. Once configured, the {project_name} method will be also available (together with the configured identity providers) for the user login to your OpenShift web console.
This example adds {project_name} as an authentication method alongside the identity providers configured during the installation of the OpenShift Container Platform cluster. Once configured, the {project_name} method will be also available (together with the configured identity providers) for the user login to your OpenShift web console.
[role="additional-resources"]
.Additional resources
* link:{ocpdocs_idp_config_link}[Identity providers]
* link:{ocpdocs_install_cluster_link}[Installation of the OpenShift Container Platform cluster]
==== Configuring {project_name} Credentials
Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_sso-app-demo_._openshift32.example.com_/auth/admin* using the xref:sso-administrator-setup[administrator account] created during the {project_name} deployment.
.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
.Procedure
Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_sso-app-demo_._openshift32.example.com_/auth/admin* using the xref:sso-administrator-setup[administrator account created during the {project_name} deployment.
*Create a Realm*
@ -665,8 +696,6 @@ Create a test user that can be used to demonstrate the {project_name}-enabled Op
*Create and Configure an OpenID-Connect Client*
See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#clients[Managing Clients] chapter of the Red Hat Single Sign-On Server Administration Guide for more information.
. Click *Clients* in the *Manage* sidebar and click *Create*.
. Enter the *Client ID*. This example uses _openshift-demo_.
. Select a *Client Protocol* from the drop-down menu (this example uses *openid-connect*) and click *Save*. You will be taken to the configuration *Settings* page of the _openshift-demo_ client.
@ -675,10 +704,19 @@ See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-o
The client *Secret* is needed to configure OpenID-Connect on the OpenShift master in the next section. You can copy it now from under the *Credentials* tab. The secret is <pass:quotes[_7b0384a2-b832-16c5-9d73-2957842e89h7_]> for this example.
==== Configuring OpenShift Master for {project_name} Authentication
Log in to the OpenShift master CLI. You must have the required permissions to edit the */etc/origin/master/master-config.yaml* file.
[role="additional-resources"]
.Additional resources
* link:{project_doc_base_url}//server_administration_guide/index#assembly-managing-clients_server_administration_guide[Managing OpenID Connect and SAML Clients]
. Edit the */etc/origin/master/master-config.yaml* file and find the *identityProviders*. For example, in the case the OpenShift master is configured with the link:{ocpdocs_htpasswd_idp_link}[HTPassword identity provider], the *identityProviders* section will look similar to the following one:
==== Configuring OpenShift Master for {project_name} authentication
Log in to the OpenShift master CLI.
.Prerequisites
You must have the permissions to edit the */etc/origin/master/master-config.yaml* file.
.Procedure
. Edit the */etc/origin/master/master-config.yaml* file and find the *identityProviders* section. For example, in the case the OpenShift master is configured with the link:{ocpdocs_htpasswd_idp_link}[HTPassword identity provider], the *identityProviders* section will look similar to the following one:
+
[source,bash,subs="attributes+,macros+"]
----
@ -740,35 +778,39 @@ $ systemctl restart atomic-openshift-master
==== Logging in to OpenShift
Navigate to the OpenShift web console, which in this example is _https://openshift.example.com:8443/console_. The OpenShift login page now has the option to use either *htpasswd_auth* or *rh-sso*. The former is still available because it is present in the */etc/origin/master/master-config.yaml*.
.Procedure
Select *rh-sso* and log in to OpenShift with the _testuser_ user created earlier in {project_name}. 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.
. Navigate to the OpenShift web console, which in this example is _https://openshift.example.com:8443/console_.
+
The OpenShift login page now offers the options to log in either using *htpasswd_auth* or *rh-sso* identity providers? The former is still available because it is present in the */etc/origin/master/master-config.yaml*.
To provide _testuser_ `view` privileges for the _sso-app-demo_, use the OpenShift CLI:
. Select *rh-sso* and log in to OpenShift with the _testuser_ user created earlier in {project_name}.
+
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:
+
[source,bash,subs="attributes+,macros+"]
----
$ oc adm policy add-role-to-user view testuser -n sso-app-demo
----
[[binary-builds]]
=== Example Workflow: Creating OpenShift Application from Existing Maven Binaries and Securing it Using {project_name}
=== Creating an OpenShift application from maven binaries and securing it using {project_name}
To deploy existing applications on OpenShift, you can use the link:{ocpdocs_binary_source_link}[binary source] capability.
To deploy existing applications on OpenShift, you can use the binary source capability.
==== Deploy Binary Build of EAP 6.4 / 7.1 JSP Service Invocation Application and Secure it 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.1 JSP service application that authenticates using the {project_name}.
*Prerequisite:*
.Prerequisites
[IMPORTANT]
====
This guide assumes the {project_openshift_product_name} image has been previously link:{openshift_link}#Example-Deploying-SSO[deployed using one of the following templates:]
* The {project_openshift_product_name} image has been previously deployed using one of the following templates:
* *_{project_templates_version}-postgresql_*
* *_{project_templates_version}-postgresql-persistent_*
* *_{project_templates_version}-x509-postgresql-persistent_*
====
===== Create {project_name} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application
@ -776,12 +818,14 @@ The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name} real
*Create the {project_name} Realm*
. Login to the administration console of the {project_name} server.
. Login to the Admin Console of the {project_name} server.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
+
Use the xref:sso-administrator-setup[credentials of the {project_name} administrator user].
. Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*.
. Enter a realm name (this example uses `demo`) and click *Create*.
[[copy-rsa-public-key]]
@ -798,14 +842,11 @@ The information about the public key is necessary xref:sso-public-key-details[la
*Create {project_name} Roles*
[NOTE]
====
The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstart exposes three endpoints by the service:
* `public` - Requires no authentication.
* `secured` - Can be invoked by users with the `user` role.
* `admin` - Can be invoked by users with the `admin` role.
====
Create `user` and `admin` roles in {project_name}. These roles will be assigned to an {project_name} application user to authenticate access to user applications.
@ -829,7 +870,7 @@ 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`).
.. 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 will prompt you to confirm.
===== Assign `user` {project_name} Role to the Realm Management User
===== Assign the user role to the realm management user
Perform the following steps to tie the previously created `appuser` with the `user` {project_name} role:
@ -844,6 +885,8 @@ You can select multiple items at once by holding the *Ctrl* key and simultaneous
===== Prepare {project_name} Authentication for OpenShift Deployment of the EAP 6.4 / 7.1 JSP Application
.Procedure
. Create a new project for the EAP 6.4 / 7.1 JSP application.
+
[source,bash,subs="attributes+,macros+"]
@ -894,7 +937,9 @@ $ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks
$ oc secrets link default eap-ssl-secret eap-jgroup-secret
----
===== Deploy Binary Build of the EAP 6.4 / 7.1 JSP Application
===== Deploy binary build of the EAP 6.4 / 7.1 JSP application
.Procedure
. Clone the source code.
+
@ -902,7 +947,8 @@ $ oc secrets link default eap-ssl-secret eap-jgroup-secret
----
$ git clone \https://github.com/keycloak/keycloak-quickstarts.git
----
. link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.1/html-single/development_guide/#use_the_maven_repository[Configure] the link:https://access.redhat.com/maven-repository[Red Hat JBoss Middleware Maven repository].
link:{appserver_doc_base_url}/html-single/development_guide/index#use_the_maven_repository[Configure] the link:https://access.redhat.com/maven-repository[Red Hat JBoss Middleware Maven repository]
. Build both the link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] applications.
.. Build the `service-jee-jaxrs` application.
+
@ -1229,29 +1275,30 @@ NAME HOST/PORT PATH SERVICES PORT
eap-app eap-app-eap-app-demo.openshift.example.com eap-app 8080-tcp None
----
===== Access the Application
===== Access the application
Access the application in your browser using the URL *\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*. You should see output like on the following image:
[.text-center]
image:images/sso_app_jee_jsp.png[{project_name} Example JSP Application]
.Procedure
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.
* Click the *LOGIN* button to be redirected for user authentication to the {project_name} server instance against the `demo` realm.
. Click the *LOGIN* button to be redirected for user authentication to the {project_name} server instance against the `demo` realm.
+
Specify the username and password of the {project_name} user configured earlier (`appuser` / `apppassword`). Click *Log in*. The look of the application changes as detailed in the following image:
+
[.text-center]
image:images/sso_app_jee_jsp_logged_in.png[]
* Click the *INVOKE SECURED* button to access the `secured` endpoint.
. Click the *INVOKE SECURED* button to access the `secured` endpoint.
+
You should see the *Message: secured* output.
* Click the *INVOKE ADMIN* button to access the `admin` endpoint.
. Click the *INVOKE ADMIN* button to access the `admin` endpoint.
+
You should see *403 Forbidden* output.
+
@ -1259,10 +1306,12 @@ You should see *403 Forbidden* output.
====
The `admin` endpoint requires users with `admin` {project_name} 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.
====
+
.Procedure
Perform the following steps to add the `appuser` to the `admin` {project_name} role:
+
. Access the administration console of the {project_name} server's instance.
. Access the Admin Console of the {project_name} server's instance.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*.
+
@ -1283,15 +1332,20 @@ Use the xref:sso-administrator-setup[credentials of the {project_name} administr
You should see the *Message: admin* output already.
[[Example-EAP-Auto]]
=== Example Workflow: Automatically Registering EAP Application in {project_name} 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 {project_name} was deployed on OpenShift. This example prepares {project_name} 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} client registration. Once deployed, the {project_name} user can be used to authenticate and access {appserver_name}.
=== Automatically registering an EAP application in {project_name} with an OpenID-Connect client
This example prepares {project_name} 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} client registration. Once deployed, the {project_name} user can be used to authenticate and access {appserver_name}.
[NOTE]
====
This example uses a OpenID-Connect client but an SAML client could also be used. See xref:../advanced_concepts/advanced_concepts.adoc#SSO-Clients[{project_name} Clients] and xref:../advanced_concepts/advanced_concepts.adoc#Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients.
====
==== Preparing {project_name} Authentication for OpenShift Deployment
.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
==== Preparing {project_name} authentication for OpenShift deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
. Create a new project:
@ -1340,9 +1394,11 @@ $ oc create secret generic eap-jgroup-secret --from-file=eapjgroups.jceks
$ oc secrets link default eap-ssl-secret eap-jgroup-secret
----
==== Preparing the {project_name} Credentials
==== Preparing the {project_name} credentials
Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:sso-administrator-setup[administrator account] created during the {project_name} deployment.
.Procedure
*Create a Realm*
. Hover your cursor over the realm namespace at the top of the sidebar and click *Add Realm*.
@ -1382,7 +1438,9 @@ 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.
. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, add the role created earlier.
==== Deploy the {project_name}-enabled {appserver_name} Image
==== Deploy the {project_name}-enabled {appserver_name} image
,Procedure
. 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.
@ -1441,15 +1499,16 @@ Create the _application user_:
It may take several minutes for the {appserver_name} image to deploy.
==== Log in to the {appserver_name} Server Using {project_name}
==== Log in to the {appserver_name} Server using {project_name}
.Procedure
. Access the {appserver_name} application server and click *Login*. You are redirected to the {project_name} login.
. Log in using the {project_name} user created in the example. You are authenticated against the {project_name} server and returned to the {appserver_name} application server.
[[Example-EAP-Manual]]
=== Example Workflow: Manually Registering EAP Application in {project_name} with SAML Client
This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} image], in which {project_name} was deployed on OpenShift.
=== Manually registering EAP application in {project_name} with SAML client
This example prepares {project_name} realm, role, and user credentials for an EAP project and configures an EAP for OpenShift deployment. Once deployed, the {project_name} user can be used to authenticate and access {appserver_name}.
@ -1458,7 +1517,14 @@ This example prepares {project_name} realm, role, and user credentials for an EA
This example uses a SAML client but an OpenID-Connect client could also be used. See xref:../advanced_concepts/advanced_concepts.adoc#SSO-Clients[{project_name} Clients] and xref:../advanced_concepts/advanced_concepts.adoc#Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients.
====
==== Preparing the {project_name} Credentials
.Prerequisites
* The steps described in the xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
==== Preparing the {project_name} credentials
.Procedure
Log in to the encrypted {project_name} web server at *$$https://secure-sso-$$_<project-name>_._<hostname>_/auth/admin* using the xref:sso-administrator-setup[administrator account] created during the {project_name} deployment.
*Create a Realm*
@ -1539,9 +1605,11 @@ 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 *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 {project_name} Authentication for OpenShift Deployment
==== Preparing {project_name} authentication for OpenShift deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
.Procedure
. Create a new project:
+
[source,bash,subs="attributes+,macros+"]
@ -1590,9 +1658,13 @@ $ oc secrets link default eap-ssl-secret eap-jgroup-secret
----
[[modified-saml-xml]]
==== Modifying the *secure-saml-deployments* File
==== Modifying the *secure-saml-deployments* file
The *keycloak-saml-subsystem.xml*, exported from the {project_name} 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} SAML adapter configuration.
.Prerequisites
* The *keycloak-saml-subsystem.xml*, exported from the {project_name} 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} SAML adapter configuration.
.Procedure
. 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_.
@ -1632,7 +1704,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 {project_name} client.
. 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*
The client type must also be specified by the *<auth-method>* key in the application *web.xml*. This file is read by the image at deployment.
@ -1646,6 +1718,8 @@ 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 {project_name} 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} login. Log in to the application through {project_name} using the _application user_ user created earlier.