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

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.

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 2022.2 product delivery.

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


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

KEYCLOAK_ADMIN=<username>
KEYCLOAK_ADMIN_PASSWORD=<password>
BASH

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.


  1. 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.
  2. In the left sidebar, click the Master realm and select Create realm.
  3. In the dialog, enter censhare in the Name field.
  4. 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.


Create the user

  1. In the left sidebar of the Keycloak admin console, under Manage, open the Users menu.
  2. On the right side of the screen, click Add user.

  3. Enter the following details:

    FieldValue
    Username
    keycloak-admin
    Email 1 your email address
    First Name 1 Enter any name.
    Last Name 1 Enter any name.
    User enabledON
    Email verifiedOFF
    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!

  4. Save your changes.

Assign role mappings

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

  1. In the new user detail view, go to the Role Mapping tab.
  2. Click Assign Role.
  3. Click on the downward-facing arrow right next to the filter icon to access the client level roles.
  4. Type in realm in the search field.
  5. 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. 

  1. In the left navigation pane, under Manage -> Users open the admin user.
  2. Go to the Credentials tab.
  3. Click Set password.
  4. Enter your password.
  5. Switch the Temporary toggle to OFF.
  6. 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 KC 20.

Import new client configuration

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


  1. In the left sidebar of the Keycloak admin console, open the Clients menu.
  2. 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.
  3. 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:

      FieldValue
      Name
      censhare5
      Description
      censhare5
      Client authenticationON
      AuthorizationON
      Service account rolesON
    2. Save your changes.

    3. On the Settings tab, under Access settings, enter the following values:

      FieldValue
      Root URL
      http://localhost:8082/
      Valid Redirect URIs
      http://localhost:8082/*

      http://localhost:9000/*
  4. Go to the Credentials tab.
  5. 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. 
  6. 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. Consult 

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 Protocol

openid-connect


Access Type

confidential


Standard Flow Enabled

ON


Implicit Flow Enabled

OFF


Direct Access Grants Enabled

ON


Service Accounts Enabled

ON


Authorization Enabled

ON


Root URL

[CENSHARE_WEB_BASE_URL]

Enter the URL from which users access the web-based censhare client.

Valid Redirect URIs

[CENSHARE_WEB_BASE_URL]*

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 (*).

  1. Click Save.

  2. Go to the Credentials tab.

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

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

  1. In the left sidebar of the Keycloak admin console, open the Clients menu.
  2. 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.
  3. 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:

      FieldValue
      Name
      desktop-app
      Description
      desktop-app
      Client authenticationON
      AuthorizationOFF
      Service account rolesOFF
    2. Save your changes.

    3. On the Settings tab, under Access settings, enter the following values:

      FieldValue
      Root URL
      http://localhost:8082/
      Valid Redirect URIs
      http://localhost:8082/*
  4. Go to the Credentials tab.
  5. 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 Protocol

openid-connect


Access Type

confidential

In Keycloak 21, this is called Client authentication.

Standard Flow Enabled

ON


Implicit Flow Enabled

OFF


Direct Access Grants Enabled

ON


Service Accounts Enabled

OFF


Authorization Enabled

OFF


Root URL

[KEYCLOAK_BASE_URL]

Enter the Keycloak server URL (absolute URL). The base URL must be accessible from the client computers inside your corporate network.

Valid Redirect URIs

[KEYCLOAK_BASE_URL]*

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

[KEYCLOAK_BASE_URL]

Enter the Keycloak server URL (absolute URL).

Web Origins

[KEYCLOAK_BASE_URL]

Enter the Keycloak server URL (absolute URL).

  1. Click Save.

  2. Go to the Credentials tab.

  3. 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:


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.

  1. Open the hosts.xml file. The default path on macOS is  /Users/USER/Library/Preferences/censhare/hosts.xml.
  2. In the entry of the desired server, set the attribute  authentication-method="external".
  3. 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.

  1. In the censhare Admin Client, open the Configuration/Services/Keycloak admin client service directory, and open the Configuration file.

  2. Select the Service enabled field.

  3. In the Invocations field, select the maximum number of parallel processes. The default is 2.

  4. Leave the Version field unaltered.

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


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

    Admin user access password

    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.

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

  7. Click OK to save the configuration.

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

PropertyValueEnabledComment
com.censhare.desktop-client.keycloak.server-side-logouttruenoLocation of the setting: censhare Admin Client → Configuration → Server → Launcher:
  • Set to false to disable
  • Only disable if application@keycloak-logout is enabled
application@keycloak-logouttrueno

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.