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.
. 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.
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} server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores.
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:
.. 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]:
.. Import the CA certificate into the HTTPS keystore. Provide `mykeystorepass` as the keystore password. Reply `yes` to `Trust this certificate? [no]:` question:
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} server truststore, generated in the xref:Configuring-Keystores[previous section].
. 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.
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:
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} 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.
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:
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.
The hostname SPI introduced a flexible way to configure the hostname for the {project_name} server. There are two built-in providers. The first is `request`, which uses the request headers to determine the hostname. This is the *default setting* for {project_openshift_product_name} image. The second 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 {project_name} server through an alternative URL.
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.
{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 has been described in https://docs.okd.io/latest/dev_guide/expose_service/expose_internal_ip_service.html#manually-assign-ip-service[OpenShift manual].
Tip: The easiest way to get started is to deploy {project_name} from a template and then modify the Endpoints object. You might also need to update some of the datasource configuration variables in the DeploymentConfig. Once you're done, just roll a new deployment out.
{project_name} does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the `master` realm's management console and perform server maintenance operations such as, creating realms or users, or registering applications intended to be secured by {project_name}.
* 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.
{project_name} allows an initial administrator account to be created via the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/getting_started_guide/#creating_the_admin_account[Welcome Page] web form, but only if the Welcome Page is accessed from localhost; this method of administrator account creation is not applicable for the {project_openshift_product_name} image.
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.
* 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} 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.
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:
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:
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.
When restarting the server it is important to restart just the JBoss EAP process within the running {project_name} container, and not the whole container. This is because restarting the whole container will recreate it from scratch, without the {project_name} server administration account for the `master` realm.
. Log in to the `master` realm's administration console of the {project_name} server using the credentials created in the steps above. In the browser, navigate to *\http://sso-<project-name>.<hostname>/auth/admin* for the {project_name} web server, or to *\https://secure-sso-<project-name>.<hostname>/auth/admin* for the encrypted {project_name} web server, and specify the user name and password used to create the administrator user.
=== 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 link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:]
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-mysql
$ oc scale --replicas=0 dc sso
deploymentconfig "sso" scaled
----
+
[NOTE]
====
In the preceding command, ``sso-mysql`` appears because a MySQL template was used to deploy the {project_openshift_product_name} image. However, if a PostgreSQL template was used, the name of the deployment config of the PostgreSQL pod would be ``sso-postgresql``.
====
. Edit the deployment config to set the JAVA_OPTS_APPEND variable. For example, to enable TechPreview features, you set the variable as follows:
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.
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.
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:
==== 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 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.
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 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:
* 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
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.
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.
