Install Keycloak

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

# DB
db=postgres

YML

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:

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

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:

# 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

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

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

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

YML

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