Configure Keycloak

censhare requires external authentication using Keycloak as identity broker. Keycloak runs as a service on the host. Learn how to configure Keycloak to use it with censhare.

Prerequisites

Write permissions to the installation directory
Installation of censhare Server, client, and tools
Installation of Keycloak

For production use, Keycloak recommends to use an external database, for example PostgreSQL. Consult the official Keycloak documentation for the newest information.

Introduction

Keycloak is used as authentication server for the censhare Server.

You can use Keycloak as an external identity provider. Keycloak then serves as an identity broker between the identity provider and censhare Server.
You can also use Keycloak with the censhare standard authentication. Keycloak then serves as a gatekeeper to the censhare Server. The user authentication is handled via the authentication server. Keycloak is used to log in to censhare Web, the censhare Client, and the censhare Admin Client. On the Keycloak server, the censhare realm contains the clients and respective configurations that handle the user authentication to censhare Web and the censhare Clients.

The configuration of the authentication method is not part of this documentation.

If you already use a Keycloak server in your organizational network, you can add the censhare realm to this service, and do not have to set up a new Keycloak instance. Otherwise, you must install and set up Keycloak first, before you proceed with this configuration.

Keycloak realms

In Keycloak, you work in a realm. A realm is a space where you manage objects such as applications or a group of users.

You must set up a realm for censhare.

Keycloak clients

In Keycloak, clients are entities that can request Keycloak to authenticate users. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution.

The censhare realm contains two clients to handle the login:

login from a web browser (censhare Web)
login from a censhare Client or censhare Admin Client

Clients store the authentication details for a specific application in Keycloak. A client is always created in a realm. The censhare Server and the Cloud Gateway use this client to authenticate themselves in Keycloak.

If you have an Xeditor integration

If you have an Xeditor integration in your censhare system, you will see an additional client named ets. Please do not remove or modify this client!

It is necessary to provision you with your Xeditor instance and is fully managed by the censhare IT.

Note on the Keycloak UI

Keycloak UI changes quite often, e.g., with every new patch. Keeping this fact in mind, please consider the following instructions as general guidelines. The Keycloak UI is very intuitive. Although single buttons may be moved around or renamed, the core concepts persist and you can quickly find what you need.

Current instructions are based on Keycloak 21, which is an integral part of the censhare 2023.1 product delivery.

The latest supported version is Keycloak 24.

Create Keycloak system admin account

If you already use a Keycloak server and want to configure this server to authenticate censhare users, you can skip this step.

Before you can use Keycloak, you need to create a system admin account which you use to log in to the Keycloak Administration console. Please follow the instructions from the official documentation: https://www.keycloak.org/docs/latest/server_admin/index.html#creating-first-admin_server_administration_guide

Keycloak 21 instructions

For Keycloak 21, before start the server, add these lines inside /etc/sysconfig/keycloak-21 to create the admin user:

BASH

KEYCLOAK_ADMIN=<username>
KEYCLOAK_ADMIN_PASSWORD=<password>

After the start, if the admin login goes well, you can remove these lines from this file.

Configure the censhare realm and realm keys

When you start KeyCloak, there is only the master realm. This master realm is only used for managing other realms. Therefore, you have to create a separate realm for censhare. The censhare realm stores everything that is related to censhare.

Before you start

Ensure that the Keycloak server is running, and that you can access it, and log in with the admin user that you created in the previous step.

Below you will find sample instructions.

Keycloak 21 instructions

Open the Keycloak admin console at http://localhost:8080/auth/ and log in with the admin user credentials that you set in the previous step.
In the left sidebar, click the Master realm and select Create realm.
In the dialog, enter censhare in the Name field.
Click Create.

Create internal admin user

For administration purposes, the Keycloak admin client service of the censhare Server must access Keycloak. The censhare Server uses this information get to know to which groups and roles a user belongs to. He also requests details about the user such as the full name. Besides that the censhare Server receives a certificate which allows him to check the integrity of JWT tokens.

Therefore, you must create a specific admin user that the censhare Server uses to retrieve data from Keycloak.

Important things to remember are:

This user must be enabled.
It needs to be assigned all admin roles that are tagged as *realm*. This is not consistent across KC versions, and may be called realm-management or master-realm.
It needs a permanent password.

Below you will find sample instructions. Make sure you are in the censhare realm that you just created.

Keycloak 21 instructions

Create the user

