keycloak-scim/openshift/topics/reference.adoc

== Reference

[[sso-artifact-repository-mirrors-section]]
=== Artifact repository mirrors

// This page describes MAVEN_MIRROR_URL variable usage
// It requires 'bcname' attribute to be set to the name of the product

[role="_abstract"]
A repository in Maven holds build artifacts and dependencies of various types
(all the project jars, library jar, plugins or any other project specific
artifacts). It also specifies locations from where to download artifacts from,
while performing the S2I build. Besides using central repositories, it is a
common practice for organizations to deploy a local custom repository (mirror).

Benefits of using a mirror are:

* Availability of a synchronized mirror, which is geographically closer and
  faster.
* Ability to have greater control over the repository content.
* Possibility to share artifacts across different teams (developers, CI),
  without the need to rely on public servers and repositories.
* Improved build times.

Often, a repository manager can serve as local cache to a mirror. Assuming that
the repository manager is already deployed and reachable externally at
*_pass:[http://10.0.0.1:8080/repository/internal/]_*, the S2I build can then use this
manager by supplying the `MAVEN_MIRROR_URL` environment variable to the
build configuration of the application using the following procedure:

.Procedure

. Identify the name of the build configuration to apply `MAVEN_MIRROR_URL`
  variable against.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc get bc -o name
buildconfig/sso
----
. Update build configuration of `sso` with a `MAVEN_MIRROR_URL` environment variable.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc set env bc/sso \
  -e MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/"
buildconfig "sso" updated
----
. Verify the setting.
+
[source,bash,subs="attributes+,macros+"]
----
$ oc set env bc/sso --list
# buildconfigs sso
MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/
----
. Schedule new build of the application.

NOTE: During application build, you will notice that Maven dependencies are
pulled from the repository manager, instead of the default public repositories.
Also, after the build is finished, you will see that the mirror is filled with
all the dependencies that were retrieved and used during the build.

[[env_vars]]
=== Environment variables 

==== Information environment variables
The following information environment variables are designed to convey
information about the image and should not be modified by the user:

.Information Environment Variables
[cols="3",options="header"]
|===
|Variable Name |Description |Example Value
|*_AB_JOLOKIA_AUTH_OPENSHIFT_*
|-
|*_true_*

|*_AB_JOLOKIA_HTTPS_*
|-
|*_true_*

|*_AB_JOLOKIA_PASSWORD_RANDOM_*
|-
|*_true_*

|*_JBOSS_IMAGE_NAME_*
|Image name, same as "name" label.
|*_{openshift_image_repository}_*

|*_JBOSS_IMAGE_VERSION_*
|Image version, same as "version" label.
|*_{project_versionDoc}_*

|*_JBOSS_MODULES_SYSTEM_PKGS_*
|-
|*_org.jboss.logmanager,jdk.nashorn.api_*

|===

==== Configuration environment variables
Configuration environment variables are designed to conveniently adjust the
image without requiring a rebuild, and should be set by the user as desired.

[[conf_env_vars]]
.Configuration Environment Variables
[cols="3",options="header"]
|===
|Variable Name |Description |Example Value
|*_AB_JOLOKIA_AUTH_OPENSHIFT_*
|Switch on client authentication for OpenShift TLS communication. The value of
this parameter can be a relative distinguished name which must be contained in
a presented client's certificate. Enabling this parameter will automatically
switch Jolokia into https communication mode. The default CA cert is set to
`/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`.
|*_true_*

|*_AB_JOLOKIA_CONFIG_*
|If set uses this file (including path) as Jolokia JVM agent properties (as
described in Jolokia's
link:https://jolokia.org/reference/html/agents.html#agents-jvm[reference
manual]). If not set, the `/opt/jolokia/etc/jolokia.properties` file will be
created using the settings as defined in this document, otherwise the rest of
the settings in this document are ignored.
|*_/opt/jolokia/custom.properties_*

|*_AB_JOLOKIA_DISCOVERY_ENABLED_*
|Enable Jolokia discovery. Defaults to *_false_*.
|*_true_*

|*_AB_JOLOKIA_HOST_*
|Host address to bind to. Defaults to *_0.0.0.0_*.
|*_127.0.0.1_*

|*_AB_JOLOKIA_HTTPS_*
|Switch on secure communication with https. By default self-signed server
certificates are generated if no serverCert configuration is given in
*_AB_JOLOKIA_OPTS_*. _NOTE: If the values is set to an empty string, https is
turned `off`. If the value is set to a non empty string, https is turned `on`._
|*_true_*

|*_AB_JOLOKIA_ID_*
|Agent ID to use ($HOSTNAME by default, which is the container id).
|*_openjdk-app-1-xqlsj_*

