Keycloak user authentication requires users to have an account in Keycloak or to be linked to it, for example via LDAP. Learn how to create an account directly in Keycloak.

Introduction

When users log in via Keycloak for the first time, the censhare server automatically creates the corresponding account and the associated Person asset. Which parameters are then synchronized depends on the configuration. You create a user account in Keycloak to access censhare as a regular user.

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 20, which is an integral part of the censhare 2022.2 product delivery.

Add users to Keycloak

Create user

  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. See Configure Keycloak

  3. In the left navigation, select Users.

  4. Click Add user.

  5. The ID and Created at fields are filled automatically when you save the user profile.

  6. Enter the Username. The username serves as unique identifier to match the Keycloak user with a user in the censhare master data. If the user already exists in censhare, use the exact same username.

    Lowercase in usernames: Keycloak stores usernames and emails in lower case by design. Mixed-case letters are not supported in Keycloak. We, therefore, recommend to only use lowercase for your usernames. 

  7. Leave the Email, First Name and Last Name fields empty. These data are managed in the censhare master data.

  8. The User Enabled toggle must be switched ON. Otherwise, the user is inactive.

  9. Set the Email Verified and the Required User Actions fields according to your policies.

  10. Click Save.

Create user password

Assign a password to the user:

  1. Go to the Credentials tab to set the new user password.

  2. In the dialog window, select Temporary: OFF.

  3. Click Reset Password to activate the credentials.
  4. The password is confirmed.

User data synchronization

To use censhare, each user requires at least a default role and default domain. Additional roles and domains can be required, for example when you use the Standard governance model for censhare Web.

There are several options where to create these user data and how to synchronize them between censhare and Keycloak:

  • Add user data in censhare only and do not synchronize between Keycloak and censhare.
  • Add user data in Keycloak or via a template and synchronize with the user table of the censhare Server using a mapping process. For more information, see Authorization mapper.

Add user data in censhare

When Keycloak authenticates a user, the login request is redirected to the censhare Server. The user is logged in with the user profile that is stored in the master data on the censhare Server.

To add and configure a user, do the following:

  1. In the censhare Admin Client, open the Master data/Users table.
  2. Click the plus icon to add a new user.

  3. Enter the required fields. 

    To match a user that is authenticated via Keycloak, the Login name must match exactly the Username in Keycloak.

  4. In the Authentication fields, disable Standard, and select External, and then, in the Data synchronization field, select Don't synchronize.
  5. Click OK to save the new user.


Configure login from desktop clients

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

  1. Open the hosts.xml configuration. The default path is ~/Users/[USER]/Library/Preferences/censhare/hosts.xml.
  2. In the <host/> entry of the desired server, set the attribute authentication-method="external".
  3. Save the configuration.

Configure login from web-based clients

The enable login via Keycloak from a web-based client, no configuration is required. You can also configure alternative login methods in the System asset.

Result

The new user is now added in Keycloak and in censhare.

When a new user logs in for the first time and a language has been set in Keycloak (cs_locale), this is not set on the created Person asset. Locale changes in Keycloak are only applied to the Person asset, if the user already exists in censhare.