Install Keycloak

Learn how to install a fresh Keycloak instance or use an existing one with censhare.

Required infrastructure | Options

It is not required to have a separate server just for Keycloak. Keycloak can be installed on the same server as the censhare Server.
If you have a Keycloak instance already running, or for other reasons, Keycloak can be installed on a separate server than the censhare Server.

Installation options

If you do not have a Keycloak instance yet, Keycloak can be installed from the RPM packages together with censhare RPM packages together with censhare.
If you already use Keycloak in your organizational network, you can use your existing Keycloak instance. Ask our support for an installation package without Keycloak, if you do not need to install Keycloak bundled with the censhare platform.
- However, in that case, you must add and configure the censhare realm on your Keycloak server.

Database

Keycloak stores data in a database. You can use your existing censhare database for Keycloak; the schemas will co-exist in a complete isolation from each other. However:

Use Postgres with Keycloak

We highly recommend using Postgres database with Keycloak. Although Keycloak declares to be compatible with Oracle, unfortunately, we cannot offer support for using Oracle with Keycloak.

In case you use an Oracle database with the censhare Server, you have two options:

utilize it for the Keycloak data: in this case, you have to embrace the risk of using an incompatible database that we cannot support;
set up a separate Postgres database for Keycloak: in this case, remember to specify the following in the keycloak.conf file (see also below):

keycloak.conf

YML

# DB
db=postgres

Installation

If you already have a running Keycloak installation, you need to upgrade it to a newer Keycloak.
If you need to install Keycloak, go to the location where you installed censhare:

CODE

rpm -i keycloak-<<version-build-number-platform>>.rpm 
# or yum install --enablerepo="censhare*" keycloak-21

In case a PostgreSQL DB is used at the server, an initial setup for that DB is required, as in the example below. Please feel free to refer to the 3d-party provider official documentation on this: https://www.keycloak.org/server/db

SQL

CREATE USER keycloak PASSWORD 'keycloak';
CREATE DATABASE keycloak OWNER keycloak TEMPLATE template0 ENCODING 'UTF8';

Create an initial admin user for Keycloak as described in the official 3d-party documentation: https://www.keycloak.org/docs/latest/server_admin/index.html#creating-first-admin_server_administration_guide

First steps after installation

Edit the entries inside /opt/keycloak/conf/keycloak.conf to adapt to your server (DB user, pass and connection, hostname, etc.).
- The hostname should be the external hostname where the Keycloak service should be reachable from the outside. Please feel free to refer to the 3d-party provider official documentation on this: https://www.keycloak.org/server/hostname
Since this new version have a lot of changes, the configuration file is very different. To update with all default options, please change only these entries:

BASH

# Basic settings for running in production. Change accordingly before deploying the server.
...
db-url=jdbc:postgresql://<DB_server>/<DB_service>
db-username=<user>
db-password=<password>
...
hostname=<hostname>
...

Please do not change the following parameters:

keycloak.conf

YML

# Observability
...
health-enabled=true
metrics-enabled=true

# Log
...
log=file,console
log-file=/var/log/keycloak/server.log

# HTTP
...
http-relative-path=/auth

TLS/SSL: Keycloak already has an internal certificate file, so a new one will not be required.
After this, you can follow the other steps in the Configure Keycloak for external authentication tutorial.