|*_AB_JOLOKIA_OFF_*
|If set disables activation of Jolokia (i.e. echos an empty value). By default,
Jolokia is enabled. _NOTE: If the values is set to an empty string, https is
turned `off`. If the value is set to a non empty string, https is turned `on`._
|*_true_*

|*_AB_JOLOKIA_OPTS_*
|Additional options to be appended to the agent configuration. They should be
given in the format `"key=value, key=value, …<200b> "`
|*_backlog=20_*

|*_AB_JOLOKIA_PASSWORD_*
|Password for basic authentication. By default authentication is switched off.
|*_mypassword_*

|*_AB_JOLOKIA_PASSWORD_RANDOM_*
|If set, a random value is generated for *_AB_JOLOKIA_PASSWORD_*, and it is
saved in the *_/opt/jolokia/etc/jolokia.pw_* file.
|*_true_*

|*_AB_JOLOKIA_PORT_*
|Port to use (Default: *_8778_*).
|*_5432_*

|*_AB_JOLOKIA_USER_*
|User for basic authentication. Defaults to *_jolokia_*.
|*_myusername_*

|*_CONTAINER_CORE_LIMIT_*
|A calculated core limit as described in
link:https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt[CFS
Bandwidth Control.]
|*_2_*

|*_GC_ADAPTIVE_SIZE_POLICY_WEIGHT_*
|The weighting given to the current Garbage Collection (GC) time versus previous
GC times.
|*_90_*

|*_GC_MAX_HEAP_FREE_RATIO_*
|Maximum percentage of heap free after GC to avoid shrinking.
|*_40_*

|*_GC_MAX_METASPACE_SIZE_*
|The maximum metaspace size.
|*_100_*

|*_GC_TIME_RATIO_MIN_HEAP_FREE_RATIO_*
|Minimum percentage of heap free after GC to avoid expansion.
|*_20_*

|*_GC_TIME_RATIO_*
|Specifies the ratio of the time spent outside the garbage collection (for
example, the time spent for application execution) to the time spent in the
garbage collection.
|*_4_*

|*_JAVA_DIAGNOSTICS_*
|Set this to get some diagnostics information to standard out when things are
happening.
|*_true_*

|*_JAVA_INITIAL_MEM_RATIO_*
|This is used to calculate a default initial heap memory based the maximal
heap memory. The default is 100 which means 100% of the maximal heap is used
for the initial heap size. You can skip this mechanism by setting this value
to 0 in which case no `-Xms` option is added.
|*_100_*

|*_JAVA_MAX_MEM_RATIO_*
|It is used to calculate a default maximal heap memory based on a containers
restriction. If used in a Docker container without any memory constraints for
the container then this option has no effect. If there is a memory constraint
then `-Xmx` is set to a ratio of the container available memory as set here.
The default is 50 which means 50% of the available memory is used as an upper
boundary. You can skip this mechanism by setting this value to 0 in which case
no `-Xmx` option is added.
|*_40_*

|*_JAVA_OPTS_APPEND_*
|Server startup options.
|*_-Dkeycloak.migration.action=export -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=/tmp_*

|*_MQ_SIMPLE_DEFAULT_PHYSICAL_DESTINATION_*
|For backwards compatability, set to true to use `MyQueue` and `MyTopic` as
physical destination name defaults instead of `queue/MyQueue` and `topic/MyTopic`.
|*_false_*

|*_OPENSHIFT_KUBE_PING_LABELS_*
|Clustering labels selector.
|*_app=sso-app_*

|*_OPENSHIFT_KUBE_PING_NAMESPACE_*
|Clustering project namespace.
|*_myproject_*

|*_SCRIPT_DEBUG_*
|If set to `true`, ensurses that the bash scripts are executed with the `-x`
option, printing the commands and their arguments as they are executed.
|*_true_*

|*_SSO_ADMIN_PASSWORD_*
|Password of the administrator account for the `master` realm of the {project_name}
server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift Instructional message when the template is
instantiated.
|*_adm-password_*

|*_SSO_ADMIN_USERNAME_*
|Username of the administrator account for the `master` realm of the {project_name}
server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift Instructional message when the template is
instantiated.
|*_admin_*

|*_SSO_HOSTNAME_*
|Custom hostname for the {project_name} server. *Not set by default*. If not
set, the `request` hostname SPI provider, which uses the request headers to
determine the hostname of the {project_name} server is used. If set, the
`fixed` hostname SPI provider, with the hostname of the {project_name} server
set to the provided variable value, is used. See dedicated
xref:../content/advanced_concepts/advanced_concepts.adoc#advanced-concepts-sso-hostname-spi-setup[Customizing Hostname for the {project_name} Server]
section for additional steps to be performed, when *_SSO_HOSTNAME_* variable
is set.
|*_rh-sso-server.openshift.example.com_*

