libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

[KEYCLOAK-8234] Drop the 'project_name_abbr' attribute

Browse source 
by substituting it with 'project_name' one, where previously referenced

Signed-off-by: Jan Lieskovsky <jlieskov@redhat.com>
This commit is contained in:
Jan Lieskovsky 2018-12-13 18:57:05 +01:00 committed by Stian Thorgersen
parent fe14ea90cc
commit dce27ff5f1
7 changed files with 292 additions and 291 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

140
openshift/topics/advanced_concepts.adoc
View file

@ -1,8 +1,8 @@
== Advanced Concepts
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.
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.
=== Requirements and Deploying xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination] {project_name_abbr} Templates
=== Requirements and Deploying xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination] {project_name} Templates
==== Preparing the Deployment
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]]
==== Creating HTTPS and JGroups Keystores, and Truststore for the {project_name_abbr} Server
==== Creating HTTPS and JGroups Keystores, and Truststore for the {project_name} Server
The {project_name_abbr} application templates using xref:../introduction/introduction.adoc#passthrough-templates[passthrough TLS termination] require:
The {project_name} 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,
* 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_abbr} server truststore] used for securing the {project_name_abbr} requests
* 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_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 {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: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} 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_abbr} 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} server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores.
[WARNING]
====
@ -100,7 +100,7 @@ $ keytool -genseckey -alias secret-key -storetype JCEKS -keystore jgroups.jceks
----
[[create-server-truststore]]
*_Import the CA certificate into a new {project_name_abbr} server truststore:_*
*_Import the CA certificate into a new {project_name} server truststore:_*
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.
. Create the secrets for the HTTPS and JGroups keystores, and {project_name_abbr} server truststore, generated in the xref:Configuring-Keystores[previous section].
. Create the secrets for the HTTPS and JGroups keystores, and {project_name} server truststore, generated in the xref:Configuring-Keystores[previous section].
+
[subs="verbatim,macros,attributes"]
----
$ oc secret new sso-app-secret keystore.jks jgroups.jceks truststore.jks
----
. Link these secrets to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[default] service account, which is used to run {project_name_abbr} 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} pods.
+
[subs="verbatim,macros,attributes"]
----
$ oc secrets link default sso-app-secret
----
==== Deploying the Chosen {project_name_abbr} Passthrough TLS Template via OpenShift CLI
==== Deploying the Chosen {project_name} 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:
[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_abbr} 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} 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 {project_name_abbr} server, and passwords for the HTTPS and JGroups keystores, and the truststore of the {project_name_abbr} 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} server, and passwords for the HTTPS and JGroups keystores, and the truststore of the {project_name} 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.
====
@ -184,9 +184,9 @@ $ oc new-app --template={project_templates_version}-https \
{project_name} {project_version} (Ephemeral with passthrough TLS)
---------
An example {project_name_abbr} 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates.
An example {project_name} 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates.
A new {project_name_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.
A new {project_name} service has been created in your project. The admin username/password for accessing the master realm via the {project_name} console is 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} requests.
* With parameters:
* Application Name=sso
@ -206,14 +206,14 @@ $ oc new-app --template={project_templates_version}-https \
* JGroups Keystore Password=password
* JGroups Cluster Password=yeSppLfp # generated
* ImageStream Namespace=openshift
* {project_name_abbr} Administrator Username=admin
* {project_name_abbr} Administrator Password=redhat
* {project_name_abbr} Realm=demorealm
* {project_name_abbr} Service Username=
* {project_name_abbr} Service Password=
* {project_name_abbr} Trust Store=truststore.jks
* {project_name_abbr} Trust Store Password=mykeystorepass
* {project_name_abbr} Trust Store Secret=sso-app-secret
* {project_name} Administrator Username=admin
* {project_name} Administrator Password=redhat
* {project_name} Realm=demorealm
* {project_name} Service Username=
* {project_name} Service Password=
* {project_name} Trust Store=truststore.jks
* {project_name} Trust Store Password=mykeystorepass
* {project_name} Trust Store Secret=sso-app-secret
* Container Memory Limit=1Gi
--> Creating resources ...
@ -227,7 +227,7 @@ $ oc new-app --template={project_templates_version}-https \
Run 'oc status' to view your app.
----
==== Accessing the Administrator Console of the {project_name_abbr} Pod
==== Accessing the Administrator Console of the {project_name} Pod
After the template got deployed, identify the available routes:
@ -257,7 +257,7 @@ $ oc get routes
|None
|===
and access the {project_name_abbr} administrator console at:
and access the {project_name} administrator console at:
* *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
* *\http://sso-sso-app-demo.openshift.example.com/auth/admin*
@ -325,8 +325,8 @@ Red Hat Single Sign-On does not provide any pre-configured management account ou
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 {project_name_abbr} application template, or
* 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.
* By providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the {project_name} application template, or
* By xref:sso-admin-remote-shell[a remote shell session to particular {project_name} pod], if the {project_openshift_product_name} image is deployed without an application template.
[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]]
==== Creating {project_name_abbr} Administrator Account via Template Parameters
==== Creating {project_name} Administrator Account via Template Parameters
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.
When deploying {project_name} application template, *_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]
====
@ -345,25 +345,25 @@ When deploying {project_name_abbr} application template, *_SSO_ADMIN_USERNAME_*
[IMPORTANT]
====
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:
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_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 {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 {project_name_abbr} and the database pods are destructed.
* For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates) the account exists throughout the lifecycle of the particular {project_name} 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 {project_name} 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 {project_name} and the database pods are destructed.
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).
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_abbr} 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} applications.
====
[IMPORTANT]
====
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:
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_abbr} application.
. Identify the deployment config of the {project_name} application.
+
[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]]
==== Creating {project_name_abbr} Administrator Account via Remote Shell Session to {project_name_abbr} Pod
==== Creating {project_name} Administrator Account via Remote Shell Session to {project_name} Pod
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:
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:
. Identify the {project_name_abbr} application pod.
. Identify the {project_name} application pod.
+
[subs="verbatim,macros,attributes"]
----
@ -400,7 +400,7 @@ sso-mysql-6-d97pf 1/1 Running 0 2m
$ oc rsh sso-12-pt93n
sh-4.2$
----
. Create the {project_name_abbr} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
. Create the {project_name} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
+
[subs="verbatim,macros,attributes"]
----
@ -426,27 +426,27 @@ sh-4.2$ ./jboss-cli.sh --connect ':reload'
+
[WARNING]
====
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.
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_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.
. 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.
=== 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_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.
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}-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} web server.
After the {project_name_abbr} web server pod has started, it can be accessed from its custom configured hostnames, or from the default hostnames:
After the {project_name} 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 {project_name_abbr} web server, and
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted {project_name_abbr} web server.
* *\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:../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]]
=== {project_name_abbr} Clients
=== {project_name} Clients
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.
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 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.
{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. +
{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:
- *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]]
==== Automatic and Manual {project_name_abbr} Client Registration Methods
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.
==== 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_abbr} 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} client adapter and including it in the client application configuration.
===== Automatic {project_name_abbr} Client Registration
===== Automatic {project_name} Client Registration
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.
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.
The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
The {project_name} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
[cols="2*", options="header"]
|===
@ -492,10 +492,10 @@ The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*,
|Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>
|*_SSO_URL_*
|The {project_name_abbr} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|The {project_name} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|*_SSO_REALM_*
|The {project_name_abbr} realm created for this procedure.
|The {project_name} realm created for this procedure.
|*_SSO_USERNAME_*
|The name of the _realm management user_.
@ -504,16 +504,16 @@ The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*,
| The password of the user.
|*_SSO_PUBLIC_KEY_*
|The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name_abbr} console.
|The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name} console.
|*_SSO_BEARER_ONLY_*
|If set to *true*, the OpenID Connect client is registered as bearer-only.
|*_SSO_ENABLE_CORS_*
|If set to *true*, the {project_name_abbr} adapter enables Cross-Origin Resource Sharing (CORS).
|If set to *true*, the {project_name} adapter enables Cross-Origin Resource Sharing (CORS).
|===
If the {project_name_abbr} client uses the SAML protocol, the following additional variables need to be configured:
If the {project_name} client uses the SAML protocol, the following additional variables need to be configured:
[cols="2*", options="header"]
|===
@ -532,29 +532,29 @@ If the {project_name_abbr} client uses the SAML protocol, the following addition
|Alias for keys/certificate to use for SAML. The default is _jboss_.
|===
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.
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_abbr} Client Registration
===== Manual {project_name} Client Registration
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:
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:
[horizontal]
*OpenID-Connect*:: _../configuration/secure-deployments_
*SAML*:: _../configuration/secure-saml-deployments_
These files are copied to the {project_name_abbr} adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed.
These files are copied to the {project_name} adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed.
There are two methods for passing the {project_name_abbr} adapter configuration to the client application:
There are two methods for passing the {project_name} adapter configuration to the client application:
* 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
* Modify the deployment file to contain the {project_name} adapter configuration so that it is included in the _standalone-openshift.xml_ file at deployment, or
* Manually include the OpenID-Connect _keycloak.json_ file, or the SAML _keycloak-saml.xml_ file in the client application's *../WEB-INF* directory.
See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {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.
See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {project_name} Authentication, Using SAML Client] for an end-to-end example of the manual {project_name} client registration method using a SAML client.
=== Limitations
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.
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 `oadm policy` command.
For example, to allow an {project_name_abbr}-created user to view a project namespace in OpenShift:
For example, to allow an {project_name}-created user to view a project namespace in OpenShift:
[subs="verbatim,macros,attributes"]
----
oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]>

