757 lines
35 KiB
Text
757 lines
35 KiB
Text
== Performing advanced procedures
|
|
|
|
[role="_abstract"]
|
|
This chapter describes advanced procedures, such as setting up keystores and a truststore for the {project_name} server, creating an administrator account, as well as an overview of available {project_name} client registration methods, and guidance on configuring clustering.
|
|
|
|
=== Deploying passthrough TLS termination templates
|
|
|
|
You can deploy using these templates. They require HTTPS, JGroups keystores and the {project_name} server truststore to already exist, and therefore can be used to instantiate the {project_name} server pod using your custom HTTPS, JGroups keystores and {project_name} server truststore.
|
|
|
|
==== Preparing the deployment
|
|
|
|
.Procedure
|
|
. Log in to the OpenShift CLI with a user that holds the _cluster:admin_ role.
|
|
|
|
. Create a new project:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc new-project sso-app-demo
|
|
----
|
|
. Add the `view` role to the link:{ocpdocs_default_service_accounts_link}[`default`] service account. This enables the service account to view all the resources in the sso-app-demo namespace, which is necessary for managing the cluster.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
|
|
----
|
|
|
|
[[Configuring-Keystores]]
|
|
==== Creating HTTPS and JGroups Keystores, and Truststore for the {project_name} Server
|
|
|
|
In this procedure, the *_openssl_* toolkit is used to generate a CA certificate to sign the HTTPS keystore, and create a truststore for the {project_name} server. The *_keytool_*, a package *included with the Java Development Kit*, is then used to generate self-signed certificates for these keystores.
|
|
|
|
The {project_name} application templates using xref:../introduction/introduction.adoc#reencrypt-templates[re-encryption TLS termination] do not *require* or *expect* the HTTPS and JGroups keystores and {project_name} server truststore to be prepared beforehand.
|
|
|
|
====
|
|
[NOTE]
|
|
If you want to provision the {project_name} server using existing HTTPS / JGroups keystores, use some of the passthrough templates instead.
|
|
====
|
|
|
|
The re-encryption templates use OpenShift's internal link:{ocpdocs_serving_x509_secrets_link}[service serving x509 certificate secrets] to automatically create the HTTPS and JGroups keystores.
|
|
|
|
The {project_name} server truststore is also created automatically, containing the */var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt* CA certificate file, which is used to create these cluster certificates. Moreover, the truststore for the {project_name} server is pre-populated with the all known, trusted CA certificate files found in the Java system path.
|
|
|
|
.Prerequisites
|
|
|
|
The {project_name} application templates using passthrough TLS termination require the following to be deployed:
|
|
|
|
* An xref:create-https-keystore[HTTPS keystore] used for encryption of https traffic,
|
|
* The xref:create-jgroups-keystore[JGroups keystore] used for encryption of JGroups communications between nodes in the cluster, and
|
|
* xref:create-server-truststore[{project_name} server truststore] used for securing the {project_name} requests
|
|
|
|
[NOTE]
|
|
====
|
|
For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS).
|
|
|
|
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]]
|
|
|
|
.Procedure
|
|
|
|
. Generate a CA certificate. Pick and remember the password. Provide identical password, when xref:signing-csr-with-ca-certificate[signing the certificate sign request with the CA certificate] below:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ openssl req -new -newkey rsa:4096 -x509 -keyout xpaas.key -out xpaas.crt -days 365 -subj "/CN=xpaas-sso-demo.ca"
|
|
----
|
|
. Generate a private key for the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ 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:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ 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]:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ openssl x509 -req <(printf "subjectAltName=DNS:secure-sso-sso-app-demo.openshift.example.com") -CA xpaas.crt -CAkey xpaas.key -in sso.csr -out sso.crt -days 365 -CAcreateserial
|
|
----
|
|
+
|
|
[NOTE]
|
|
====
|
|
To make the preceding command work on one line, the command includes the process substitution (`<() syntax`). Be sure that your current shell environment supports such syntax. Otherwise, you can encounter a `syntax error near unexpected token `('` message.
|
|
====
|
|
. Import the CA certificate into the HTTPS keystore. Provide `mykeystorepass` as the keystore password. Reply `yes` to `Trust this certificate? [no]:` question:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore keystore.jks
|
|
----
|
|
. Import the signed certificate sign request into the HTTPS keystore. Provide `mykeystorepass` as the keystore password:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ 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:
|
|
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ keytool -genseckey -alias secret-key -storetype JCEKS -keystore jgroups.jceks
|
|
----
|
|
|
|
[[create-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:
|
|
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ keytool -import -file xpaas.crt -alias xpaas.ca -keystore truststore.jks
|
|
----
|
|
|
|
[[Configuring-Secrets]]
|
|
==== Creating secrets
|
|
|
|
.Procedure
|
|
|
|
You create objects called secrets that OpenShift uses to hold sensitive information, such as passwords or keystores.
|
|
|
|
. Create the secrets for the HTTPS and JGroups keystores, and {project_name} server truststore, generated in the xref:Configuring-Keystores[previous section].
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc create secret generic sso-app-secret --from-file=keystore.jks --from-file=jgroups.jceks --from-file=truststore.jks
|
|
----
|
|
. Link these secrets to the default service account, which is used to run {project_name} pods.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc secrets link default sso-app-secret
|
|
----
|
|
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
* link:{ocpdocs_secrets_link}[What is a secret?]
|
|
* link:{ocpdocs_default_service_accounts_link}[Default project service accounts and roles]
|
|
|
|
==== Deploying a Passthrough TLS template using the OpenShift CLI
|
|
|
|
After you create xref:Configuring-Keystores[keystores] and xref:Configuring-Secrets[secrets], deploy a passthrough TLS termination template by using the `oc` command.
|
|
|
|
===== `oc` command guidelines
|
|
In the following `oc` command, the values of *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, *_HTTPS_PASSWORD_*, *_JGROUPS_ENCRYPT_PASSWORD_*, and *_SSO_TRUSTSTORE_PASSWORD_* variables match the default values in the *_{project_templates_version}-https_* {project_name} application template.
|
|
|
|
For production environments, Red Hat recommends that you consult the on-site policy for your organization for guidance on generating a strong user name and password for the administrator user account of the {project_name} server, and passwords for the HTTPS and JGroups keystores, and the truststore of the {project_name} server.
|
|
|
|
Also, when you create the template, make the passwords match the passwords provided when you created the keystores. If you used a different username or password, modify the values of the parameters in your template to match your environment.
|
|
|
|
[NOTE]
|
|
====
|
|
You can determine the alias names associated with the certificate by using the following *_keytool_* commands. The *_keytool_* is a package included with the Java Development Kit.
|
|
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ keytool -v -list -keystore keystore.jks | grep Alias
|
|
Enter keystore password: mykeystorepass
|
|
Alias name: xpaas.ca
|
|
Alias name: jboss
|
|
----
|
|
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ keytool -v -list -keystore jgroups.jceks -storetype jceks | grep Alias
|
|
Enter keystore password: password
|
|
Alias name: secret-key
|
|
----
|
|
|
|
The *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, and the *_SSO_REALM_* template parameters in the following command are optional.
|
|
====
|
|
|
|
===== Sample `oc` command
|
|
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc new-app --template={project_templates_version}-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/{project_templates_version}-https" to project sso-app-demo
|
|
|
|
{project_name} {project_version} (Ephemeral with passthrough TLS)
|
|
---------
|
|
An example {project_name} 7 application. For more information about using this template, see \https://github.com/jboss-openshift/application-templates.
|
|
|
|
A new {project_name} service has been created in your project. The admin username/password for accessing the master realm via the {project_name} console is 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
|
|
* 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
|
|
* {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 ...
|
|
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.
|
|
----
|
|
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
* xref:../introduction/introduction.adoc#passthrough-templates[Passthrough TLS Termination]
|
|
|
|
[[advanced-concepts-sso-hostname-spi-setup]]
|
|
=== Customizing the Hostname for the {project_name} Server
|
|
|
|
The hostname SPI introduced a flexible way to configure the hostname for the {project_name} server.
|
|
The default hostname provider one is `default`. This provider provides enhanced functionality over the original `request` provider which is now deprecated. Without additional settings, it uses the request headers to determine the hostname similarly to the original `request` provider.
|
|
|
|
For configuration options of the `default` provider, refer to the {installguide_link}#_hostname[{installguide_name}].
|
|
The `frontendUrl` option can be configured via `SSO_FRONTEND_URL` environment variable.
|
|
|
|
[NOTE]
|
|
For backward compatibility, `SSO_FRONTEND_URL` settings is ignored if `SSO_HOSTNAME` is also set.
|
|
|
|
Another option of hostname provider is `fixed`, which allows configuring a fixed hostname. The latter makes sure that only valid hostnames can be used and allows internal applications to invoke the {project_name} server through an alternative URL.
|
|
|
|
.Procedure
|
|
|
|
Run the following commands to set the `fixed` hostname SPI provider for the {project_name} server:
|
|
|
|
. Deploy the {project_openshift_product_name} image with *_SSO_HOSTNAME_* environment variable set to the desired hostname of the {project_name} server.
|
|
+
|
|
[source,yaml,subs="verbatim,macros,attributes"]
|
|
----
|
|
$ oc new-app --template={project_templates_version}-x509-https \
|
|
-p SSO_HOSTNAME="rh-sso-server.openshift.example.com"
|
|
----
|
|
|
|
. Identify the name of the route for the {project_name} service.
|
|
+
|
|
[source,yaml,subs="verbatim,macros,attributes"]
|
|
----
|
|
$ oc get routes
|
|
NAME HOST/PORT
|
|
sso sso-sso-app-demo.openshift.example.com
|
|
----
|
|
|
|
. Change the `host:` field to match the hostname specified as the value of the *_SSO_HOSTNAME_* environment variable above.
|
|
+
|
|
[NOTE]
|
|
====
|
|
Adjust the `rh-sso-server.openshift.example.com` value in the following command as necessary.
|
|
====
|
|
+
|
|
----
|
|
$ oc patch route/sso --type=json -p '[{"op": "replace", "path": "/spec/host", "value": "rh-sso-server.openshift.example.com"}]'
|
|
----
|
|
+
|
|
If successful, the previous command will return the following output:
|
|
+
|
|
----
|
|
route "sso" patched
|
|
----
|
|
|
|
[[sso-connecting-to-an-external-database]]
|
|
=== Connecting to an external database
|
|
|
|
{project_name} can be configured to connect to an external (to OpenShift cluster) database. In order to achieve this, you need to modify the `sso-{database name}` Endpoints object to point to the proper address. The procedure is described in the link:{ocpdocs_ingress_service_external_ip_link}[OpenShift manual].
|
|
|
|
The easiest way to get started is to deploy {project_name} from a template and then modify the Endpoints object. You might also need to update some of the datasource configuration variables in the DeploymentConfig. Once you're done, just roll a new deployment out.
|
|
|
|
[[sso-using-custom-jdbc-driver]]
|
|
=== Using Custom JDBC Driver
|
|
|
|
To connect to any database, the JDBC driver for that database must be present and {project_name} configured
|
|
properly. Currently, the only JDBC driver available in the image is the PostgreSQL JDBC driver. For any other
|
|
database, you need to extend the {project_name} image with a custom JDBC driver and a CLI script to register
|
|
it and set up the connection properties. The following steps illustrate how to do that, taking MariaDB driver
|
|
as an example. Update the example for other database drivers accordingly.
|
|
|
|
.Procedure
|
|
|
|
. Create an empty directory.
|
|
. Download the JDBC driver binaries into this directory.
|
|
. Create a new `Dockerfile` file in this directory with the following contents. For other databases, replace `mariadb-java-client-2.5.4.jar` with the filename of the respective driver:
|
|
+
|
|
[source,subs="attributes+,macros+,+quotes"]
|
|
----
|
|
*FROM* {openshift_image_repository}:latest
|
|
|
|
*COPY* sso-extensions.cli /opt/eap/extensions/
|
|
*COPY* mariadb-java-client-2.5.4.jar /opt/eap/extensions/jdbc-driver.jar
|
|
----
|
|
. Create a new `sso-extensions.cli` file in this directory with the following contents. Update the values of the variables in italics according to the deployment needs:
|
|
+
|
|
[source,bash,subs="attributes+,macros+,+quotes"]
|
|
----
|
|
batch
|
|
|
|
set DB_DRIVER_NAME=_mariadb_
|
|
set DB_USERNAME=_username_
|
|
set DB_PASSWORD=_password_
|
|
set DB_DRIVER=_org.mariadb.jdbc.Driver_
|
|
set DB_XA_DRIVER=_org.mariadb.jdbc.MariaDbDataSource_
|
|
set DB_JDBC_URL=_jdbc:mariadb://jdbc-host/keycloak_
|
|
set DB_EAP_MODULE=_org.mariadb_
|
|
|
|
set FILE=/opt/eap/extensions/jdbc-driver.jar
|
|
|
|
module add --name=$DB_EAP_MODULE --resources=$FILE --dependencies=javax.api,javax.resource.api
|
|
/subsystem=datasources/jdbc-driver=$DB_DRIVER_NAME:add( \
|
|
driver-name=$DB_DRIVER_NAME, \
|
|
driver-module-name=$DB_EAP_MODULE, \
|
|
driver-class-name=$DB_DRIVER, \
|
|
driver-xa-datasource-class-name=$DB_XA_DRIVER \
|
|
)
|
|
/subsystem=datasources/data-source=KeycloakDS:remove()
|
|
/subsystem=datasources/data-source=KeycloakDS:add( \
|
|
jndi-name=java:jboss/datasources/KeycloakDS, \
|
|
enabled=true, \
|
|
use-java-context=true, \
|
|
connection-url=$DB_JDBC_URL, \
|
|
driver-name=$DB_DRIVER_NAME, \
|
|
user-name=$DB_USERNAME, \
|
|
password=$DB_PASSWORD \
|
|
)
|
|
|
|
run-batch
|
|
----
|
|
. In this directory, build your image by typing the following command, replacing the `project/name:tag` with arbitrary name. `docker` can be used instead of `podman`.
|
|
+
|
|
[source,bash,subs="attributes+,macros+,+quotes"]
|
|
----
|
|
podman build -t docker-registry-default/project/name:tag .
|
|
----
|
|
. After the build finishes, push your image to the registry used by OpenShift to deploy your image. Refer to the link:{ocpdocs_cluster_local_registry_access_link}[OpenShift guide] for details.
|
|
|
|
[[sso-administrator-setup]]
|
|
=== Creating the Administrator Account for {project_name} Server
|
|
|
|
{project_name} does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the `master` realm's management console and performing server maintenance operations such as creating realms or users or registering applications intended to be secured by {project_name}.
|
|
|
|
The administrator account can be created:
|
|
|
|
* 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]
|
|
====
|
|
{project_name} allows an initial administrator account to be created by the link:{project_doc_base_url}/getting_started_guide/index#create-admin_[Welcome Page] web form, but only if the Welcome Page is accessed from localhost; this method of administrator account creation is not applicable for the {project_openshift_product_name} image.
|
|
====
|
|
|
|
[[sso-admin-template-parameters]]
|
|
==== Creating the Administrator Account using template parameters
|
|
|
|
When deploying {project_name} application template, the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the {project_name} server's administrator account to be created for the `master` realm.
|
|
|
|
*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.
|
|
|
|
The lifespan of the {project_name} server's administrator account depends upon the storage type used to store the {project_name} server's database:
|
|
|
|
* For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates), the account exists throughout the lifecycle of the particular {project_name} pod (stored account data is lost upon pod destruction),
|
|
* For an ephemeral database mode *_{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}-postgresql-persistent_*, and *_{project_templates_version}-x509-postgresql-persistent_* templates), the account exists throughout the lifecycle of the persistent medium used to hold the database data. This means that the stored account data is preserved even when both the {project_name} and the database pods are destructed.
|
|
|
|
It is a common practice to deploy an {project_name} application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new {project_name} application needs to be instantiated).
|
|
|
|
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.
|
|
|
|
.Procedure
|
|
|
|
Run the following commands to prepare the previously created deployment config of the {project_name} application for reuse after the administrator account has been created:
|
|
|
|
. Identify the deployment config of the {project_name} application.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc get dc -o name
|
|
deploymentconfig/sso
|
|
deploymentconfig/sso-postgresql
|
|
----
|
|
. Clear the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables setting.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc set env dc/sso \
|
|
-e SSO_ADMIN_USERNAME="" \
|
|
-e SSO_ADMIN_PASSWORD=""
|
|
----
|
|
|
|
[[sso-admin-remote-shell]]
|
|
==== Creating the Administrator Account via a remote shell session to {project_name} Pod
|
|
|
|
You use the following commands to create an administrator account for the `master` realm of the {project_name} server, when deploying the {project_openshift_product_name} image directly from the image stream without using a template.
|
|
|
|
.Prerequisite
|
|
|
|
* {project_name} application pod has been started.
|
|
|
|
.Procedure
|
|
|
|
. Identify the {project_name} application pod.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc get pods
|
|
NAME READY STATUS RESTARTS AGE
|
|
sso-12-pt93n 1/1 Running 0 1m
|
|
sso-postgresql-6-d97pf 1/1 Running 0 2m
|
|
----
|
|
. Open a remote shell session to the {project_openshift_product_name} container.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc rsh sso-12-pt93n
|
|
sh-4.2$
|
|
----
|
|
. Create the {project_name} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
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.
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
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 {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 Admin Console of the {project_name} server using the credentials created in the steps above. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the {project_name} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server, and specify the user name and password used to create the administrator user.
|
|
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
* xref:../introduction/introduction.adoc#sso-templates[Templates for use with this software]
|
|
|
|
=== Customizing the default behavior of the {project_name} image
|
|
|
|
You can change the default behavior of the {project_name} image such as enabling TechPreview features or enabling debugging. This section describes how to make this change by using the JAVA_OPTS_APPEND variable.
|
|
|
|
.Prerequisites
|
|
|
|
This procedure assumes that the {project_openshift_product_name} image has been previously xref:Example-Deploying-SSO[deployed using one of the following templates:]
|
|
|
|
* *_{project_templates_version}-postgresql_*
|
|
* *_{project_templates_version}-postgresql-persistent_*
|
|
* *_{project_templates_version}-x509-postgresql-persistent_*
|
|
|
|
.Procedure
|
|
|
|
You can use the OpenShift web console or the CLI to change the default behavior.
|
|
|
|
If you use the OpenShift web console, you add the JAVA_OPTS_APPEND variable to the sso deployment config. For example, to enable TechPreview features, you set the variable as follows:
|
|
|
|
[source,bash,subs=+attributes]
|
|
----
|
|
JAVA_OPTS_APPEND="-Dkeycloak.profile=preview"
|
|
----
|
|
|
|
If you use the CLI, use the following commands to enable TechPreview features when the {project_name} pod was deployed using a template that is mentioned under Prerequisites.
|
|
|
|
. Scale down the {project_name} pod:
|
|
|
|
+
|
|
[source,bash,subs=+attributes]
|
|
----
|
|
$ oc get dc -o name
|
|
deploymentconfig/sso
|
|
deploymentconfig/sso-postgresql
|
|
|
|
$ oc scale --replicas=0 dc sso
|
|
deploymentconfig "sso" scaled
|
|
----
|
|
|
|
+
|
|
[NOTE]
|
|
====
|
|
In the preceding command, ``sso-postgresql`` appears because a PostgreSQL template was used to deploy the {project_openshift_product_name} image.
|
|
====
|
|
|
|
. Edit the deployment config to set the JAVA_OPTS_APPEND variable. For example, to enable TechPreview features, you set the variable as follows:
|
|
|
|
+
|
|
[source,bash,subs=+attributes]
|
|
----
|
|
oc env dc/sso -e "JAVA_OPTS_APPEND=-Dkeycloak.profile=preview"
|
|
----
|
|
|
|
. Scale up the {project_name} pod:
|
|
|
|
+
|
|
[source,bash,subs=+attributes]
|
|
----
|
|
$ oc scale --replicas=1 dc sso
|
|
deploymentconfig "sso" scaled
|
|
----
|
|
|
|
. Test a TechPreview feature of your choice.
|
|
|
|
|
|
=== Deployment process
|
|
|
|
Once deployed, the *_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates create a single pod that contains both the database and the {project_name} servers. The *_{project_templates_version}-postgresql_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-postgresql-persistent_* templates create two pods, one for the database server and one for the {project_name} web server.
|
|
|
|
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} web server, and
|
|
* *\https://secure-sso-_<project-name>_._<hostname>_/auth/admin*: for the encrypted {project_name} web server.
|
|
|
|
Use the xref:sso-administrator-setup[administrator user credentials] to log in into the `master` realm's Admin Console.
|
|
|
|
[[SSO-Clients]]
|
|
=== {project_name} clients
|
|
|
|
Clients are {project_name} entities that request user authentication. A client can be an application requesting {project_name} to provide user authentication, or it can be making requests for access tokens to start services on behalf of an authenticated user. See the link:{project_doc_base_url}/server_administration_guide/index#assembly-managing-clients_server_administration_guide[Managing Clients chapter of the {project_name} documentation] for more information.
|
|
|
|
{project_name} provides link:{project_doc_base_url}/server_administration_guide/clients#oidc_clients[OpenID-Connect] and link:{project_doc_base_url}/server_administration_guide/index#client-saml-configuration[SAML] client protocols.
|
|
|
|
OpenID-Connect is the preferred protocol and uses three different access types:
|
|
|
|
- *public*: Useful for JavaScript applications that run directly in the browser and require no server configuration.
|
|
- *confidential*: Useful for server-side clients, such as EAP web applications, that need to perform a browser login.
|
|
- *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:
|
|
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
...
|
|
<login-config>
|
|
<auth-method>KEYCLOAK</auth-method>
|
|
</login-config>
|
|
...
|
|
----
|
|
|
|
[[Auto-Man-Client-Reg]]
|
|
==== Automatic and manual {project_name} client registration methods
|
|
A client application can be automatically registered to an {project_name} realm by using credentials passed in variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates.
|
|
|
|
Alternatively, you can manually register the client application by configuring and exporting the {project_name} client adapter and including it in the client application configuration.
|
|
|
|
===== Automatic {project_name} client registration
|
|
|
|
Automatic {project_name} client registration 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} environment variables included in the *_eap64-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 {project_name} web server authentication address: $$https://secure-sso-$$_<project-name>_._<hostname>_/auth
|
|
|
|
|*_SSO_REALM_*
|
|
|The {project_name} 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 {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} adapter enables Cross-Origin Resource Sharing (CORS).
|
|
|===
|
|
|
|
If the {project_name} 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 {project_name} with OpenID-Connect Client] for an end-to-end example of the automatic client registration method using an OpenID-Connect client.
|
|
|
|
===== Manual {project_name} client registration
|
|
|
|
Manual {project_name} client registration 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} adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed.
|
|
|
|
There are two methods for passing the {project_name} adapter configuration to the client application:
|
|
|
|
* 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} Authentication, Using SAML Client] for an end-to-end example of the manual {project_name} client registration method using a SAML client.
|
|
|
|
=== Using {project_name} vault with OpenShift secrets
|
|
Several fields in the {project_name} administration support obtaining the value
|
|
of a secret from an external vault, see link:{adminguide_link}#_vault-administration[{adminguide_name}].
|
|
The following example shows how to set up the file-based plaintext vault in OpenShift
|
|
and set it up to be used for obtaining an SMTP password.
|
|
|
|
.Procedure
|
|
|
|
. Specify a directory for the vault using the *_SSO_VAULT_DIR_* environment variable.
|
|
You can introduce the *_SSO_VAULT_DIR_* environment variable directly in the environment in your deployment configuration. It can also be included in the template by addding the following snippets at the appropriate places in the template:
|
|
+
|
|
[source,json,subs="attributes+,macros+"]
|
|
----
|
|
"parameters": [
|
|
...
|
|
{
|
|
"displayName": "RH-SSO Vault Secret directory",
|
|
"description": "Path to the RH-SSO Vault directory.",
|
|
"name": "SSO_VAULT_DIR",
|
|
"value": "",
|
|
"required": false
|
|
}
|
|
...
|
|
]
|
|
|
|
env: [
|
|
...
|
|
{
|
|
"name": "SSO_VAULT_DIR",
|
|
"value": "${SSO_VAULT_DIR}"
|
|
}
|
|
...
|
|
]
|
|
----
|
|
|
|
+
|
|
[NOTE]
|
|
====
|
|
The files plaintext vault provider will be configured only when you set
|
|
*_SSO_VAULT_DIR_* environment variable.
|
|
====
|
|
|
|
. Create a secret in your OpenShift cluster:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc create secret generic rhsso-vault-secrets --from-literal=master_smtp-password=mySMTPPsswd
|
|
----
|
|
|
|
. Mount a volume to your deployment config using the `${SSO_VAULT_DIR}` as the path.
|
|
For a deployment that is already running:
|
|
+
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
oc set volume dc/sso --add --mount-path=${SSO_VAULT_DIR} --secret-name=rhsso-vault-secrets
|
|
----
|
|
|
|
. After a pod is created you can use a customized string within your {project_name}
|
|
configuration to refer to the secret. For example, for using `mySMTPPsswd` secret
|
|
created in this tutorial, you can use `${vault.smtp-password}` within the `master`
|
|
realm in the configuration of the smtp password and it will be replaced by `mySMTPPsswd` when used.
|
|
|
|
|
|
=== Limitations
|
|
OpenShift does not currently accept OpenShift role mapping from external providers. If {project_name} is used as an authentication gateway for OpenShift, users created in {project_name} must have the roles added using the OpenShift Administrator `oc adm policy` command.
|
|
|
|
For example, to allow an {project_name}-created user to view a project namespace in OpenShift:
|
|
[source,bash,subs="attributes+,macros+"]
|
|
----
|
|
$ oc adm policy add-role-to-user view <pass:quotes[_user-name_]> -n <pass:quotes[_project-name_]>
|
|
----
|