|*_SSO_REALM_*
|Name of the realm to be created in the {project_name} server if this environment variable
is provided.
|*_demo_*

|*_SSO_SERVICE_PASSWORD_*
|The password for the {project_name} service user.
|*_mgmt-password_*

|*_SSO_SERVICE_USERNAME_*
|The username used to access the {project_name} service. This is used by clients to create
the application client(s) within the specified {project_name} realm. This user is created
if this environment variable is provided.
|*_sso-mgmtuser_*

|*_SSO_TRUSTSTORE_*
|The name of the truststore file within the secret.
|*_truststore.jks_*

|*_SSO_TRUSTSTORE_DIR_*
|Truststore directory.
|*_/etc/sso-secret-volume_*

|*_SSO_TRUSTSTORE_PASSWORD_*
|The password for the truststore and certificate.
|*_mykeystorepass_*

|*_SSO_TRUSTSTORE_SECRET_*
|The name of the secret containing the truststore file. Used for
_sso-truststore-volume_ volume.
|*_truststore-secret_*

|===

Available link:{ocpdocs_templates_link}[application templates]
for {project_openshift_product_name} can combine the xref:conf_env_vars[aforementioned
configuration variables] with common OpenShift variables (for example
*_APPLICATION_NAME_* or *_SOURCE_REPOSITORY_URL_*), product specific variables
(e.g. *_HORNETQ_CLUSTER_PASSWORD_*), or configuration variables typical to
database images (e.g. *_POSTGRESQL_MAX_CONNECTIONS_*) yet. All of these different
types of configuration variables can be adjusted as desired to achieve the
deployed {project_name}-enabled application will align with the intended use case as much
as possible. The list of configuration variables, available for each category
of application templates for {project_name}-enabled applications, is described below.

==== Template variables for all {project_name} images

.Configuration Variables Available For All {project_name} Images
[cols="2*", options="header"]
|===
|Variable
|Description
|*_APPLICATION_NAME_*
|The name for the application.

|*_DB_MAX_POOL_SIZE_*
|Sets xa-pool/max-pool-size for the configured datasource.

|*_DB_TX_ISOLATION_*
|Sets transaction-isolation for the configured datasource.

|*_DB_USERNAME_*
|Database user name.

|*_HOSTNAME_HTTP_*
|Custom hostname for http service route. Leave blank for default hostname,
e.g.: _<application-name>.<project>.<default-domain-suffix>_.

|*_HOSTNAME_HTTPS_*
|Custom hostname for https service route. Leave blank for default hostname,
e.g.: _<application-name>.<project>.<default-domain-suffix>_.

|*_HTTPS_KEYSTORE_*
|The name of the keystore file within the secret. If defined along with
*_HTTPS_PASSWORD_* and *_HTTPS_NAME_*, enable HTTPS and set the SSL certificate
key file to a relative path under _$JBOSS_HOME/standalone/configuration_.

|*_HTTPS_KEYSTORE_TYPE_*
|The type of the keystore file (JKS or JCEKS).

|*_HTTPS_NAME_*
|The name associated with the server certificate (e.g. _jboss_). If defined
along with *_HTTPS_PASSWORD_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set the
SSL name.

|*_HTTPS_PASSWORD_*
|The password for the keystore and certificate (e.g. _mykeystorepass_). If
defined along with *_HTTPS_NAME_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set
the SSL key password.

|*_HTTPS_SECRET_*
|The name of the secret containing the keystore file.

|*_IMAGE_STREAM_NAMESPACE_*
|Namespace in which the ImageStreams for Red Hat Middleware images are
installed. These ImageStreams are normally installed in the _openshift_
namespace. You should only need to modify this if you've installed the
ImageStreams in a different namespace/project.

|*_JGROUPS_CLUSTER_PASSWORD_*
|JGroups cluster password.

|*_JGROUPS_ENCRYPT_KEYSTORE_*
|The name of the keystore file within the secret.

|*_JGROUPS_ENCRYPT_NAME_*
|The name associated with the server certificate (e.g. _secret-key_).

|*_JGROUPS_ENCRYPT_PASSWORD_*
|The password for the keystore and certificate (e.g. _password_).

|*_JGROUPS_ENCRYPT_SECRET_*
|The name of the secret containing the keystore file.

|*_SSO_ADMIN_USERNAME_*
|Username of the administrator account for the `master` realm of the {project_name}
server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift instructional message when the template is
instantiated.

