Server XML Configuration
Overview
Bouncer is a Keycloak repackaged with additional cloud and Yambas oriented features. Keycloak itself is built on top of Wildfly and JBoss. Bouncer run in different operation mode depending on your system requirements, each mode having its own configuration file. The different operation mode are described in the Keycloak operation mode documentation.
By default Bouncer run in standalone-ha mode and is configured using the standalone-ha.xml configuration located in Docker under /opt/jboss/keycloak/standalone/configuration/standalone-ha.xml, and in RPM and Debian under /opt/apiomat/bouncer/<bouncerVersion/standalone/configuration/standalone-ha.xml.
In this documentation we will describe how to configure your server xml file for different thematics.
Update Note
During an update of the component, you should always compare and adapt your current xml-configuration with the delivered configuration, as this file also contains information about integrated plugins, that may change over time
Using Placeholder
In the different examples of this documentation and in the operation xml configuration you will notice that placeholder values are used instead of static values. There are two types of placeholders: for server configuration which can be given as flag/argument to the Jboss server or for environment values. These placeholders give the possibility to overwrite the configuration values on server start without having to actually modify the xml files.
To set a my.conf.placeholder flag, configure the value with:
${my.conf.placeholder:myDefault}You can then use the flag as argument for the server start in RPM or Debian, or as argument for the Docker container with the following notation:
-Dmy.conf.placeholder=myValueNote that if you don' provide the flag, the value myDefault will be use as defined above.
To set a MY_CONF_PLACEHOLDER environment placeholder:
${env.MY_CONF_PLACEHOLDER:myDefault}Now the environment value will be use when starting the server, and if not defined, the myDefault value set above will be used.
HTTPS
By default, https is enabled in Bouncer. At first boot, it will create self-signed ssl certificate and use it.
If you want to use your own keystore (which has your ssl certificate in it) and truststore (which has trusted ssl of other services), configure your targeted operation mode xml configuration file.
To overwrite the default configuration and provide your own keystore configuration refer to enable SSL/HTTPS section of Keycloak documentation.
Follow the documentation to configure a new security-realms element with a path to your keystore and update the configuration of the https-listener to use your new security-realms element. The Bouncer container provides an empty default keystore.jks file which you can overwrite by mapping to /opt/bouncer/configuration/keystore.jks.
For outgoing HTTPS requests, add a truststore spi and configure it using Keycloak truststore documentation to point to your *truststore.jks* containing the trusted public certificates.
The Bouncer container provides an empty default truststore.jks file which you can overwrite by mapping to /opt/bouncer/configuration/truststore.jks.
Datasource
Bouncer can be configured with a relational database setup. Without a datasource configuration, H2 in-memory database will be use.
Refer to Keycloak database documentation for more insights about datasource configuration.
Package the JDBC Driver
The first step will be to package the wanted database Driver as a module. If you are not running in a Docker environment follow the steps described in Keycloak package the JDBC Driver.
In Docker the JDBC Driver and module.xml files are pre-configured for all the supported vendors, except for Oracle JDBC Driver which is not bundled in the image and should be added as a volume under /opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main.
The default configuration value for each vendor are the following:
|
Vendor |
Driver module name |
Datasource class name |
|
PostgreSQL |
org.postgresql.jdbc |
org.postgresql.xa.PGXADataSource |
|
Oracle |
com.oracle.jdbc |
oracle.jdbc.xa.client.OracleXADataSource |
|
MySQL |
com.mysql.jdbc |
com.mysql.cj.jdbc.MysqlXADataSource |
|
MariaDB |
org.mariadb.jdbc |
org.mariadb.jdbc.MySQLDataSource |
|
SQLServer |
com.microsoft.sqlserver.jdbc |
com.microsoft.sqlserver.jdbc.SQLServerXADataSource |
Declare your driver
When running with RPM, Debian or mapping your own operation mode configuration in Docker, you will have to add the datasource information to your configuration. First you'll need to declare your JDBC Driver and then modify Keycloak Datasource.
Global server configuration
In this section we will describe common server xml configuration.
Note that this is not an exhaustive list.
The configurations described in this section are also documented under Keycloak bind addresses and Keycloak socket port bindings.
Public address
The public address can be configured in your operation mode xml configuration file by changing the default value of the public interface's inet-address:
<interfaces> ... <interface name="public"> <inet-address value="${jboss.bind.address:127.0.0.1}"/> </interface> ...</interfaces>Public port
The public port can be configured in your operation mode xml configuration file by changing the default port value of the http socket-binding under the public socket-binding-group:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <socket-binding name="http" port="${jboss.http.port:8080}"/> ...</socket-binding-group>SSL port
The public SSL port can be configured in your operation mode xml configuration file by changing the default port value of the https socket-binding under the public socket-binding-group:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <socket-binding name="https" port="${jboss.https.port:8443}"/> ...</socket-binding-group>Management address
The management address can be configured in your operation mode xml configuration file by changing the default value of the management interface's inet-address:
<interfaces> ... <interface name="management"> <inet-address value="${jboss.bind.address.management:127.0.0.1}"/> </interface> ...</interfaces>Management port
The management port can be configured in your operation mode xml configuration file by changing the default port value of the management-http socket-binding under the public socket-binding-group:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/> ...</socket-binding-group>Management SSL port
The management SSL port can be configured in your operation mode xml configuration file by changing the default port value of the management-https socket-binding under the public socket-binding-group:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/> ...</socket-binding-group>AJP port
You can configure the port for communication using the AJP protocol in your operation mode xml configuration file by changing the default port value of the ajp socket-binding under the public socket-binding-group:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/> ...</socket-binding-group>Transaction sockets
Set in your operation mode xml configuration file the following socket-binding (e.g. with default values):
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <socket-binding name="txn-recovery-environment" port="4712"/> <socket-binding name="txn-status-manager" port="4713"/> ...</socket-binding-group>SMTP
The SMTP configuration for Bouncer can be configured by modifying the operation mode xml configuration file:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <outbound-socket-binding name="mail-smtp"> <remote-destination host="${jboss.mail.server.host:localhost}" port="${jboss.mail.server.port:25}"/> </outbound-socket-binding> ...</socket-binding-group>Default theme
The default theme can be set in xml by modifying the theme configuration:
<theme> <staticMaxAge>2592000</staticMaxAge> <cacheThemes>true</cacheThemes> <cacheTemplates>true</cacheTemplates> <welcomeTheme>${env.KEYCLOAK_WELCOME_THEME:easy-theme}</welcomeTheme> <default>${env.KEYCLOAK_DEFAULT_THEME:easy-theme}</default> <dir>${jboss.home.dir}/themes</dir></theme>Healthcheck
In addition to the environment properties described in [Bouncer] Installation, you can configure the Healthcheck plugin in your targeted operation mode xml configuration file under the healthcheck spi tag:
<spi name="healthcheck"> <provider name="infinispan" enabled="true"> <properties> <property name="cacheManagerJndiName" value="${env.CACHE_MANAGER_JNDI:java:jboss/infinispan/container/keycloak}"/> </properties> </provider> <provider name="filesystem" enabled="true"> <properties> <property name="path" value="${env.FS_CHECK_PATH:java:jboss/infinispan/container/keycloak}"/> <property name="thresholdInBytes" value="${env.FS_CHECK_THRESHOLD:1073741824}"/> </properties> </provider> <provider name="database" enabled="true"> <properties> <property name="jndiName" value="${env.DB_JNDI:java:jboss/datasources/KeycloakDS}"/> <property name="query" value="${env.DB_HEALTH_QUERY:SELECT 1}"/> </properties> </provider></spi>Discovery client registration
In addition to using environment as described in [Bouncer] Installation, you can configure the Registry plugin in your targeted operation mode xml configuration file under the registry spi tag:
<spi name="registry"> <provider name="consul" enabled="true"> <properties> <property name="registrationEnabled" value="${env.CONSUL_ENABLED:true}"/> <property name="consulUrl" value="${env.CONSUL_URL:http://localhost:8500/}"/> <property name="consulConnectTimeoutMillis" value="${env.CONSUL_CONNECT_TIMEOUT_MS:10000}"/> <property name="consulReadTimeoutMillis" value="${env.CONSUL_READ_TIMEOUT_MS:10000}"/> <property name="consulWriteTimeoutMillis" value="${env.CONSUL_WRITE_TIMEOUT_MS:10000}"/> <property name="consulMaxRetry" value="${env.CONSUL_MAX_RETRY:-1}"/> <property name="consulRetryDelaySeconds" value="${env.CONSUL_RETRY_DELAY_S:30}"/> <property name="serviceId" value="${env.REGISTRY_SERVICE_ID:bouncer}"/> <property name="serviceName" value="${env.REGISTRY_SERVICE_NAME:bouncer}"/> <property name="host" value="${env.REGISTRY_SERVICE_HOST:localhost}"/> <property name="port" value="${env.REGISTRY_SERVICE_PORT:8080}"/> <property name="healthCheckUrl" value="${env.REGISTRY_HEALTHCHECK_URL:http://localhost:8080/auth/realms/master/health/check}"/> <property name="checkIntervalSeconds" value="${env.REGISTRY_CHECK_INTERVAL_S:5}"/> <property name="deregisterAfterSeconds" value="${env.REGISTRY_DEREGISTER_S:120}"/> <property name="tags" value="["contextPath=/auth","version=3.0.0"]"/> </properties> </provider></spi>By default, the consul provider is enabled, but the registration to consul is disabled. Change the value of registrationEnabled to true if you want to enable automatic registration.
After any modification to your server configuration don't forget to reload or restart the server.
Enable metrics
Metrics can also be enabled in the standalone.xml, standalone-ha.xml or domain.xml file (depending on your operation mode). Simply set the statistics-enabled value to true depending on the subsystem you want to enable metrics for:
a) Datasources subsystem, for each defined datasource
<subsystem xmlns="urn:jboss:domain:datasources:6.0"> <datasources> ... <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true"> ... </datasource> ... </datasources></subsystem>b) EJB3 subsystem
<subsystem xmlns="urn:jboss:domain:ejb3:8.0"> ... <statistics enabled="true"/> ...</subsystem>c) Undertow subsystem
<subsystem xmlns="urn:jboss:domain:undertow:11.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other" statistics-enabled="true"> ...</subsystem>d) Transactions subsystem
<subsystem xmlns="urn:jboss:domain:transactions:5.0"> <coordinator-environment statistics-enabled="true"/></subsystem>Vault
In this section we'll explain how to set up Kubernetes / OpenShift files plaintext vault in a containerized environment. Refer to Keycloak use vault secret documentation for insights on how to use secrets.
When mapping standalone.xml, standalone-ha.xml or domain.xml files in your container add the vault SPI the following way :
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1"> ... <spi name="vault"> <default-provider>files-plaintext</default-provider> <provider name="files-plaintext" enabled="true"> <properties> <property name="dir" value="${jboss.home.dir}/secrets"/> </properties> </provider> </spi> ...</subsystem>