Configure Keycloak for external authentication
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.
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
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
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.
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.
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.
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 (*). |
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.
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.
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). |
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.
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_sysadmin
- 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:
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.
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:
|
application@keycloak-logout | true | no | Location of the setting: censhare Admin Client → Configuration → Modules → Clients → Client → Client Preferences:
|
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:
|
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.