|*_SSO_ADMIN_PASSWORD_*
|Password of the administrator account for the `master` realm of the {project_name}
server. *Required.* If no value is specified, it is auto generated and
displayed as an OpenShift instructional message when the template is
instantiated.

|*_SSO_REALM_*
|Name of the realm to be created in the {project_name} server if this environment variable
is provided.

|*_SSO_SERVICE_USERNAME_*
|The username used to access the {project_name} service. This is used by clients to create
the application client(s) within the specified {project_name} realm. This user is created
if this environment variable is provided.

|*_SSO_SERVICE_PASSWORD_*
|The password for the {project_name} service user.

|*_SSO_TRUSTSTORE_*
|The name of the truststore file within the secret.

|*_SSO_TRUSTSTORE_SECRET_*
|The name of the secret containing the truststore file. Used for
*_sso-truststore-volume_* volume.

|*_SSO_TRUSTSTORE_PASSWORD_*
|The password for the truststore and certificate.
|===

==== Template variables specific to *_{project_templates_version}-postgresql_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-postgresql-persistent_*

.Configuration Variables Specific To {project_name}-enabled PostgreSQL Applications With Ephemeral Or Persistent Storage
[cols="2*", options="header"]
|===
|Variable
|Description
|*_DB_USERNAME_*
|Database user name.

|*_DB_PASSWORD_*
|Database user password.

|*_DB_JNDI_*
|Database JNDI name used by application to resolve the datasource,
e.g. _java:/jboss/datasources/postgresql_

|*_POSTGRESQL_MAX_CONNECTIONS_*
|The maximum number of client connections allowed. This also sets the maximum
number of prepared transactions.

|*_POSTGRESQL_SHARED_BUFFERS_*
|Configures how much memory is dedicated to PostgreSQL for caching data.
|===

==== Template variables for general *eap64* and *eap71* S2I images

.Configuration Variables For EAP 6.4 and EAP 7 Applications Built Via S2I
[cols="2*", options="header"]
|===
|Variable
|Description
|*_APPLICATION_NAME_*
|The name for the application.

|*_ARTIFACT_DIR_*
|Artifacts directory.

|*_AUTO_DEPLOY_EXPLODED_*
|Controls whether exploded deployment content should be automatically deployed.

|*_CONTEXT_DIR_*
|Path within Git project to build; empty for root project directory.

|*_GENERIC_WEBHOOK_SECRET_*
|Generic build trigger secret.

|*_GITHUB_WEBHOOK_SECRET_*
|GitHub trigger secret.

|*_HORNETQ_CLUSTER_PASSWORD_*
|HornetQ cluster administrator password.

|*_HORNETQ_QUEUES_*
|Queue names.

|*_HORNETQ_TOPICS_*
|Topic names.

|*_HOSTNAME_HTTP_*
|Custom host name for http service route. Leave blank for default host name,
e.g.: _<application-name>.<project>.<default-domain-suffix>_.

|*_HOSTNAME_HTTPS_*
|Custom host name for https service route. Leave blank for default host name,
e.g.: _<application-name>.<project>.<default-domain-suffix>_.

|*_HTTPS_KEYSTORE_TYPE_*
|The type of the keystore file (JKS or JCEKS).

|*_HTTPS_KEYSTORE_*
|The name of the keystore file within the secret. If defined along with
*_HTTPS_PASSWORD_* and *_HTTPS_NAME_*, enable HTTPS and set the SSL certificate
key file to a relative path under _$JBOSS_HOME/standalone/configuration_.

|*_HTTPS_NAME_*
|The name associated with the server certificate (e.g. _jboss_). If defined
along with *_HTTPS_PASSWORD_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set the
SSL name.

|*_HTTPS_PASSWORD_*
|The password for the keystore and certificate (e.g. _mykeystorepass_). If
defined along with *_HTTPS_NAME_* and *_HTTPS_KEYSTORE_*, enable HTTPS and set
the SSL key password.

|*_HTTPS_SECRET_*
|The name of the secret containing the keystore file.

|*_IMAGE_STREAM_NAMESPACE_*
|Namespace in which the ImageStreams for Red Hat Middleware images are
installed. These ImageStreams are normally installed in the _openshift_
namespace. You should only need to modify this if you've installed the
ImageStreams in a different namespace/project.

|*_JGROUPS_CLUSTER_PASSWORD_*
|JGroups cluster password.

|*_JGROUPS_ENCRYPT_KEYSTORE_*
|The name of the keystore file within the secret.