In the left sidebar of the Keycloak admin console, under Manage, open the Users menu.
On the right side of the screen, click Add user.
Enter the following details:
Field Value
Username
keycloak-admin
Email ¹ your email address
First Name ¹ Enter any name.
Last Name ¹ Enter any name.
User enabled ON
Email verified OFF
Remark

(1) These user details are not mandatory in Keycloak, but are required in censhare to authenticate a user. Always enter email, first name and last name!
Save your changes.

Assign role mappings

The keycloak-admin user must have all client and realm roles assigned.

In the new user detail view, go to the Role Mapping tab.
Click Assign Role.
Click on the downward-facing arrow right next to the filter icon to access the client level roles.
Type in realm in the search field.
Select all roles with a suitable tag and click Assign.

Set a password

The keycloak-admin user password is required for the Keycloak service configuration in the censhare Admin Client.

In the left navigation pane, under Manage -> Users open the admin user.
Go to the Credentials tab.
Click Set password.
Enter your password.
Switch the Temporary toggle to OFF.
Click Save.

Configure the censhare web application client

Important things to remember are:

Access must be set to confidential and not public. It means that we should enable client authentication. Depending on the KC version, the feature that enables confidential access may be called Confidential access in versions before 20 or Client authentication in Keycloak versions higher than 20.

Import new client configuration

Use these sample instructions to import a new censhare client from a supplemented configuration file.

Keycloak 21 instructions

In the left sidebar of the Keycloak admin console, open the Clients menu.
To add a new Keycloak client, either click Create client to configure it manually or click Import client and upload the censhare5.json configuration file.
1. Remember to replace the secret in the attached sample file if you want to reuse it.
If you decided to configure it manually, then, in the Client ID field of the dialog, enter censhare5.
1. Click Next and make sure that the following values are set correctly:
  Field Value
  Name
  censhare5
  Description
  censhare5
  Client authentication ON
  Authorization ON
  Service account roles ON
2. Save your changes.
3. On the Settings tab, under Access settings, enter the following values:
  Field Value
  Root URL
  http://localhost
  Valid Redirect URI
  http://localhost:8080/auth/login/censhare
  http://localhost:8082/*
  http://<<domain-name>>:8082/*
  https://<<domain-name>>.<<top-level-domain>>>/*
  The Valid Redirect URI needs an asterisk.
Go to the Credentials tab.
Copy the Secret. The secret is used by other services and applications to authenticate themselves. The secret must be added to the Keycloak service configuration in the censhare Admin Client, and to the configuration of the Cloud Gateway (partner login required to access instructions).
For Keycloak 21, in the logout settings, please check:
1. Backchannel logout session required is ON.
2. Front channel logout is OFF.

Manual configuration

If required, configure the following settings individually. You only need to do this if you do not want to use the default configuration.

Field	Value	Remarks
Client ID	Default is censhare5	Any other ID is allowed. The ID is required to configure the keycloak_service
Name	Default is censhare 5 OpenID client	Any other name is allowed.
Description		Optional. Enter a short description of the client.
Enabled	ON
Consent Required	OFF
Login Theme		Select a custom branding and layout for the login page. If you do not select any theme, the default theme is used.
Client type	OpenID Connect	Can only be selected once upon creation of the client.
Standard Flow Enabled	ON
Implicit Flow Enabled	OFF
Direct Access Grants Enabled	ON
Service Account Roles Enabled	ON
Authorization Enabled	ON
Root URL	`http://localhost`	Enter the URL from which users access the web-based censhare client.
Valid Redirect URIs	`http://localhost:8080/auth/login/censhare http://localhost:8082/* http://<<domain-name>>:8082/* https://<<domain-name>>.<<top-level-domain>>>/*`	Enter the URL from which users access the web-based censhare client, followed by the asterisk (*).
Base URL		not required
Admin URL		not required
Web Origins	*	Do not remove the asterisk (*).

Click Save.
Go to the Credentials tab.
Copy the Secret. You need this secret to set up the Keycloak service in the censhare Admin Client, and for the configuration of the Cloud Gateway.

Configure the censhare desktop application client

Import new client configuration

The desktop application client authenticates users at the censhare Clients and the censhare Admin Clients. Use these sample instructions to import a new censhare client from a supplemented configuration file.

Keycloak 21 instructions

