Ansible Role keycloak

This role installs keycloak.

Mandatory Requirements

Make sure you have OpenJDK installed.
- Keycloak < 20: OpenJDK 11
- Keycloak >= 20: OpenJDK 17
Install one of the following database servers and create a database and a user for said database. For MariaDB, this can be done using the linuxfabrik.lfops.mariadb_server role.
- mariadb
- mssql
- mysql
- oracle
- postgres

If you use the „Setup Keycloak“ Playbook, this installation is automatically done for you (you still have to take care of providing the required versions).

Tags

Tag	What it does
`keycloak`	Installs keycloak

Mandatory Role Variables

Variable	Description
`keycloak__apps__apps__host_var` / `keycloak__apps__apps__group_var`	The version of Keycloak that should be installed.
`keycloak__admin_login`	The Keycloak Admin login credentials. Subkeys: * `username`: Mandatory, string. Username. * `password`: Mandatory, string. Password.
`keycloak__db_login`	The database login credentials for keycloak. Subkeys: * `username`: Mandatory, string. Username. * `password`: Mandatory, string. Password.
`keycloak__hostname`	The hostname where keycloak is reachable.
`keycloak__java_package_name`	The Java package to be installed.
`keycloak__version`	The version of Keycloak that should be installed.

Example:

# mandatory
keycloak__apps__apps__host_var:
  - name: 'java-17-openjdk'
    state: 'present'
keycloak__admin_login:
  password: 'password'
  username: 'keycloak-admin'
keycloak__db_login:
  password: 'password'
  username: 'keycloak'
keycloak__hostname: 'keycloak.local'
keycloak__version: '25.0.1'

Optional Role Variables

Variable	Description	Default Value
`keycloak__db_url`	The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.	`unset`
`keycloak__db_url_database`	The database name for keycloak. If the db-url option is set, this option is ignored.	`keycloak`
`keycloak__db_url_host`	The host where the database for keycloak is running. If the db-url option is set, this option is ignored.	`localhost`
`keycloak__db_vendor`	Specifies the database server keycloak is supposed to use. Possible options: * mariadb * mssql * mysql * oracle * postgres	`mariadb`
`keycloak__expose_healthcheck_endpoints`	If the server should expose healthcheck endpoints.	`true`
`keycloak__expose_metrics_endpoints`	If the server should expose metrics endpoints.	`true`
`keycloak__https_protocols`	The cipher suites Keycloak is supposed to be using.	`TLSv1.3,TLSv1.2`
`keycloak__https_cipher_suites`	The cipher suites to use. If none is given, a reasonable default is selected.	`unset`
`keycloak__log`	Enable one or more log handlers in a comma-separated list.	`file`
`keycloak__log_file`	Set the log file path and filename.	`/var/log/keycloak/keycloak.log`
`keycloak__mode`	The mode to start Keycloak in. The development mode is targeted for people trying out Keycloak the first time and get it up and running quickly. It also offers convenient defaults for developers, for example to develop a new Keycloak theme. Possible options: * `production` * `development`	`production`
`keycloak__proxy_mode`	The proxy address forwarding mode if the server is behind a reverse proxy. * edge: Enables communication through HTTP between the proxy and Keycloak. This mode is suitable for deployments with a highly secure internal network where the reverse proxy keeps a secure connection (HTTP over TLS) with clients while communicating with Keycloak using HTTP. * reencrypt: Requires communication through HTTPS between the proxy and Keycloak. This mode is suitable for deployments where internal communication between the reverse proxy and Keycloak should also be protected. Different keys and certificates are used on the reverse proxy as well as on Keycloak. * passthrough: Enables communication through HTTP or HTTPS between the proxy and Keycloak. This mode is suitable for deployments where the reverse proxy is not terminating TLS. The proxy instead is forwarding requests to the Keycloak server so that secure connections between the server and clients are based on the keys and certificates used by the Keycloak server.	`unset`

Example:

# optional
keycloak__db_url_host: 'localhost'
keycloak__db_url_database: 'keycloak'
keycloak__db_url: 'jdbc:mariadb://localhost/keycloak/'
keycloak__db_vendor: 'mariadb'
keycloak__expose_healthcheck_endpoints: 'true'
keycloak__expose_metrics_endpoints: 'true'
keycloak__https_protocols: 'TLSv1.3,TLSv1.2'
keycloak__https_cipher_suites: 'TLS_RSA_WITH_AES_128_GCM_SHA256'
keycloak__log: 'file'
keycloak__log_file: '/var/log/keycloak/keycloak.log'
keycloak__mode: 'production'
keycloak__proxy_mode: 'edge'

keycloak__proxy_mode

Configure the reverse proxy:

Some Keycloak features rely on the assumption that the remote address of the HTTP request connecting to Keycloak is the real IP address of the clients machine.

When you have a reverse proxy or loadbalancer in front of Keycloak, this might not be the case, so please make sure your reverse proxy is configured correctly by performing these actions:

Set the X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host HTTP headers.

To set these headers, consult the documentation for your reverse proxy.

Take extra precautions to ensure that the X-Forwarded-For header is set by your reverse proxy. If this header is incorrectly configured, rogue clients can set this header and trick Keycloak into thinking the client is connected from a different IP address than the actual address. This precaution can more be critical if you do any deny or allow listing of IP addresses.

Exposed path recommendations When using a reverse proxy, Keycloak only requires certain paths need to be exposed. The following table shows the recommended paths to expose.

Keycloak Path	Reverse Proxy Path	Exposed	Reason
/	-	No	When exposing all paths, admin paths are exposed unnecessarily.
/admin/	-	No	Exposed admin paths lead to an unnecessary attack vector.
/js/	-	Yes (see note below)	Access to keycloak.js needed for „internal“ clients, e.g. the account console.
/welcome/	-	No	No need exists to expose the welcome page after initial installation.
/realms/	/realms/	Yes	This path is needed to work correctly, for example, for OIDC endpoints.
/resources/	/resources/	Yes	This path is needed to serve assets correctly. It may be served from a CDN instead of the Keycloak path.
/robots.txt	/robots.txt	Yes	Search engine rules.
/metrics	-	No	Exposed metrics lead to an unnecessary attack vector.
/health	-	No	Exposed health checks lead to an unnecessary attack vector.

Note:

As it’s true that the js path is needed for internal clients like the account console, it’s good practice to use keycloak.js from a JavaScript package manager like npm or yarn for your external clients.

On the webconsole

If you try to configure the administrative user via the web console on a remote machine you will encounter an error. This is prohibited because of potential security risks. Therefore, creating the administrative user via the web admin console is only allowed when running on localhost. As a consequence, you have to set the following environment variables first before executing the start command:

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=linuxfabrik

License

The Unlicense

Author Information

Linuxfabrik GmbH, Zurich