|*_JGROUPS_ENCRYPT_NAME_*
|The name associated with the server certificate (e.g. _secret-key_).

|*_JGROUPS_ENCRYPT_PASSWORD_*
|The password for the keystore and certificate (e.g. _password_).

|*_JGROUPS_ENCRYPT_SECRET_*
|The name of the secret containing the keystore file.

|*_SOURCE_REPOSITORY_REF_*
|Git branch/tag reference.

|*_SOURCE_REPOSITORY_URL_*
|Git source URI for application.
|===

==== Template variables specific to *_eap64-sso-s2i_* and *_eap71-sso-s2i_* for automatic client registration

.Configuration Variables For EAP 6.4 and EAP 7 {project_name}-enabled Applications Built Via S2I
[cols="2*", options="header"]
|===
|Variable
|Description
|*_SSO_URL_*
|{project_name} server location.

|*_SSO_REALM_*
|Name of the realm to be created in the {project_name} server if this environment variable
is provided.

|*_SSO_USERNAME_*
|The username used to access the {project_name} service. This is used to create the
application client(s) within the specified {project_name} realm. This should match the
*_SSO_SERVICE_USERNAME_* specified through one of the *{project_templates_version}-* templates.

|*_SSO_PASSWORD_*
|The password for the {project_name} service user.

|*_SSO_PUBLIC_KEY_*
|{project_name} public key. Public key is recommended to be passed into the template to
avoid man-in-the-middle security attacks.

|*_SSO_SECRET_*
|The {project_name} client secret for confidential access.

|*_SSO_SERVICE_URL_*
|{project_name} service location.

|*_SSO_TRUSTSTORE_SECRET_*
|The name of the secret containing the truststore file. Used for
*_sso-truststore-volume_* volume.

|*_SSO_TRUSTSTORE_*
|The name of the truststore file within the secret.

|*_SSO_TRUSTSTORE_PASSWORD_*
|The password for the truststore and certificate.

|*_SSO_BEARER_ONLY_*
|{project_name} client access type.

|*_SSO_DISABLE_SSL_CERTIFICATE_VALIDATION_*
|If true SSL communication between EAP and the {project_name} Server is insecure
(i.e. certificate validation is disabled with curl)

|*_SSO_ENABLE_CORS_*
|Enable CORS for {project_name} applications.
|===

==== Template variables specific to *_eap64-sso-s2i_* and *_eap71-sso-s2i_* for automatic client registration with SAML clients

.Configuration Variables For EAP 6.4 and EAP 7 {project_name}-enabled Applications Built Via S2I Using SAML Protocol
[cols="2*", options="header"]
|===
|Variable
|Description
|*_SSO_SAML_CERTIFICATE_NAME_*
|The name associated with the server certificate.

|*_SSO_SAML_KEYSTORE_PASSWORD_*
|The password for the keystore and certificate.

|*_SSO_SAML_KEYSTORE_*
|The name of the keystore file within the secret.

|*_SSO_SAML_KEYSTORE_SECRET_*
|The name of the secret containing the keystore file.

|*_SSO_SAML_LOGOUT_PAGE_*
|{project_name} logout page for SAML applications.
|===

=== Exposed ports
[cols="2",options="header"]
|===
|Port Number | Description
|*_8443_* | HTTPS

|*_8778_* | Jolokia monitoring

|===

////
=== Labels

=== Datasources

=== Clustering

=== Security domains

=== HTTPS

=== Source-to-Image (S2I)

=== Known issues
* There is a known issue with the EAP6 Adapter _HttpServletRequest.logout()_ in which the adapter does not log out from the application, which can create a login loop. The workaround is to call _HttpSession.invalidate();_ after _request.logout()_ to clear the Keycloak token from the session. For more information, see https://issues.redhat.com/browse/KEYCLOAK-2665[KEYCLOAK-2665].
* The SSO logs throw a duplication error if the SSO pod is restarted while backed by a database pod. This error can be safely ignored.
* Setting _adminUrl_ to a "https://..." address in an OpenID Connect client will cause *javax.net.ssl.SSLHandshakeException* exceptions on the SSO server if the default secrets (*sso-app-secret* and *eap-app-secret*) are used. The application server must use either CA-signed certificates or configure the SSO trust store to trust the self-signed certificates.
* If the client route uses a different domain suffix to the SSO service, the client registration script will erroneously configure the client on the SSO side, causing bad redirection.
* The SSO-enabled JBoss EAP image does not properly set the *adminUrl* property during automatic client registration. As a workaround, log in to the SSO console after the application has started and manually modify the client registration *adminUrl* property to *http://_<application-name>_-_<project-name>_._<hostname>_/_<app-context>_*.
////