In the left sidebar of the Keycloak admin console, open the Clients menu.
To add a new Keycloak client, either click Create client to configure it manually or click Import client and upload the client-desktop.json configuration file.
1. Replace the secret to the correct one in the attached sample file if you want to reuse it.
2. Set your local host to http://localhost:* as this is random.
If you decided to configure it manually, then, in the Client ID field of the dialog, enter desktop-app.
1. Click Next and make sure that the following values are set correctly:
  Field Value
  Name
  desktop-app
  Description
  desktop-app
  Client authentication ON
  Authorization OFF
2. Save your changes.
3. On the Settings tab, under Access settings, enter the following values:
  Field Value
  Root URL
  http://localhost
  Valid Redirect URIs
  http://localhost:*
Go to the Credentials tab.
Copy the Secret. The secret is used by other services and applications to authenticate themselves. The secret must be added to the Keycloak service configuration in the censhare Admin Client, and to the configuration of the Cloud Gateway.

Manual configuration

If you want to configure the desktop client manually, make sure that the following settings are correct:

Field	Value	Remarks
Client ID	Default is desktop-app	Any other ID is allowed. The ID is required to configure the Keycloak service.
Name	Default is desktop-app	Any other name is allowed.
Description		Optional. Enter a short description of the client.
Enabled	ON
Consent Required	OFF
Login Theme		Select a custom branding and layout for the login page. If you do not select any theme, the default theme is used.
Client Type	OpenID Connect	Can only be selected once upon creation of the client.
Standard Flow Enabled	ON
Implicit Flow Enabled	OFF
Direct Access Grants Enabled	ON
Service Accounts Roles Enabled	OFF
Authorization Enabled	OFF
Root URL	`http://localhost:`	Enter the Keycloak server URL (absolute URL). The base URL must be accessible from the client computers inside your corporate network.
Valid Redirect URIs	`http://localhost:*`	Enter the Keycloak server URL (absolute URL), followed by the asterisk (). Do not remove the localhost* entry!
Base URL		not required
Admin URL	`http://localhost:`	Enter the Keycloak server URL (absolute URL).
Web Origins	`*`	Enter the Keycloak server URL (absolute URL).

Click Save.
Go to the Credentials tab.
Copy the Secret. You need this secret to set up the Keycloak service, and for the configuration of the Cloud Gateway.

If you imported the JSON configuration file to set up the client, the Secret field shows a [CREATE_SECRET] placeholder. Click Regenerate Secret to generate a valid secret and copy it.

Configure the censhare CI HUB application client

Follow the steps described in CI HUB - Setup in censhare

You can omit this task if you do not use the CI HUB integration.

Configure client connection to the censhare Server

The hosts.xml file is an XML file on the local client computer that contains the information about all available censhare application servers (hosts) and their connection parameters.

Prerequisites:

The clients must be installed and configured. For more information see, censhare - RPM-based installation and Install Java-based censhare clients
The connection to the censhare Sever must be set up. For more information, see The hosts.xml file and Client Preferences.

For the connection to Keycloak, the authentication method for the censhare Client and censhare Admin Client must be set to external in the respective hosts.xml files.

Open the hosts.xml file. The default path on macOS is /Users/USER/Library/Preferences/censhare/hosts.xml.
In the entry of the desired server, set the attribute authentication-method="external".
Save the configuration.

Configure censhare Server to access Keycloak

The Keycloak service connects the censhare Server to the Keycloak server and queries the user data from the Keycloak server.

You need the admin user credentials from the censhare realm and both secrets from the clients that you created in Keycloak.

The configuration is done in the censhare Admin Client.

In the censhare Admin Client, open the Configuration/Services/Keycloak admin client service directory, and open the Configuration file.
Select the Service enabled field.
In the Invocations field, select the maximum number of parallel processes. The default is 2.
Leave the Version field unaltered.

In the Authentication server setup area, configure the service for censhare Web:

Admin user access password
Base URL	Enter the hostname of the Keycloak server (absolute URL). Keycloak must be accessible internally (from the censhare Server) through this URL. Important: Add the certificate for this host to the censhare Server truststore! For more information on the certificate for the Keycloak service, see Certificates in censhare environments - Keycloak service. If the censhare Server is installed inside of Kubernetes, you can use the service name instead.
Realm name	Enter the realm name that you configured in the Keycloak administration console. Default is censhare.
Admin user access name	Enter the user credentials of the system user that retrieves the data from Keycloak.
Keycloak OAuth2 client ID	Enter the client ID of the censhare web application client in Keycloak. Default is censhare5.
OAuth client secret	Enter the secret of the censhare web application client in Keycloak. The secret is generated automatically in Keycloak. You can find it under the censhare realm in the respective Clients settings on the Credentials tab.

