keycloak-scim/openshift/topics/advanced_concepts.adoc

== Advanced Concepts

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} Templates

==== Preparing the Deployment
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

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} server truststore] used for securing the {project_name} requests

the {project_openshift_product_name} image to be deployed properly.

[IMPORTANT]
====
The {project_name} application templates using xref:../introduction/introduction.adoc#reencrypt-templates[re-encryption TLS termination] do not *require* or *expect* the aforementioned HTTPS and JGroups keystores and {project_name} server truststore to be prepared beforehand. The templates use OpenShift's internal link:{ocpdocs_serving_x509_secrets_link}[service serving x509 certificate secrets] to automatically create the HTTPS and JGroups keystores. The {project_name} server truststore is also created automatically, containing the */var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt* CA certificate file, which is used to create these cluster certificates. Moreover, the truststore for the {project_name} server is pre-populated with the all known, trusted CA certificate files found in the Java system path.
====

The *_openssl_* toolkit is used in the following example to generate a CA certificate to sign the HTTPS keystore, and create a truststore for the {project_name} server. *_keytool_*, a package *included with the Java Development Kit*, is then utilized to the generate self-signed certificates for these keystores.

[WARNING]
====
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:
+
[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 CA certificate 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 -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:
+
[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]]
==== Secrets

OpenShift uses objects called link:{ocpdocs_secrets_link}[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].
+
[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 link:{ocpdocs_default_service_accounts_link}[default] service account, which is used to run {project_name} pods.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc secrets link default sso-app-secret
----

==== Deploying the Chosen {project_name} Passthrough TLS Template via OpenShift CLI

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} 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.
====

[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:

[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
----

Finally, the *_SSO_ADMIN_USERNAME_*, *_SSO_ADMIN_PASSWORD_*, and the *_SSO_REALM_* template parameters in the following command are optional.
====

[[advanced-topics-deploy-{project_templates_version}-https-template]]
[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.
----

[[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.

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.
+
----
$ oc new-app --template=sso-cd-x509-https \
  -p SSO_HOSTNAME="rh-sso-server.openshift.example.com"
----
. Identify the name of the route for the {project_name} service.
+
----
$ oc get routes
----
+
[cols="7",options="header"]
|===
|NAME
|HOST/PORT
|PATH
|SERVICES
|PORT
|TERMINATION
|WILDCARD

|sso
|sso-sso-app-demo.openshift.example.com
|
|sso
|<all>
|reencrypt
|None
|===
. 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].

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.

[[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.

. 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}: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 perform 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 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 the Administrator Account Using Template Parameters

When deploying {project_name} application template, the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the {project_name} server's administrator account to be created for the `master` realm.

[NOTE]
====
*Both of these parameters are required.* If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated.
====

[IMPORTANT]
====
The lifespan of the {project_name} server's administrator account depends upon the storage type used to store the {project_name} server's database:

* For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates), the account exists throughout the lifecycle of the particular {project_name} pod (stored account data is lost upon pod destruction),
* 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).
====

[WARNING]
====
In the case of *ephemeral or persistent database mode*, after creating the RH_SSO server's administrator account, remove the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables from the deployment config before deploying new {project_name} applications.
====

[IMPORTANT]
====
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 Remote Shell Session to {project_name} Pod

Run following commands to create an administrator account for the `master` realm of the {project_name} server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the {project_name} application pod has been started:

. 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 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:]

* *_{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 administration 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: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} 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:

[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 files plaintext vault in OpenShift
and set it up to be used for obtaining an SMTP password.

. 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_]>
----