The external authentication of censhare WP uses Keycloak as authentication server for censhare WP and the censhare Clients. Keycloak can be configured with the censhare standard login. Keycloak verifies the user credentials and authenticates the user. The necessary user attributes are managed in the master data as before.
Context
The setup is done in the censhare Admin Client and in the Keycloak administration console.
Prerequisites
Installation of censhare WP
The censhare realm and clients on the Keycloak server, and the Keycloak service in the censhare Admin Client
An administration account for the censhare Admin Client and the Keycloak server
Introduction
Note: The setup in this article refers to censhare WP (webpacked). censhare WP requires external authentication via Keycloak. The censhare standard authentication refers to the authentication that uses user data from the censhare master data. Technically, this is configured in censhare WP as external authentication, because Keycloak serves as a gatekeeper and verifies the username/password externally, before passing the user to the censhare server, where the required and optional user attributes are taken from the Master data/Users table.
To use the external authentication via Keycloak with censhare WP, a dedicated authentication server is required. The user authentication is handled via this dedicated authentication server. Keycloak is used to log in to censhare WP, the censhare Client, and the censhare Admin Client. Keycloak does not serve as an identity broker between censhare Server and an identity provider, but as a gatekeeper to the censhare Server.
On the Keycloak sever, the censhare realm contains the clients and respective configurations that handle the user authentication to censhare Web and the censhare Clients. In this setup, Keycloak only verifies the user identity (user name and password) and passes the user to the censhare Server. The user profile (default domain and default role, groups, additional domains and roles) are managed as before in the master data. No external user attributes are handled.
If you use already 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 setup Keycloak first, before you proceed with this configuration.
Authentication schema via Keycloak with censhare standard login
Configure the clients
To log-in via Keycloak from the censhare Client and the censhare Admin Client, on the client computers, do the following:
Open the hosts.xml configuration. The default path is ~/Users/[USER]/Library/Preferences/censhare/hosts.xml.
In the <host/> entry of the desired server, set the attribute authentication-method="external".
Save the configuration.
Configure censhare WP
The login via Keycloak from censhare WP works without any further configuration. However, you can configure alternative login methods to censhare WP in the System asset.
Add users to Keycloak
To add a user to Keycloak, do the following:
Open the Keycloak URL and log in with your administration credentials.
If not pre-selected, select the censhare realm. If the censhare realm is not configured yet, you must add it first.
In the left navigation, select Users.
Click Add user.
The ID and Created at fields are filled out automatically when you save the user profile.
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.
Leave the Email, First Name and Last Name fields empty. These data are managed in the censhare master data.
The User Enabled toggle must be switched ON. Otherwise, the user is inactive.
Set the Email Verified and the Required User Actions fields according to your policies.
Click Save.
Now, click Impersonate. The new account opens in a new browser tab.
Open the new browser tab, and in the left navigation, select Password.
Enter a password and confirm the password.
Now, the additional tabs display next to the Details tab.
Go to the Credentials tab, and enter a New Password and Password Confirmation.
Click Reset Password to activate the credentials.
Notes:
(1) Attributes are not transmitted from Keycloak to the censhare Server. Attributes are managed in the censhare master data (see the following section). Do not enter any user attributes in the Attributes tab in Keycloak.
(2) The Role mappings are set automatically. The Role mappings ensure that users are authenticated at the censhare Server. Do not add the censhare default role and additional roles here. The censhare roles are managed in the censhare master data (see the following section).
(3) Groups are not transmitted from Keycloak to the censhare Server. Groups are managed in the censhare master data (see the following section). Do not enter any groups in the Groups tab in Keycloak.
The new user is now configured in Keycloak. Next, you must add this user to the censhare master data.
Configure user master data
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:
In the censhare Admin Client, open the Master data/Users table.
Click the plus icon to add a new user.
Enter the required fields.
Important: To match a user that is authenticated via Keycloak, the Login name must match exactly the Username in Keycloak.
In the Authentication fields, deselect Standard, and select External, and then, in the Data synchronization field, select Don't synchronize.
Click OK to save the new user.
The user configuration is now complete.
Result
When users log in to censhare WP, they are authenticated with their credentials by the Keycloak server. Keycloak then redirects the users to the censhare Server. Users are logged in with their roles, domains, and groups from the user profile in the censhare master data.