In the Authentication credentials for native client setup, configure the service for the desktop applications censhare Client and the censhare Admin Client. The native client service uses the same realm and admin user as the web client setup. Only the client ID and secret are required:

Base URL (exposed to client)	Enter the Keycloak URL that is accessible from any native Client in your corporate network.
Keycloak OAuth2 client ID	Enter the client ID of the censhare desktop application client in Keycloak. Default is desktop-app.
Keycloak OAuth native application secret	Enter the secret of the desktop application client in Keycloak. The secret is generated automatically and can be found in the client settings in the Credentials tab.

Click OK to save the configuration.
Restart the censhare Server. If necessary, synchronize the remote servers.

Add or migrate users to Keycloak

To add new users, see Add new users to Keycloak.

For update installations or when updating from authentication solutions other than Keycloak, see Migrate users to Keycloak.

Test desktop client login via Keycloak

Start either the censhare Client or the censhare Admin Client and try to log in with the user that you created above. When you select the corresponding censhare-Server in the dialog, the login and password fields are disabled. Instead, you are forwarded to the Keycloak login page in your default browser. Enter the credentials (login name and password) of the user that you created in Keycloak.

If the login was successful, switch back to the censhare Client or the censhare Admin Client applications. The login process starts automatically and you can access and work with the application.

Important Keycloak configuration in the Admin Client

There are a few Keycloak-related properties in the censhare Admin Client. Their default values (see table below) enable a correct logout from both censhare clients: censhare Client and censhare Admin Client.

Property Value Enabled Comment

com.censhare.desktop-client.keycloak.server-side-logout

true

no

Location of the setting: censhare Admin Client → Configuration → Server → Launcher:

Set to false to disable
Only disable if application@keycloak-logout is enabled

application@keycloak-logout

true

no

Location of the setting: censhare Admin Client → Configuration → Modules → Clients → Client → Client Preferences:

Set to false to disable
Only disable if com.censhare.desktop-client.keycloak.server-side-logout is enabled

application@token-refresh-interval-minutes

Any number smaller than the "SSO Session Idle" time configured in the Keycloak realm settings

yes

Location of the setting: censhare Admin Client → Configuration → Modules → Clients → Client → Client Preferences:

A value of 0 disables token refreshes completely.

The reason they are set up like this is the following.

The standard browser, which is used for the Keycloak login, stores a session cookie after the first login. On the second login the same browser is used as well and sends the still existing session cookie to Keycloak. Keycloak detects that the session cookie is still valid and that the previous session was not closed. If the session timeout has not yet elapsed, the old session is used again without prompting the user for username and password again.

As a result, the user cannot log in after performing a logout. This is particularly a problem for those users, which fulfil multiple roles in their daily work and use different censhare logins for that purpose. That‘s why we recommend to keep the following default properties. However, you do not have to use the so-called server-side and client-side logouts at the same time.

If client-side Keycloak logout is enabled, the client refreshes the current Keycloak token regularly every few minutes. The interval of those refresh requests can be configured via the client preferences with property application@token-refresh-interval-minutes. The value is given in minutes and must be smaller than the SSO Session Idle time configured in the Keycloak realm settings (under SSO Session Settings). A value of 0 disables token refreshes completely. Note that if the Keycloak server is restarted, all currently active tokens become invalid. If token refresh is enabled for the client, the user will be redirected to the browser to re-login on the next scheduled refresh.

Result

The Keycloak server is installed and configured in the censhare instance in your organizational network. To verify the authentication, log in either from a censhare Client or from censhare Web. From both instances, you are forwarded to the Keycloak login page. After successful login, you are redirected to the censhare Client or the censhare web application.

Next steps

Carry on with the censhare configuration.

Configure the censhare Standard login, or add and configure the authentication via LDAP or SAML to log in censhare users.

Field	Value
Username	keycloak-admin
Email ¹	your email address
First Name ¹	Enter any name.
Last Name ¹	Enter any name.
User enabled	ON
Email verified	OFF

Field	Value
Name	censhare5
Description	censhare5
Client authentication	ON
Authorization	ON
Service account roles	ON

Field	Value
Root URL	http://localhost
Valid Redirect URI	http://localhost:8080/auth/login/censhare http://localhost:8082/* http://<<domain-name>>:8082/* https://<<domain-name>>.<<top-level-domain>>>/*

Field	Value
Name	desktop-app
Description	desktop-app
Client authentication	ON
Authorization	OFF