Skip to main content
Skip table of contents

Configure Keycloak with LDAP


You can add an LDAP/AD service to Keycloak to log in users to censhare with their LDAP/AD user profile.

Context

The setup is done in the censhare Admin Client and in the Keycloak administration console.

This article is only valid for censhare 2021.1.


Prerequisites

Introduction

To use the external authentication with censhare Web, a dedicated Keycloak authentication server is required. The user authentication is handled via this dedicated authentication server. Keycloak is used to log in to censhare Web, the censhare Client, and the censhare Admin Client. Keycloak serves as an identity broker for the censhare Server.

On the Keycloak server, the censhare realm contains the clients and respective configurations that handle the user authentication to censhare WP and the censhare Clients. When a user logs in, Keycloak sends a query to the LDAP/AD server that stores user profiles, attributes and permissions for all services within your organizational network.

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.

To use the LDAP profiles for user authentication in censhare, the LDAP/AD service must be added to the Keycloak user federation. In a user federation, user profiles (user names, passwords, personal data, and other attributes) are shared over multiple services.

To synchronize the user data from LDAP to censhare, a mapping is required. The mapping pairs the LDAP attributes with the corresponding censhare user attributes. Keycloak queries the required attributes from LDAP and adds them to the requested user profile. The mapping itself is done in censhare, similar to the mappings of a custom LDAP authentication.




Authentication schema via Keycloak with LDAP

Configure the user federation in Keycloak

To add your LDAP to the Keycloak user federation, do the following:

  1. Open the Keycloak URL and log in with your administration credentials.

  2. If not pre-selected, select the censhare realm. If the censhare realm is not configured yet, you must add it first.

  3. In the left navigation, select User federation.

  4. In the main area, in the Add provider field, select LDAP.

  5. The Enabled toggle must be switched ON.

  6. In the Console display Name, enter an internal name for the LDAP. Default is ldap. If you add multiple LDAP directories, choose meaningful internal names.

  7. In the Priority field, enter a priority value (integer). The priority is only relevant if you add multiple LDAP directories to the censhare federation. When Keycloak looks up a user, it first checks the LDAP directory with the lowest value, and so on.

  8. The Import Users toggle must be switched ON.

  9. In the Edit Mode field, select UNSYNCED.

  10. Switch OFF the Sync Registration toggle.

  11. Enter the parameters of your LDAP server in the respective fields. Mandatory fields are marked with a red asterisk.

  12. Leave the fields in the sections Kerberos Integration, Sync Settings and Cache Settings as is.

  13. Click Save to add the configuration to the censhare federation.

Configure attribute mappers in Keycloak

Keycloak queries the required user attributes from the LDAP server and passes them to the censhare Server. For this purpose, mapping is required. As the mapping can be quite complex, in this step the user attributes from LDAP are mapped as is. The actual mapping to the respective censhare user attributes is configured in censhare. This is described in the Configure internal server module section below.

When you saved your LDAP configuration, the Mappers tab displays on top. Configure the mappers as follows:

  1. Open the Mappers tab in the LDAP federation that you configured in the previous step.

  2. The following default mappers are pre-configured: No configuration is necessary here.

    • full name

    • last name

    • MSAD account controls

    • email

    • modify date

    • creation date

    • username

    To successfully log in to censhare, the domain and role attributes are required. The mappers for these attributes must be added manually.

  3. To add a new mapper, click Create.

  4. In the Name field, enter an internal name for the mapper. The internal name is not part of the mapping. You can choose any name.

  5. In the Mapper Type field, select user-attribute-ldap-mapper.

  6. The User Model Attribute field contains the target attribute name. Enter the exact same name as in the LDAP Attribute field (see following step).

  7. In the LDAP Attribute field, enter the name of the source attribute that you want to map.

  8. Switch the Read Only toggle ON.

  9. Switch the Always Read Value From LDAP toggle ON. This ensures that user attributes are synchronized with the LDAP data every time a user logs in.

  10. Switch the Is Mandatory In LDAP toggle ON. This ensures that only valid LDAP attributes are mapped.

  11. Switch the Is Binary Attribute toggle OFF.

  12. Click Save.

  13. Repeat the previous steps for each attribute that you want to map.

  14. When you are done, return to the Settings tab, and click Synchronize all users.

The Keycloak configuration is now complete. The following configurations are done in the censhare Admin Client.

Configure the Keycloak module in censhare

Important: If you are not familiar with the censhare domain framework and user configuration, contact censhare solution development for the proper configuration of the internal server module.

In the internal server module, you configure the censhare query and the user attribute mapping. To set up the module, do the following:

  1. In the censhare Admin Client, go to the Configuration/Modules/Server Internal Modules directory and open the Login by Keycloak configuration.

  2. In the dialog, click Edit XML file.

  3. Note: The <search/> query and filter parameters are not used in the module! You do not need to edit them.

  4. Edit the <mappings/> section with the user attribute mappings. The mapping defines all required and optional attributes to create or synchronize a censhare user:

    • The <group name="ldap2party-search"/> element maps the LDAP principal name to the corresponding censhare party.

    • The <group name="ldap2party"/> element maps the LDAP user attributes to the corresponding censhare user attributes and sets the defaults.

  5. Click OK to save your changes and close the XML editor.

  6. Click OK to save your configuration.

Configure the clients

To log in via Keycloak from the censhare Client and the censhare Admin Client, on the client computers, do the following:

  1. Open the hosts.xml configuration. The default path 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 Web

The login via Keycloak from censhare Web works without any further configuration. However, you can configure alternative login methods to censhare Web in the System asset.

Result

When users logs in to censhare Web, the censhare Client, or the censhare Admin Client, they are redirected to the Keycloak login page. When they enter their credentials, Keycloak retrieves the user data from the LDAP server and passes them to the censhare Server. Users are logged in with their default domain and role. New users can log in likewise. Their user profile is added to the censhare master data with the respective attributes.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close