KEYCLOAK-8161 remove unused adoc files
This commit is contained in:
Matthew Helmke
parent
1a05779398
commit
dcbee72e99
2 changed files with 0 additions and 633 deletions
|
|
@ -1,483 +0,0 @@
|
|||
These cover additional configuration topics, such as seting up keystores and a truststore for the RH-SSO server, creating an administrator account, an overview of available RH-SSO client registration methods, and guidance on configuring clustering.
|
||||
|
||||
=== Requirements and Deploying xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination] RH-SSO Templates
|
||||
|
||||
==== Preparing the Deployment
|
||||
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
|
||||
|
||||
. Create a new project:
|
||||
+
|
||||
----
|
||||
$ oc new-project sso-app-demo
|
||||
----
|
||||
. Add the `view` role to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. This enables the service account to view all the resources in the sso-app-demo namespace, which is necessary for managing the cluster.
|
||||
+
|
||||
----
|
||||
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
|
||||
----
|
||||
|
||||
[[Configuring-Keystores]]
|
||||
==== Creating HTTPS and JGroups Keystores, and Truststore for the RH-SSO Server
|
||||
|
||||
The RH-SSO 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[RH-SSO server truststore] used for securing the RH-SSO requests
|
||||
|
||||
the {project_openshift_product_name} image to be deployed properly.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
The RH-SSO application templates using xref:../introduction/introduction.adoc#reencrypt-templates[re-encryption TLS termination] do not *require* or *expect* the aforementioned HTTPS and JGroups keystores and RH-SSO server truststore to be prepared beforehand. The templates use OpenShift's internal link:https://docs.openshift.com/container-platform/latest/dev_guide/secrets.html#service-serving-certificate-secrets[service serving x509 certificate secrets] to automatically create the HTTPS and JGroups keystores. The RH-SSO server truststore is also created automatically, containing the */var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt* CA certificate file, which is used to create these cluster certificates. Moreover, the truststore for the RH-SSO server is pre-populated with the all known, trusted CA certificate files found in the Java system path.
|
||||
====
|
||||
|
||||
The *_openssl_* toolkit is used in the following example to generate a CA certificate to sign the HTTPS keystore, and create a truststore for the RH-SSO server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores.
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS).
|
||||
|
||||
See the https://access.redhat.com/documentation/en-us/jboss_enterprise_application_platform/6.1/html-single/security_guide/index#Generate_a_SSL_Encryption_Key_and_Certificate[JBoss Enterprise Application Platform Security Guide] for more information on how to create a keystore with self-signed or purchased SSL certificates.
|
||||
====
|
||||
|
||||
[[create-https-keystore]]
|
||||
*_Create the HTTPS keystore:_*
|
||||
|
||||
[[generate-ca-certificate]]
|
||||
.. Generate a CA certificate. Pick and remember the password. Provide identical password, when xref:signing-csr-with-ca-certificate[signing the certificate sign request with the CA certificate] below:
|
||||
+
|
||||
[subs="verbatim,macros"]
|
||||
----
|
||||
$ openssl req -new -newkey rsa:4096 -x509 -keyout xpaas.key -out xpaas.crt -days 365 -subj "/CN=xpaas-sso-demo.ca"
|
||||
----
|
||||
.. Generate a CA certificate for the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
|
||||
+
|
||||
----
|
||||
$ keytool -genkeypair -keyalg RSA -keysize 2048 -dname "CN=secure-sso-sso-app-demo.openshift.example.com" -alias jboss -keystore keystore.jks
|
||||
----
|
||||
.. Generate a certificate sign request for the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
|
||||
+
|
||||
----
|
||||
$ keytool -certreq -keyalg rsa -alias jboss -keystore keystore.jks -file sso.csr
|
||||
----
|
||||
|
||||
[[signing-csr-with-ca-certificate]]
|
||||
[start=4]
|
||||
.. Sign the certificate sign request with the CA certificate. Provide the same password that was used to xref:generate-ca-certificate[generate the CA certificate]:
|
||||
+
|
||||
----
|
||||
$ openssl x509 -req -CA xpaas.crt -CAkey xpaas.key -in sso.csr -out sso.crt -days 365 -CAcreateserial
|
||||
----
|
||||
.. Import the CA certificate into the HTTPS keystore. Provide `mykeystorepass` as the keystore password. Reply `yes` to `Trust this certificate? [no]:` question:
|
||||
+
|
||||
----
|
||||
$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore keystore.jks
|
||||
----
|
||||
.. Import the signed certificate sign request into the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
|
||||
+
|
||||
----
|
||||
$ keytool -import -file sso.crt -alias jboss -keystore keystore.jks
|
||||
----
|
||||
|
||||
[[create-jgroups-keystore]]
|
||||
*_Generate a secure key for the JGroups keystore:_*
|
||||
|
||||
Provide `password` as the keystore password:
|
||||
|
||||
----
|
||||
$ keytool -genseckey -alias secret-key -storetype JCEKS -keystore jgroups.jceks
|
||||
----
|
||||
|
||||
[[create-server-truststore]]
|
||||
*_Import the CA certificate into a new RH-SSO server truststore:_*
|
||||
|
||||
Provide `mykeystorepass` as the truststore password. Reply `yes` to `Trust this certificate? [no]:` question:
|
||||
|
||||
----
|
||||
$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore truststore.jks
|
||||
----
|
||||
|
||||
[[Configuring-Secrets]]
|
||||
==== Secrets
|
||||
|
||||
OpenShift uses objects called link:https://docs.openshift.com/container-platform/latest/dev_guide/secrets.html[secrets] to hold sensitive information, such as passwords or keystores.
|
||||
|
||||
. Create the secrets for the HTTPS and JGroups keystores, and RH-SSO server truststore, generated in the xref:Configuring-Keystores[previous section].
|
||||
+
|
||||
----
|
||||
$ oc secret new sso-app-secret keystore.jks jgroups.jceks truststore.jks
|
||||
----
|
||||
. Link these secrets to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[default] service account, which is used to run RH-SSO pods.
|
||||
+
|
||||
----
|
||||
$ oc secrets link default sso-app-secret
|
||||
----
|
||||
|
||||
==== Deploying the Chosen RH-SSO 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-sso72-https-template[in the following command] have been chosen to match the default values of the respective parameters of the *_sso72-https_* RH-SSO application template.
|
||||
|
||||
For production environments, Red Hat recommends that you consult the on-site policy, specific to your organization for guidance on how to generate sufficiently strong user name and password for the administrator user account of the RH-SSO server, and passwords for the HTTPS and JGroups keystores, and the truststore of the RH-SSO server.
|
||||
|
||||
Be aware that *the passwords provided when provisioning the template need to match the passwords provided when creating the keystores*. If using different username and passwords, modify the values of respective xref:advanced-topics-deploy-sso72-https-template[template parameters] as appropriate for your environment.
|
||||
====
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The following commands using the *_keytool_*, a package *included with the Java Development Kit*, can be used to determine the names associated with the certificate:
|
||||
|
||||
----
|
||||
$ keytool -v -list -keystore keystore.jks | grep Alias
|
||||
Enter keystore password: mykeystorepass
|
||||
Alias name: xpaas.ca
|
||||
Alias name: jboss
|
||||
----
|
||||
|
||||
----
|
||||
$ keytool -v -list -keystore jgroups.jceks -storetype jceks | grep Alias
|
||||
Enter keystore password: password
|
||||
Alias name: secret-key
|
||||
----
|
||||
|
||||
Finally, the *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, and the *_SSO_REALM_* template parameters in the following command are optional.
|
||||
====
|
||||
|
||||
[[advanced-topics-deploy-sso72-https-template]]
|
||||
----
|
||||
$ oc new-app --template=sso72-https \
|
||||
-p HTTPS_SECRET="sso-app-secret" \
|
||||
-p HTTPS_KEYSTORE="keystore.jks" \
|
||||
-p HTTPS_NAME="jboss" \
|
||||
-p HTTPS_PASSWORD="mykeystorepass" \
|
||||
-p JGROUPS_ENCRYPT_SECRET="sso-app-secret" \
|
||||
-p JGROUPS_ENCRYPT_KEYSTORE="jgroups.jceks" \
|
||||
-p JGROUPS_ENCRYPT_NAME="secret-key" \
|
||||
-p JGROUPS_ENCRYPT_PASSWORD="password" \
|
||||
-p SSO_ADMIN_USERNAME="admin" \
|
||||
-p SSO_ADMIN_PASSWORD="redhat" \
|
||||
-p SSO_REALM="demorealm" \
|
||||
-p SSO_TRUSTSTORE="truststore.jks" \
|
||||
-p SSO_TRUSTSTORE_PASSWORD="mykeystorepass" \
|
||||
-p SSO_TRUSTSTORE_SECRET="sso-app-secret"
|
||||
--> Deploying template "openshift/sso72-https" to project sso-app-demo
|
||||
|
||||
Red Hat Single Sign-On 7.2 (Ephemeral with passthrough TLS)
|
||||
---------
|
||||
An example RH-SSO 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates.
|
||||
|
||||
A new RH-SSO service has been created in your project. The admin username/password for accessing the master realm via the RH-SSO console is admin/redhat. Please be sure to create the following secrets: "sso-app-secret" containing the keystore.jks file used for serving secure content; "sso-app-secret" containing the jgroups.jceks file used for securing JGroups communications; "sso-app-secret" containing the truststore.jks file used for securing RH-SSO requests.
|
||||
|
||||
* With parameters:
|
||||
* Application Name=sso
|
||||
* Custom http Route Hostname=
|
||||
* Custom https Route Hostname=
|
||||
* Server Keystore Secret Name=sso-app-secret
|
||||
* Server Keystore Filename=keystore.jks
|
||||
* Server Keystore Type=
|
||||
* Server Certificate Name=jboss
|
||||
* Server Keystore Password=mykeystorepass
|
||||
* Datasource Minimum Pool Size=
|
||||
* Datasource Maximum Pool Size=
|
||||
* Datasource Transaction Isolation=
|
||||
* JGroups Secret Name=sso-app-secret
|
||||
* JGroups Keystore Filename=jgroups.jceks
|
||||
* JGroups Certificate Name=secret-key
|
||||
* JGroups Keystore Password=password
|
||||
* JGroups Cluster Password=yeSppLfp # generated
|
||||
* ImageStream Namespace=openshift
|
||||
* RH-SSO Administrator Username=admin
|
||||
* RH-SSO Administrator Password=redhat
|
||||
* RH-SSO Realm=demorealm
|
||||
* RH-SSO Service Username=
|
||||
* RH-SSO Service Password=
|
||||
* RH-SSO Trust Store=truststore.jks
|
||||
* RH-SSO Trust Store Password=mykeystorepass
|
||||
* RH-SSO Trust Store Secret=sso-app-secret
|
||||
* Container Memory Limit=1Gi
|
||||
|
||||
--> Creating resources ...
|
||||
service "sso" created
|
||||
service "secure-sso" created
|
||||
service "sso-ping" created
|
||||
route "sso" created
|
||||
route "secure-sso" created
|
||||
deploymentconfig "sso" created
|
||||
--> Success
|
||||
Run 'oc status' to view your app.
|
||||
----
|
||||
|
||||
==== Accessing the Administrator Console of the RH-SSO Pod
|
||||
|
||||
After the template got deployed, identify the available routes:
|
||||
|
||||
----
|
||||
$ oc get routes
|
||||
----
|
||||
|
||||
[cols="7",options="header"]
|
||||
|===
|
||||
|NAME |HOST/PORT |PATH |SERVICES |PORT |TERMINATION |WILDCARD
|
||||
|
||||
|secure-sso
|
||||
|secure-sso-sso-app-demo.openshift.example.com
|
||||
|
|
||||
|secure-sso
|
||||
|<all>
|
||||
|passthrough
|
||||
|None
|
||||
|
||||
|sso
|
||||
|sso-sso-app-demo.openshift.example.com
|
||||
|
|
||||
|sso
|
||||
|<all>
|
||||
|
|
||||
|None
|
||||
|===
|
||||
|
||||
and access the RH-SSO administrator console at:
|
||||
|
||||
* *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
|
||||
* *\http://sso-sso-app-demo.openshift.example.com/auth/admin*
|
||||
|
||||
using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account].
|
||||
|
||||
[[sso-administrator-setup]]
|
||||
=== Creating Administrator Account for Red Hat Single Sign-On Server
|
||||
|
||||
Red Hat Single Sign-On does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the `master` realm's management console and perform server maintenance operations such as, creating realms or users, or registering applications intended to be secured by Red Hat Single Sign-On.
|
||||
|
||||
The administrator account can be created:
|
||||
|
||||
* By providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the RH-SSO application template, or
|
||||
* By xref:sso-admin-remote-shell[a remote shell session to particular RH-SSO pod], if the {project_openshift_product_name} image is deployed without an application template.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Red Hat Single Sign-On allows an initial administrator account to be created via the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/getting_started_guide/#creating_the_admin_account[Welcome Page] web form, but only if the Welcome Page is accessed from localhost; this method of administrator account creation is not applicable for the {project_openshift_product_name} image.
|
||||
====
|
||||
|
||||
[[sso-admin-template-parameters]]
|
||||
==== Creating RH-SSO Administrator Account via Template Parameters
|
||||
|
||||
When deploying RH-SSO application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the RH-SSO server's administrator account to be created for the `master` realm.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
*Both of these parameters are required.* If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated.
|
||||
====
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
The lifespan of the RH-SSO server's administrator account depends upon the storage type used to store the RH-SSO server's database:
|
||||
|
||||
* For an in-memory database mode (*_sso72-https_* and *_sso72-x509-https_* templates) the account exists throughout the lifecycle of the particular RH-SSO pod (stored account data is lost upon pod destruction),
|
||||
* For an ephemeral database mode (*_sso72-mysql_* and *_sso72-postgresql_* templates) the account exists throughout the lifecycle of the database pod (even if the RH-SSO pod is destructed, the stored account data is preserved under the assumption that the database pod is still running),
|
||||
* For persistent database mode (*_sso72-mysql-persistent_*, *_sso72-x509-mysql-persistent_*, *_sso72-postgresql-persistent_*, and *_sso72-x509-postgresql-persistent_* templates) the account exists throughout the lifecycle of the persistent medium used to hold the database data. This means that the stored account data is preserved even when both the RH-SSO and the database pods are destructed.
|
||||
|
||||
It is a common practice to deploy an RH-SSO application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new RH-SSO application needs to be instantiated).
|
||||
====
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
In the case of *ephemeral or persistent database mode*, after creating the RH_SSO server's administrator account, remove the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables from the deployment config before deploying new RH-SSO applications.
|
||||
====
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
Run the following commands to prepare the previously created deployment config of the RH-SSO application for reuse after the administrator account has been created:
|
||||
|
||||
. Identify the deployment config of the RH-SSO application.
|
||||
+
|
||||
----
|
||||
$ oc get dc -o name
|
||||
deploymentconfig/sso
|
||||
deploymentconfig/sso-mysql
|
||||
----
|
||||
. Clear the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables setting.
|
||||
+
|
||||
----
|
||||
$ oc env dc/sso -e SSO_ADMIN_USERNAME="" SSO_ADMIN_PASSWORD=""
|
||||
----
|
||||
====
|
||||
|
||||
[[sso-admin-remote-shell]]
|
||||
==== Creating RH-SSO Administrator Account via Remote Shell Session to RH-SSO Pod
|
||||
|
||||
Run following commands to create an administrator account for the `master` realm of the RH-SSO server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the RH-SSO application pod has been started:
|
||||
|
||||
. Identify the RH-SSO application pod.
|
||||
+
|
||||
----
|
||||
$ oc get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
sso-12-pt93n 1/1 Running 0 1m
|
||||
sso-mysql-6-d97pf 1/1 Running 0 2m
|
||||
----
|
||||
. Open a remote shell session to the {project_openshift_product_name} container.
|
||||
+
|
||||
----
|
||||
$ oc rsh sso-12-pt93n
|
||||
sh-4.2$
|
||||
----
|
||||
. Create the RH-SSO server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
|
||||
+
|
||||
----
|
||||
sh-4.2$ cd /opt/eap/bin/
|
||||
sh-4.2$ ./add-user-keycloak.sh -r master -u sso_admin -p sso_password
|
||||
Added 'sso_admin' to '/opt/eap/standalone/configuration/keycloak-add-user.json', restart server to load user
|
||||
----
|
||||
+
|
||||
[NOTE]
|
||||
====
|
||||
The `sso_admin`/`sso_password` credentials in the example above are for demonstration purposes only. Refer to the password policy applicable within your organization for guidance on how to create a secure user name and password.
|
||||
====
|
||||
. Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly.
|
||||
+
|
||||
----
|
||||
sh-4.2$ ./jboss-cli.sh --connect ':reload'
|
||||
{
|
||||
"outcome" => "success",
|
||||
"result" => undefined
|
||||
}
|
||||
----
|
||||
+
|
||||
[WARNING]
|
||||
====
|
||||
When restarting the server it is important to restart just the JBoss EAP process within the running RH-SSO container, and not the whole container. This is because restarting the whole container will recreate it from scratch, without the RH-SSO server administration account for the `master` realm.
|
||||
====
|
||||
. Log in to the `master` realm's administration console of the RH-SSO server using the credentials created in the steps above. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the RH-SSO web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted RH-SSO web server, and specify the user name and password used to create the administrator user.
|
||||
|
||||
=== Deployment Process
|
||||
|
||||
Once deployed, the *_sso72-https_* and *_sso72-x509-https_* templates create a single pod that contains both the database and the RH-SSO servers. The *_sso72-mysql_*, *_sso72-mysql-persistent_*, *_sso72-x509-mysql-persistent_*, *_sso72-postgresql_*, *_sso72-postgresql-persistent_*, and *_sso72-x509-postgresql-persistent_* templates create two pods, one for the database server and one for the RH-SSO web server.
|
||||
|
||||
After the RH-SSO web server pod has started, it can be accessed from its custom configured hostnames, or from the default hostnames:
|
||||
|
||||
* *\http://sso-_<project-name>_._<hostname>_/auth/admin*: for the RH-SSO web server, and
|
||||
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted RH-SSO web server.
|
||||
|
||||
Use the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator user credentials] to log in into the `master` realm’s administration console.
|
||||
|
||||
[[SSO-Clients]]
|
||||
=== RH-SSO Clients
|
||||
|
||||
Clients are RH-SSO entities that request user authentication. A client can be an application requesting RH-SSO to provide user authentication, or it can make requests for access tokens to start services on behalf of an authenticated user. See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients[Managing Clients chapter of the Red Hat Single Sign-On documentation] for more information.
|
||||
|
||||
RH-SSO provides link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#oidc_clients[OpenID-Connect] and link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#saml_clients[SAML] client protocols. +
|
||||
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.
|
||||
- *confidential*: Useful for server-side clients, such as EAP web applications, that need to perform a browser login.
|
||||
- *bearer-only*: Useful for back-end services that allow bearer token requests.
|
||||
|
||||
It is required to specify the client type in the *<auth-method>* key of the application *web.xml* file. This file is read by the image at deployment. Set the value of *<auth-method>* element to:
|
||||
|
||||
* *KEYCLOAK* for the OpenID Connect client.
|
||||
* *KEYCLOAK-SAML* for the SAML client.
|
||||
|
||||
The following is an example snippet for the application *web.xml* to configure an OIDC client:
|
||||
|
||||
----
|
||||
...
|
||||
<login-config>
|
||||
<auth-method>KEYCLOAK</auth-method>
|
||||
</login-config>
|
||||
...
|
||||
----
|
||||
|
||||
[[Auto-Man-Client-Reg]]
|
||||
==== Automatic and Manual RH-SSO Client Registration Methods
|
||||
A client application can be automatically registered to an RH-SSO realm by using credentials passed in variables specific to the *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates.
|
||||
|
||||
Alternatively, you can manually register the client application by configuring and exporting the RH-SSO client adapter and including it in the client application configuration.
|
||||
|
||||
===== Automatic RH-SSO Client Registration
|
||||
|
||||
Automatic RH-SSO client registration is determined by RH-SSO environment variables specific to the *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. The RH-SSO credentials supplied in the template are then used to register the client to the RH-SSO realm during deployment of the client application.
|
||||
|
||||
The RH-SSO environment variables included in the *_eap64-sso-s2i_*, *_eap70-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are:
|
||||
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Variable
|
||||
|Description
|
||||
|*_HOSTNAME_HTTP_*
|
||||
|Custom hostname for http service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>
|
||||
|
||||
|*_HOSTNAME_HTTPS_*
|
||||
|Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>
|
||||
|
||||
|*_SSO_URL_*
|
||||
|The RH-SSO web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|
||||
|
||||
|*_SSO_REALM_*
|
||||
|The RH-SSO realm created for this procedure.
|
||||
|
||||
|*_SSO_USERNAME_*
|
||||
|The name of the _realm management user_.
|
||||
|
||||
|*_SSO_PASSWORD_*
|
||||
| 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 RH-SSO 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 RH-SSO adapter enables Cross-Origin Resource Sharing (CORS).
|
||||
|===
|
||||
|
||||
If the RH-SSO client uses the SAML protocol, the following additional variables need to be configured:
|
||||
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Variable
|
||||
|Description
|
||||
|*_SSO_SAML_KEYSTORE_SECRET_*
|
||||
|Secret to use for access to SAML keystore. The default is _sso-app-secret_.
|
||||
|
||||
|*_SSO_SAML_KEYSTORE_*
|
||||
|Keystore filename in the SAML keystore secret. The default is _keystore.jks_.
|
||||
|
||||
|*_SSO_SAML_KEYSTORE_PASSWORD_*
|
||||
|Keystore password for SAML. The default is _mykeystorepass_.
|
||||
|
||||
|*_SSO_SAML_CERTIFICATE_NAME_*
|
||||
|Alias for keys/certificate to use for SAML. The default is _jboss_.
|
||||
|===
|
||||
|
||||
See xref:Example-EAP-Auto[Example Workflow: Automatically Registering EAP Application in RH-SSO with OpenID-Connect Client] for an end-to-end example of the automatic client registration method using an OpenID-Connect client.
|
||||
|
||||
===== Manual RH-SSO Client Registration
|
||||
|
||||
Manual RH-SSO client registration is determined by the presence of a deployment file in the client application's _../configuration/_ directory. These files are exported from the client adapter in the RH-SSO web console. The name of this file is different for OpenID-Connect and SAML clients:
|
||||
|
||||
[horizontal]
|
||||
*OpenID-Connect*:: _../configuration/secure-deployments_
|
||||
*SAML*:: _../configuration/secure-saml-deployments_
|
||||
|
||||
These files are copied to the RH-SSO adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed.
|
||||
|
||||
There are two methods for passing the RH-SSO adapter configuration to the client application:
|
||||
|
||||
* Modify the deployment file to contain the RH-SSO adapter configuration so that it is included in the _standalone-openshift.xml_ file at deployment, or
|
||||
* Manually include the OpenID-Connect _keycloak.json_ file, or the SAML _keycloak-saml.xml_ file in the client application's *../WEB-INF* directory.
|
||||
|
||||
See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use RH-SSO Authentication, Using SAML Client] for an end-to-end example of the manual RH-SSO client registration method using a SAML client.
|
||||
|
||||
=== Limitations
|
||||
OpenShift does not currently accept OpenShift role mapping from external providers. If RH-SSO is used as an authentication gateway for OpenShift, users created in RH-SSO must have the roles added using the OpenShift Administrator `oadm policy` command.
|
||||
|
||||
For example, to allow an RH-SSO-created user to view a project namespace in OpenShift:
|
||||
[subs="verbatim,macros"]
|
||||
----
|
||||
oadm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]>
|
||||
----
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
=== Using the {project_openshift_product_name} Image Streams and Application Templates
|
||||
Red Hat JBoss Middleware for OpenShift images are pulled on demand from the Red Hat Registry: link:https://access.redhat.com/containers/[registry.access.redhat.com]. To update to the latest {project_openshift_product_name} images, run the following commands:
|
||||
|
||||
. On your master host(s), ensure that you are logged in as a cluster administrator or a user with project administrator access to the global `openshift` project.
|
||||
+
|
||||
----
|
||||
$ oc login -u system:admin
|
||||
----
|
||||
. Run the following commands to update the core set of RH-SSO 7.2 resources for OpenShift in the `openshift` project:
|
||||
+
|
||||
----
|
||||
$ for resource in sso72-image-stream.json \
|
||||
sso72-https.json \
|
||||
sso72-mysql.json \
|
||||
sso72-mysql-persistent.json \
|
||||
sso72-postgresql.json \
|
||||
sso72-postgresql-persistent.json \
|
||||
sso72-x509-https.json \
|
||||
sso72-x509-mysql-persistent.json \
|
||||
sso72-x509-postgresql-persistent.json
|
||||
do
|
||||
oc replace -n openshift --force -f \
|
||||
https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.4.11/sso/${resource}
|
||||
done
|
||||
----
|
||||
. Run the following command to install the RH-SSO 7.2 OpenShift image streams in the `openshift` project:
|
||||
+
|
||||
----
|
||||
$ oc -n openshift import-image redhat-sso72-openshift:1.1
|
||||
----
|
||||
|
||||
[[Example-Deploying-SSO]]
|
||||
=== Deploying the {project_openshift_product_name} Image
|
||||
[[Preparing-SSO-Authentication-for-OpenShift-Deployment]]
|
||||
==== Preparing the Deployment
|
||||
Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
|
||||
|
||||
. Create a new project:
|
||||
+
|
||||
----
|
||||
$ oc new-project sso-app-demo
|
||||
----
|
||||
. Add the `view` role to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. This enables the service account to view all the resources in the sso-app-demo namespace, which is necessary for managing the cluster.
|
||||
+
|
||||
----
|
||||
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
|
||||
----
|
||||
|
||||
==== Deploying the {project_openshift_product_name} Image using Application Template
|
||||
|
||||
===== Deploying the Template via OpenShift CLI
|
||||
|
||||
. List the available RH-SSO application templates:
|
||||
+
|
||||
----
|
||||
$ oc get templates -n openshift -o name | grep -o 'sso72.\+'
|
||||
sso72-https
|
||||
sso72-mysql
|
||||
sso72-mysql-persistent
|
||||
sso72-postgresql
|
||||
sso72-postgresql-persistent
|
||||
sso72-x509-https
|
||||
sso72-x509-mysql-persistent
|
||||
sso72-x509-postgresql-persistent
|
||||
----
|
||||
. Deploy the selected one:
|
||||
+
|
||||
----
|
||||
$ oc new-app --template=sso72-x509-https
|
||||
--> Deploying template "openshift/sso72-x509-https" to project sso-app-demo
|
||||
|
||||
Red Hat Single Sign-On 7.2 (Ephemeral)
|
||||
---------
|
||||
An example RH-SSO 7 application. For more information about using this template, see https://github.com/jboss-openshift/application-templates.
|
||||
|
||||
A new RH-SSO service has been created in your project. The admin username/password for accessing the master realm via the RH-SSO console is IACfQO8v/nR7llVSVb4Dye3TNRbXoXhRpAKTmiCRc. The HTTPS keystore used for serving secure content, the JGroups keystore used for securing JGroups communications, and server truststore used for securing RH-SSO requests were automatically created via OpenShift's service serving x509 certificate secrets.
|
||||
|
||||
* With parameters:
|
||||
* Application Name=sso
|
||||
* JGroups Cluster Password=jg0Rssom0gmHBnooDF3Ww7V4Mu5RymmB # generated
|
||||
* Datasource Minimum Pool Size=
|
||||
* Datasource Maximum Pool Size=
|
||||
* Datasource Transaction Isolation=
|
||||
* ImageStream Namespace=openshift
|
||||
* RH-SSO Administrator Username=IACfQO8v # generated
|
||||
* RH-SSO Administrator Password=nR7llVSVb4Dye3TNRbXoXhRpAKTmiCRc # generated
|
||||
* RH-SSO Realm=
|
||||
* RH-SSO Service Username=
|
||||
* RH-SSO Service Password=
|
||||
* Container Memory Limit=1Gi
|
||||
|
||||
--> Creating resources ...
|
||||
service "sso" created
|
||||
service "secure-sso" created
|
||||
service "sso-ping" created
|
||||
route "sso" created
|
||||
route "secure-sso" created
|
||||
deploymentconfig "sso" created
|
||||
--> Success
|
||||
Run 'oc status' to view your app.
|
||||
----
|
||||
|
||||
===== Deploying the Template via OpenShift Web Console
|
||||
|
||||
Alternatively, perform the following steps to deploy the RH-SSO template via OpenShift web console:
|
||||
|
||||
. Log in to the OpenShift web console and select the _sso-app-demo_ project space.
|
||||
. Click *Add to Project*, then *Browse Catalog* to list the default image streams and templates.
|
||||
. Use the *Filter by Keyword* search bar to limit the list to those that match _sso_. You may need to click *Middleware*, then *Integration* to show the desired application template.
|
||||
. Select an RH-SSO application template. This example uses *_Red Hat Single Sign-On 7.2 (Ephemeral)_*.
|
||||
. Click *Next* in the *Information* step.
|
||||
. From the *Add to Project* drop-down menu, select the _sso-app-demo_ project space. Then click *Next*.
|
||||
. Select *Do not bind at this time* radio button in the *Binding* step. Click *Create* to continue.
|
||||
. In the *Results* step, click the *Continue to the project overview* link to verify the status of the deployment.
|
||||
|
||||
==== Accessing the Administrator Console of the RH-SSO Pod
|
||||
|
||||
After the template got deployed, identify the available routes:
|
||||
|
||||
----
|
||||
$ oc get routes
|
||||
----
|
||||
|
||||
[cols="7",options="header"]
|
||||
|===
|
||||
|NAME |HOST/PORT |PATH |SERVICES |PORT |TERMINATION |WILDCARD
|
||||
|
||||
|secure-sso
|
||||
|secure-sso-sso-app-demo.openshift.example.com
|
||||
|
|
||||
|secure-sso
|
||||
|<all>
|
||||
|reencrypt
|
||||
|None
|
||||
|
||||
|sso
|
||||
|sso-sso-app-demo.openshift.example.com
|
||||
|
|
||||
|sso
|
||||
|<all>
|
||||
|
|
||||
|None
|
||||
|===
|
||||
|
||||
and access the RH-SSO administrator console at:
|
||||
|
||||
* *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*
|
||||
* *\http://sso-sso-app-demo.openshift.example.com/auth/admin*
|
||||
|
||||
using the xref:../advanced_concepts/advanced_concepts.adoc#sso-administrator-setup[administrator account].
|
||||
Loading…
Reference in a new issue