2
openshift/topics/before_you_begin.adoc
View file

@ -3,7 +3,7 @@
=== 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_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.
* 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.

154
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
----
. Run the following commands to update the core set of {project_name_abbr} {project_version} resources for OpenShift in the `openshift` project:
. Run the following commands to update the core set of {project_name} {project_version} resources for OpenShift in the `openshift` project:
+
[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}
done
----
. Run the following command to install the {project_name_abbr} {project_version} OpenShift image streams in the `openshift` project:
. Run the following command to install the {project_name} {project_version} OpenShift image streams in the `openshift` project:
+
[subs="verbatim,macros,attributes"]
----
@ -116,8 +116,8 @@ $ oc secrets link <pass:quotes[_service-account-name_]> <pass:quotes[_sso-ssl-se
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 {project_name_abbr} application template, or
* 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.
* By providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the {project_name} application template, or
* By xref:sso-admin-remote-shell[a remote shell session to particular {project_name} pod], if the {project_openshift_product_name} image is deployed without an application template.
[NOTE]
====
@ -125,9 +125,9 @@ The administrator account can be created:
====
[[sso-admin-template-parameters]]
===== Creating {project_name_abbr} Administrator Account via Template Parameters
===== Creating {project_name} Administrator Account via Template Parameters
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.
When deploying {project_name} application template, *_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]
====
@ -136,25 +136,25 @@ When deploying {project_name_abbr} application template, *_SSO_ADMIN_USERNAME_*
[IMPORTANT]
====
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:
The lifespan of the {project_name} server's administrator account depends upon the 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 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 {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 {project_name_abbr} and the database pods are destructed.
* For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates) the account exist throughout the lifecycle of the particular {project_name} 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 {project_name} 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 {project_name} and the database pods are destructed.
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).
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_abbr} 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} applications.
====
[IMPORTANT]
====
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:
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_abbr} application.
. Identify the deployment config of the {project_name} application.
+
[subs="verbatim,macros,attributes"]
----
@ -171,11 +171,11 @@ $ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD=""
====
[[sso-admin-remote-shell]]
===== Creating {project_name_abbr} Administrator Account via Remote Shell Session to {project_name_abbr} Pod
===== Creating {project_name} Administrator Account via Remote Shell Session to {project_name} Pod
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:
Run following commands to create 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:
. Identify the {project_name_abbr} application pod.
. Identify the {project_name} application pod.
+
[subs="verbatim,macros,attributes"]
----
@ -191,7 +191,7 @@ sso-mysql-6-d97pf 1/1 Running 0 2m
$ oc rsh sso-12-pt93n
sh-4.2$
----
. Create the {project_name_abbr} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
. Create the {project_name} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
+
[subs="verbatim,macros,attributes"]
----
@ -217,9 +217,9 @@ sh-4.2$ ./jboss-cli.sh --connect ':reload'
+
[WARNING]
====
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.
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. Because restarting the whole container recreates it from scratch, without the {project_name} server administration account for the `master` realm to be created.
====
. 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.
. Log into the `master` realm's administration console of the {project_name} 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} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server, and specify user name and password used to create the administrator user.
==== Using the OpenShift Web Console
Log in to the OpenShift web console:
@ -229,14 +229,14 @@ Log in to the OpenShift web console:
. Select an application template and configure the deployment parameters as required.
. Click *Create* to deploy the application template.
These are some of the more common variables to configure an {project_name_abbr} deployment:
These are some of the more common variables to configure an {project_name} deployment:
[cols="2*", options="header"]
|===
|Variable
|Description
|*_APPLICATION_NAME_*
|The name for the {project_name_abbr} application.
|The name for the {project_name} application.
|*_HOSTNAME_HTTPS_*
|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 {project_name_abbr}
|The name of the secret containing the JGroups keystore file.
|*_SSO_ADMIN_USERNAME_*
|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.
|Username of the administrator account for the `master` realm of the {project_name} server. *Required.* If no value is specified, it is auto generated and displayed as an OpenShift instructional message when the template is instantiated.
|*_SSO_ADMIN_PASSWORD_*
|Password of the administrator account for the `master` realm of the {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.
|Password of the administrator account for the `master` realm of the {project_name} server. *Required.* If no value is specified, it is auto generated and displayed as an OpenShift instructional message when the template is instantiated.
|*_SSO_REALM_*
|The name of an additional {project_name_abbr} realm to create during deployment.
|The name of an additional {project_name} realm to create during deployment.
|*_SSO_SERVICE_USERNAME_*
|{project_name_abbr} service user name to manage the realm.
|{project_name} service user name to manage the realm.
|*_SSO_SERVICE_PASSWORD_*
|{project_name_abbr} service user password.
|{project_name} service user password.
|===
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 {project_name_abbr} deployment.
See the xref:env_vars[Reference chapter] for a more comprehensive list of the {project_name} 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 {project_name} deployment.
==== 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 {project_name_abbr} 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} login page.
For more information on OpenShift route types, see the link:https://docs.openshift.com/container-platform/3.7/architecture/networking/routes.html#route-types[Networking chapter] of the OpenShift Architecture Guide.
==== Deployment Process
Once deployed, the *_{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.
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}-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} web server.
After the {project_name_abbr} web server pod has started, it can be accessed at its custom configured hostnames, or at the default hostnames:
After the {project_name} 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 {project_name_abbr} web server, and
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted {project_name_abbr} web server.
* *\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:../get_started/get_started.adoc#sso-administrator-setup[administrator user credentials] to log in into the `master` realm’s administration console.
[[SSO-Clients]]
==== {project_name_abbr} Clients
==== {project_name} Clients
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.
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.
{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. +
{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:
- *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]]
==== Automatic and Manual {project_name_abbr} Client Registration Methods
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.
==== 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_abbr} 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} client adapter and including it in the client application configuration.
==== Automatic {project_name_abbr} Client Registration
==== Automatic {project_name} Client Registration
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.
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.
The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
The {project_name} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
[cols="2*", options="header"]
|===
@ -349,10 +349,10 @@ The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*,
|Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>
|*_SSO_URL_*
|The {project_name_abbr} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|The {project_name} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|*_SSO_REALM_*
|The {project_name_abbr} realm created for this procedure.
|The {project_name} realm created for this procedure.
|*_SSO_USERNAME_*
|The name of the _realm management user_.
@ -361,16 +361,16 @@ The {project_name_abbr} environment variables included in the *_eap64-sso-s2i_*,
| The password of the user.
|*_SSO_PUBLIC_KEY_*
|The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name_abbr} console.
|The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name} console.
|*_SSO_BEARER_ONLY_*
|If set to *true*, the OpenID Connect client is registered as bearer-only.
|*_SSO_ENABLE_CORS_*
|If set to *true*, the {project_name_abbr} adapter enables Cross-Origin Resource Sharing (CORS).
|If set to *true*, the {project_name} adapter enables Cross-Origin Resource Sharing (CORS).
|===
If the {project_name_abbr} client uses the SAML protocol, the following additional variables need to be configured:
If the {project_name} client uses the SAML protocol, the following additional variables need to be configured:
[cols="2*", options="header"]
|===
@ -389,29 +389,29 @@ If the {project_name_abbr} client uses the SAML protocol, the following addition
|Alias for keys/certificate to use for SAML. The default is _jboss_.
|===
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.
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_abbr} Client Registration
==== Manual {project_name} Client Registration
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:
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:
[horizontal]
*OpenID-Connect*:: _../configuration/secure-deployments_
*SAML*:: _../configuration/secure-saml-deployments_
These files are copied to the {project_name_abbr} adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed.
These files are copied to the {project_name} adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed.
There are two methods for passing the {project_name_abbr} adapter configuration to the client application:
There are two methods for passing the {project_name} adapter configuration to the client application:
* 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
* Modify the deployment file to contain the {project_name} adapter configuration so that it is included in the _standalone-openshift.xml_ file at deployment, or
* Manually include the OpenID-Connect _keycloak.json_ file, or the SAML _keycloak-saml.xml_ file in the client application's *../WEB-INF* directory.
See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {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.
See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {project_name} Authentication, Using SAML Client] for an end-to-end example of the manual {project_name} client registration method using a SAML client.
==== Limitations
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.
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 `oadm policy` command.
For example, to allow an {project_name_abbr}-created user to view a project namespace in OpenShift:
For example, to allow an {project_name}-created user to view a project namespace in OpenShift:
[subs="verbatim,macros,attributes"]
----
oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]>
@ -439,17 +439,17 @@ This guide assumes the {project_openshift_product_name} image has been previousl
* *_{project_templates_version}-x509-postgresql-persistent_*
====
===== Create {project_name_abbr} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application
===== Create {project_name} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application
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:
The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name} 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 {project_name_abbr} Realm*
*Create the {project_name} Realm*
. Login to the administration console of the {project_name_abbr} server.
. Login to the administration console of the {project_name} server.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
+
Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name_abbr} administrator user].
Use the xref:sso_server.adoc#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*.
@ -463,9 +463,9 @@ In the newly created `demo` realm, click the *Keys* tab, then select *Active* ta
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.
====
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.
The information about the public key is necessary xref:sso-public-key-details[later to deploy] the {project_name}-enabled EAP 6.4 / 7.1 JSP application.
*Create {project_name_abbr} Roles*
*Create {project_name} Roles*
[NOTE]
====
@ -476,7 +476,7 @@ The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-je
* `admin` - Can be invoked by users with the `admin` role.
====
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.
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.
. Click *Roles* in the *Configure* sidebar to list the roles for this realm.
+
@ -489,7 +489,7 @@ This is a new realm, so there should only be the default (`offline_access` and `
Repeat these steps for the `admin` role.
*Create the {project_name_abbr} Realm Management User*
*Create the {project_name} Realm Management User*
. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User.*
@ -498,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`).
.. 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` {project_name_abbr} Role to the Realm Management User
===== Assign `user` {project_name} Role to the Realm Management User
Perform the following steps to tie the previously created `appuser` with the `user` {project_name_abbr} role:
Perform the following steps to tie the previously created `appuser` with the `user` {project_name} role:
. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, select the `user` role created earlier, and click *Add selected>*.
. Click *Client Roles*, select *realm-management* entry from the list, select each record in the *Available Roles* list.
@ -511,7 +511,7 @@ You can select multiple items at once by holding the *Ctrl* key and simultaneous
====
. Click *Add selected>* to assign the roles to the client.
===== Prepare {project_name_abbr} Authentication for OpenShift Deployment of the EAP 6.4 / 7.1 JSP Application
===== Prepare {project_name} Authentication for OpenShift Deployment of the EAP 6.4 / 7.1 JSP Application
. Create a new project for the EAP 6.4 / 7.1 JSP application.
+
@ -800,7 +800,7 @@ deploymentconfig "eap-app" scaled
----
. Further configure the EAP 6.4 / 7.1 JSP application prior the deployment.
[[sso-public-key-details]]
.. Configure the application with proper details about the {project_name_abbr} server instance.
.. Configure the application with proper details about the {project_name} server instance.
+
[WARNING]
====
@ -903,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:
[.text-center]
image:images/sso_app_jee_jsp.png[{project_name_abbr} Example JSP Application]
image:images/sso_app_jee_jsp.png[{project_name} Example JSP Application]
Perform the following to test the application:
* Click the *INVOKE PUBLIC* button to access the `public` endpoint that doesn't require authentication.
+
You should see the *Message: public* output.
* Click the *LOGIN* button to be redirected for user authentication to the {project_name_abbr} 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 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:
Specify 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[]
@ -926,16 +926,16 @@ You should see *403 Forbidden* output.
+
[NOTE]
====
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.
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.
====
+
Perform the following steps to add the `appuser` to the `admin` {project_name_abbr} role:
Perform the following steps to add the `appuser` to the `admin` {project_name} role:
+
. Access the administration console of the {project_name_abbr} server's instance.
. Access the administration console of the {project_name} server's instance.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*.
+
Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name_abbr} administrator user].
Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name} administrator user].
. Click *Users* in the *Manage* sidebar to view the user information for the `demo` realm.
. Click *View all users* button.
. Click the ID link for the *appuser* or alternatively click the *Edit* button in the *Actions* column.

36
openshift/topics/introduction.adoc
View file

@ -1,33 +1,33 @@
== Introduction
=== What Is Red Hat Single Sign-On?
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.
=== What Is {openshift_name}?
{openshift_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.
[[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:
[[passthrough-templates]]
* 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]:
* Templates using HTTPS and JGroups keystores and a truststore for the {project_name} 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_*: {project_name_abbr} {project_version} backed by internal H2 database on the same pod.
** *_{project_templates_version}-mysql_*: {project_name_abbr} {project_version} backed by ephemeral 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_*: {project_name_abbr} {project_version} backed by ephemeral 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.
** *_{project_templates_version}-https_*: {project_name} {project_version} backed by internal H2 database on the same pod.
** *_{project_templates_version}-mysql_*: {project_name} {project_version} backed by ephemeral MySQL database on a separate pod.
** *_{project_templates_version}-mysql-persistent_*: {project_name} {project_version} backed by persistent MySQL database on a separate 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.
[[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 {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]:
* 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} 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:https://docs.openshift.com/container-platform/latest/architecture/networking/routes.html#re-encryption-termination[re-encryption TLS termination]:
** *_{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_*: {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_*: {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.
** *_{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-mysql-persistent_*: {project_name} {project_version} with auto-generated HTTPS keystore and {project_name} truststore, backed by persistent MySQL 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 that integrate with {project_name_abbr} are also available:
Other templates that integrate with {project_name} are also available:
* *_eap64-sso-s2i_*: {project_name_abbr}-enabled Red Hat JBoss Enterprise Application Platform 6.4.
* *_eap71-sso-s2i_*: {project_name_abbr}-enabled Red Hat JBoss Enterprise Application Platform 7.1.
* *_datavirt63-secure-s2i_*: {project_name_abbr}-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_abbr} that enable automatic {project_name_abbr} client registration when deployed.
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_abbr} Client Registration Methods] for more information.
See xref:Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information.

66
openshift/topics/reference.adoc
View file

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

182
openshift/topics/tutorials.adoc
View file

@ -1,4 +1,4 @@
[[{project_name_abbr}-Binary-Builds-Tutorial]]
[[{project_name}-Binary-Builds-Tutorial]]
=== Example Workflow: Creating OpenShift Application from Existing Maven Binaries and Securing it Using Red Hat Single Sing-On
== Tutorials
@ -6,7 +6,7 @@
[[Example-Deploying-SSO]]
=== Example Workflow: Preparing and Deploying the {project_openshift_product_name} image
[[Preparing-SSO-Authentication-for-OpenShift-Deployment]]
==== Preparing {project_name_abbr} Authentication for OpenShift Deployment
==== Preparing {project_name} Authentication for OpenShift Deployment
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
To deploy existing applications on OpenShift, you can use the link:https://docs.openshift.com/container-platform/latest/dev_guide/builds/build_inputs.html#binary-source[binary source] capability.
@ -29,17 +29,17 @@ This guide assumes the {project_openshift_product_name} image has been previousl
* *_{project_templates_version}-x509-postgresql-persistent_*
====
===== Create {project_name_abbr} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application
===== Create {project_name} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application
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:
The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name} 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 {project_name_abbr} Realm*
*Create the {project_name} Realm*
. Login to the administration console of the {project_name_abbr} server.
. Login to the administration console of the {project_name} server.
+
*\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
+
Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name_abbr} administrator user].
Use the xref:sso_server.adoc#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*.
@ -58,7 +58,7 @@ Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project
[NOTE]
====
By default the database is automatically migrated when you start {project_name_abbr} {project_version} for the first time.
By default the database is automatically migrated when you start {project_name} {project_version} for the first time.
====
[[automatic-db-migration]]
@ -72,12 +72,12 @@ This process assumes that you are running {project_openshift_product_name} {proj
[IMPORTANT]
====
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.
Stop all {project_name} {project_previous_version} pods before upgrading to {project_name} {project_version}, as they cannot run concurrently against the same database.
====
Use the following steps to automatically migrate the database schema:
. Identify existing deployment config for {project_name_abbr} {project_previous_version} containers.
. Identify existing deployment config for {project_name} {project_previous_version} containers.
+
[subs="verbatim,macros,attributes"]
----
@ -85,28 +85,28 @@ $ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql
----
. Stop all {project_name_abbr} {project_previous_version} containers in the current namespace.
. Stop all {project_name} {project_previous_version} containers in the current namespace.
+
[subs="verbatim,macros,attributes"]
----
$ oc scale --replicas=0 dc/sso
deploymentconfig "sso" scaled
----
. Update the image change trigger in the existing deployment config to reference the {project_name_abbr} {project_version} image.
. Update the image change trigger in the existing deployment config to reference the {project_name} {project_version} image.
+
[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}"}]'
"sso" patched
----
. Start rollout of the new {project_name_abbr} {project_version} images based on the latest image defined in the image change triggers.
. Start rollout of the new {project_name} {project_version} images based on the latest image defined in the image change triggers.
+
[subs="verbatim,macros,attributes"]
----
$ oc rollout latest dc/sso
deploymentconfig "sso" rolled out
----
. Deploy {project_name_abbr} {project_version} containers using the modified deployment config.
. Deploy {project_name} {project_version} containers using the modified deployment config.
+
[subs="verbatim,macros,attributes"]
----
@ -134,17 +134,17 @@ $ oc logs sso-4-vg21r | grep 'Updating'
[IMPORTANT]
====
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:
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:
. Configure {project_name_abbr} {project_version} with the correct datasource,
. Configure {project_name} {project_version} with the correct datasource,
. Set 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"`).
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.
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 {project_name_abbr} {project_previous_version} 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} {project_previous_version} instances before dynamic generation of the SQL migration file.
====
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:]
@ -210,7 +210,7 @@ spec:
$ cp {project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml.orig \
{project_previous_templates_version}-to-{project_templates_version}-db-migrate-job.yaml
----
. Copy the datasource definition and database access credentials from {project_name_abbr} {project_version} deployment config to appropriate places in database job migration template.
. Copy the datasource definition and database access credentials from {project_name} {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`.
+
@ -365,7 +365,7 @@ Successfully updated DB_PASSWORD to: tsWNhQHK
Successfully updated DB_DATABASE to: root
Successfully updated TX_DATABASE_PREFIX_MAPPING to: sso-postgresql=DB
----
. 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.
. Build the {project_name} {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"]
----
@ -427,10 +427,10 @@ job "{project_previous_templates_version}-to-{project_templates_version}-db-migr
+
[IMPORTANT]
====
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.
The database migration process handles the data schema update and performs manipulation of the data, therefore, stop all {project_name} {project_version} instances before dynamic generation of the SQL migration file.
====
+
. Identify existing deployment config for {project_name_abbr} {project_version} containers.
. Identify existing deployment config for {project_name} {project_version} containers.
+
[subs="verbatim,macros,attributes"]
----
@ -438,7 +438,7 @@ $ oc get dc -o name --selector=application=sso
deploymentconfig/sso
deploymentconfig/sso-postgresql
----
. Stop all {project_name_abbr} {project_version} containers in the current namespace.
. Stop all {project_name} {project_version} containers in the current namespace.
+
[subs="verbatim,macros,attributes"]
----
@ -485,7 +485,7 @@ keycloak-database-update.sql
sent 30 bytes received 29,726 bytes 59,512.00 bytes/sec
total size is 29,621 speedup is 1.00
----
. Inspect the `keycloak-database-update.sql` file for changes to be performed within manual {project_name_abbr} {project_version} database update.
. Inspect the `keycloak-database-update.sql` file for changes to be performed within manual {project_name} {project_version} database update.
. 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):
... 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]]
[start=12]
. Update image change trigger in the existing deployment config of {project_name_abbr} {project_version} to reference the {project_name_abbr} {project_version} image.
. Update image change trigger in the existing deployment config of {project_name} {project_version} to reference the {project_name} {project_version} image.
+
[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}"}]'
"sso" patched
----
. Start rollout of the new {project_name_abbr} {project_version} images based on the latest image defined in the image change triggers.
. Start rollout of the new {project_name} {project_version} images based on the latest image defined in the image change triggers.
+
[subs="verbatim,macros,attributes"]
----
$ oc rollout latest dc/sso
deploymentconfig "sso" rolled out
----
. Deploy {project_name_abbr} {project_version} containers using the modified deployment config.
. Deploy {project_name} {project_version} containers using the modified deployment config.
+
[subs="verbatim,macros,attributes"]
----
@ -596,39 +596,39 @@ $ oc scale --replicas=1 dc/sso
deploymentconfig "sso" scaled
----
=== 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 {project_name_abbr} Authentication for OpenShift Deployment] section have been performed already.
=== Example Workflow: Migrating Entire {project_name} Server Database Across The Environments
This tutorial focuses on migrating the Red Hat Single Sign-On server database from one environment to another or migrating to a different database. It assumes steps described in xref:Preparing-SSO-Authentication-for-OpenShift-Deployment[Preparing {project_name} Authentication for OpenShift Deployment] section have been performed already.
==== Deploying the {project_name_abbr} MySQL Application Template
==== Deploying the {project_name} MySQL Application Template
. Log in to the OpenShift web console and select the _sso-app-demo_ project space.
. Click *Add to project* to list the default image streams and templates.
. 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_* {project_name_abbr} application template. When deploying the template ensure to *keep the _SSO_REALM_ variable unset* (default value).
. Select *_{project_templates_version}-mysql_* {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_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.
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_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.
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.
====
+
. Click *Create* to deploy the application template and start pod deployment. This may take a couple of minutes.
+
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].
Then access the {project_name} 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]
====
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. +
This example workflow uses a self-generated CA to provide an end-to-end workflow for demonstration purposes. Accessing the {project_name} 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.
====
==== (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
==== (Optional) Creating additional {project_name} link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#core_concepts_and_terms[realm and users] to be also exported
When performing link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/server_administration_guide/#export_import[{project_name} {project_version} server database export] only {project_name_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:
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:
. 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]
@ -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.]
[[sso-export-the-database]]
==== Export the {project_name_abbr} database as a JSON file on the OpenShift pod
==== Export the {project_name} database as a JSON file on the OpenShift pod
. Get the {project_name_abbr} deployment config and scale it down to zero.
. Get the {project_name} deployment config and scale it down to zero.
+
[subs="verbatim,macros,attributes"]
----
@ -649,13 +649,13 @@ deploymentconfig/sso-mysql
$ oc scale --replicas=0 dc sso
deploymentconfig "sso" scaled
----
. 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.
. Instruct the {project_name} {project_version} server deployed on {project_openshift_product_name} image to perform database export at {project_name} server boot time.
+
[subs="verbatim,macros,attributes"]
----
oc env dc/sso -e "JAVA_OPTS_APPEND=-Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=/tmp/demorealm-export.json"
----
. Scale the {project_name_abbr} deployment config back up. This will start the {project_name_abbr} server and export its database.
. Scale the {project_name} deployment config back up. This will start the {project_name} server and export its database.
+
[subs="verbatim,macros,attributes"]
----
@ -678,7 +678,7 @@ $ oc logs sso-4-ejr0k | grep 'Export'
==== Retrieve and import the exported JSON file
. Retrieve the JSON file of the {project_name_abbr} database from the pod.
. Retrieve the JSON file of the {project_name} database from the pod.
+
[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 .
----
. (Optional) Import the JSON file of the {project_name_abbr} database into an {project_name_abbr} server running in another environment.
. (Optional) Import the JSON file of the {project_name} database into an {project_name} server running in another environment.
+
[NOTE]
====
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.
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.
====
+
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:
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:
.. 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 {project_name_abbr} realm, the users, clients, realm roles, and client roles should be imported to. This example uses `master` realm.
.. 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.
.. 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.
.. 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.
.. From the *Import from realm* drop-down menu, select the name of the {project_name} 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 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]
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_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.
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.
====
@ -737,13 +737,13 @@ The administration console import allows you to *overwrite* resources if you cho
====
[[OSE-SSO-AUTH-TUTE]]
=== Example Workflow: Configuring OpenShift to use {project_name_abbr} for Authentication
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.
=== Example Workflow: Configuring OpenShift to use {project_name} for Authentication
Configure OpenShift 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.
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.
This example adds {project_name} 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 {project_name_abbr} Credentials
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.
==== 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:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the {project_name} deployment.
*Create a Realm*
@ -752,7 +752,7 @@ Log in to the encrypted {project_name_abbr} web server at *$$https://secure-sso-
*Create a User*
Create a test user that can be used to demonstrate the {project_name_abbr}-enabled OpenShift login:
Create a test user that can be used to demonstrate the {project_name}-enabled OpenShift login:
. Click *Users* in the *Manage* sidebar to view the user information for the realm.
. Click *Add User*.
@ -790,7 +790,7 @@ identityProviders:
kind: HTPasswdPasswordIdentityProvider
----
+
Add {project_name_abbr} as a secondary identity provider with content similar to the following snippet:
Add {project_name} as a secondary identity provider with content similar to the following snippet:
+
[subs="verbatim,macros,attributes"]
----
@ -818,8 +818,8 @@ Add {project_name_abbr} as a secondary identity provider with content similar to
email:
- email
----
.. 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 {project_name_abbr} application. For example:
.. The {project_name} *Secret* hash for the *clientSecret* can be found in the {project_name} web console: *Clients* -> *_openshift-demo_* -> *Credentials*
.. The endpoints for the *urls* can be found by making a request with the {project_name} application. For example:
+
[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*.
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.
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:
[subs="verbatim,macros,attributes"]
@ -849,15 +849,15 @@ $ oadm policy add-role-to-user view testuser -n sso-app-demo
----
[[Example-EAP-Auto]]
=== 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 {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.
=== 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 JBoss EAP.
[NOTE]
====
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.
This example uses a OpenID-Connect client but an SAML client could also be used. See xref:SSO-Clients[{project_name} Clients] and xref: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_abbr} 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.
. 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
----
//. Create a service account to be used for the {project_name_abbr} deployment:
//. Create a service account to be used for the {project_name} deployment:
//+
//[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
----
==== Preparing the {project_name_abbr} Credentials
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.
==== 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:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the {project_name} deployment.
*Create a Realm*
@ -916,11 +916,11 @@ Log in to the encrypted {project_name_abbr} web server at *$$https://secure-sso-
*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 {project_name_abbr}-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}-enabled JBoss EAP image.
*Create a Role*
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.
Create a role in {project_name} 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} _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 *Add Role*.
@ -929,7 +929,7 @@ Create a role in {project_name_abbr} with a name that corresponds to the JEE rol
*Create Users and Assign Roles*
Create two users:
- 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 _realm management user_ the *realm-management* roles to handle automatic {project_name} client registration in the {project_name} server.
- Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications.
Create the _realm management user_:
@ -938,7 +938,7 @@ Create the _realm management user_:
. Click *Add User*.
. 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.
. 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.
. 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} server rights that can be used by the JBoss EAP image to create clients.
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.
. Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, add the role created earlier.
==== Deploy the {project_name_abbr}-enabled JBoss EAP Image
==== Deploy the {project_name}-enabled JBoss EAP Image
. 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.
. 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:
. Select the *_eap71-sso-s2i_* image to list all of the deployment parameters. Include the following {project_name} parameters to configure the {project_name} credentials during the EAP build:
+
[cols="2*", options="header"]
|===
@ -1007,25 +1007,25 @@ Create the _application user_:
It may take several minutes for the JBoss EAP image to deploy.
==== Log in to the JBoss EAP Server Using {project_name_abbr}
==== Log in to the JBoss EAP Server Using {project_name}
. Access the JBoss EAP application server and click *Login*. You are redirected to the {project_name_abbr} login.
. 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.
. Access the JBoss EAP 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 JBoss EAP application server.
[[Example-EAP-Manual]]
=== 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 {project_name_abbr} was deployed on OpenShift.
=== 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.
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.
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 JBoss EAP.
[NOTE]
====
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.
This example uses a SAML client but an OpenID-Connect client could also be used. See xref:SSO-Clients[{project_name} Clients] and xref: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_abbr} Credentials
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.
==== 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:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account] created during the {project_name} deployment.
*Create a Realm*
@ -1034,11 +1034,11 @@ Log in to the encrypted {project_name_abbr} web server at *$$https://secure-sso-
*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 {project_name_abbr}-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}-enabled JBoss EAP image.
*Create a Role*
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.
Create a role in {project_name} 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} _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 *Add Role*.
@ -1047,7 +1047,7 @@ Create a role in {project_name_abbr} with a name that corresponds to the JEE rol
*Create Users and Assign Roles*
Create two users:
- 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 _realm management user_ the *realm-management* roles to handle automatic {project_name} client registration in the {project_name} server.
- Assign the _application user_ the JEE role, created in the previous step, to authenticate access to user applications.
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.
////
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 {project_name_abbr} 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} server rights that can be used by the JBoss EAP image to create clients.
////
Create the _application user_:
@ -1071,7 +1071,7 @@ Create the _application user_:
*Create and Configure a SAML Client*:
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.
Clients are {project_name} 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:
@ -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 *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_abbr} 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.
. Create a new project:
@ -1158,7 +1158,7 @@ $ oc secrets link default eap-ssl-secret eap-jgroup-secret
[[modified-saml-xml]]
==== Modifying the *secure-saml-deployments* File
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.
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.
. 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_.
@ -1179,7 +1179,7 @@ The *keycloak-saml-subsystem.xml*, exported from the {project_name_abbr} client
----
+
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 {project_name_abbr} client.
The aliases and passwords for the *PrivateKey* and the *Certificate* were configured when the SAML Keys were exported from the {project_name} client.
. Delete the second *<CertificatePem>* tag and key and replace it with the the realm certificate information:
+
[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 {project_name_abbr} client.
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*
@ -1214,4 +1214,4 @@ Open the application *web.xml* file and ensure it includes the following:
==== Deploying the Application
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.
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.

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

@ -5,7 +5,6 @@
:project_versionMvn: 4.8.3.Final-redhat-00001
:project_versionNpm: 4.8.3.Final-redhat-00001
:project_images: rhsso-images
:project_openshift_product_name: RH-SSO for OpenShift
ifeval::[{project_product_cd}==false]
:project_name_full: Red Hat Single Sign-On
@ -31,6 +30,8 @@ ifeval::[{project_product_cd}==true]
:maven_repository: https://maven.repository.redhat.com/earlyaccess/
endif::[]
:project_openshift_product_name: {project_name} for OpenShift
:project_dirref: RHSSO_HOME
:quickstartRepo_name: {project_name} Quickstarts Repository