Technical FAQ censhare WP and Keycloak

As of censhare 2021.2 censhare is released as censhare WP. censhare WP will bring performance improvements and increased speed for the web-based client application. Our customers will notice substantial performance improvements with the next major censhare release.

censhare 2021.2 also allows for external authentication methods such as two-factor authentication, LDAP and SAML as well as integrating your existing identify solutions. censhare WP uses  Keycloak  as an external authentication solution. Keycloak is an open-source identity and access management solution. 

As a side note and sneak-peek, it is the first step on our journey to the next censhare evolution - censhare in Hybrid Mode.

See Why censhare WP?

Note that our systems cannot yet fully deliver the expected performance improvements. We are working intensely to achieve the full performance benefits as soon as possible and keep you posted here.

Set up censhare WP as a new installation: 

censhare WP - RPM-based installation

Keep in mind that you have to set up Keycloak as an external authentication solution.

Keycloak authentication

Learn about Frontend customization and development:

(2021.2) Release frontend bundles

(2021.2) Build, release & deploy bundles

censhare WP

You or your partner or project manager can upgrade to censhare WP by:

• upgrading the censhare Server to the latest version
• installing additional helper packages and censhare WP services corresponding to the censhare Server version
• initial configuration

censhare WP

Keycloak

You must set up Keycloak as an external authentication solution.

• If you have Keycloak already in place in your organization, you can use that instance and configure it for censhare WP.
• If you use external authentication such as SAML or LDAP, you can use them in combination with Keycloak and configure Keycloak accordingly.
• If you use the censhare standard authentication, you must set up Keycloak and add your users to Keycloak once. You can do that with a script.
• Use the authorization mapper to synchronize the roles, domains, groups and other settings of a user from Keycloak with the user table of the censhare Server.

Keycloak authentication_SysAdmin

censhare clients

censhare desktop and admin clients can be used as before.

censhare Web

• Customizations: If the project has its own customization in form of additional frontend code (placed in the censhare-Custom folder), you need to properly build and deployed the expansions.  See (2021.2) Release frontend bundles and (2021.2) Build, release & deploy bundles.
• Branding: The dynamic branding with a  Branding asset that is assigned in the  System asset does no longer work. The  Branding asset is deprecated. If you upgrade your branded censhare from an earlier version to censhare WP, you must implement the new branding. Your old branding will not work on censhare WP. See (2021.2) Custom branding (censhare WP).

Keep in mind that an upgrade can therefore involve additional efforts!

Your users will log into any censhare client via the Keycloak login page. They are then redirected to the client's home page or dashboard. They will hardly notice the changed login. They can work with the censhare clients as before.

You can download the RPM packages from the following source: 

https://rpm.censhare.com/censhare-release-rpm/stable/censhare/<version>/

<version> = as of censhare 2021/2

The required additional components can be downloaded from:
https://rpm.censhare.com/tools-release-rpm/

Run the yum install command from a terminal window.

See Install and configure censhare WP

If you do not have censhare Server installed already, you install it as a separate RPM package. The package censhare Server can be downloaded from the central censhare RPM repositories.

We recommend to use an internal HAProxy instance on the server. Therefore we increase the sizings slightly. External HAProxy is usually only used when we have remote server configurations.

See censhare WP - Initial configuration.

If required, you can install Keycloak separately. We provide an RPM for Keycloak that can be installed from our repositories. This RPM does not have any dependency. So you could optionally run yum install keycloak-<version> with our RPM repositories.

<version> = Keycloak server version 16.1.1

If Keycloak is already in place in your organization, you can use your instance for external authentication with censhare.

See Install Keycloak

The Keycloak server requires:

• At least 512M of RAM

• At least 1G of disk space

• An external PostgreSQL database is also required. It can be the same as the database for the censhare Server.

For the full list of system requirements, see Keycloak system requirements

This depends on how you manage your environments. Environments can be separated by realms. 

We recommend to use one Keycloak instance per environment, particularly when upgrading.

It is not required to have a separate server just for Keycloak. Keycloak can be installed on the same server as the censhare Server. If you have a Keycloak instance already running, or for other reasons, Keycloak can be installed on a separate server than the censhare Server.

Keycloak should work fine with AWS. The easiest option is to install Keycloak locally. Anything else might turn into an overhead.

Keycloak requires the installation of censhare WP. 

The censhare WP web-based client and the desktop clients (Admin Client, censhare (Java) Client, Service Client, Render Client) can be used as before with Keycloak. Some initial configuration is required in Keycloak to use the clients. 

See Configure Keycloak for external authentication

Master data work as usual in censhare WP. There are no special aspects that you need to consider during an upgrade. 

The governance model does not change with censhare WP. Domains, roles and permissions are defined in censhare as usual.

You have to create a group in Keycloak which is mapped to group/role in the censhare Admin Client.

When migrating users from non-LDAP managed systems where roles have been defined in censhare Admin Client, then only the mapping of the Keycloak group must be done. 

You have to migrate your users to Keycloak. We provide a script for this purpose. You have to create a group in Keycloak which is mapped to a group/role in the censhare Admin Client. When you migrate users to Keycloak, passwords are lost and need to be set again. 

To censhare, Keycloak behaves like an LDAP server. The migration and mapping only need to be done once. If the mapping is complete, then Keycloak will map roles and domains. If there isn’t any mapping, then you must add it in the censhare Admin Client.

When migrating users from non-LDAP managed systems where roles have been defined in censhare Admin Client, then only the mapping of the Keycloak group must be done. In this case, users need to set their password again. New users will have the basic mapping.

You can use the same Keycloak instance for the Java and the web-based client. For the web-based client, censhare WP is required. In Keycloak, two clients must be configured: one for the Java-based censhare Client and the censhare Admin Client, and one for the web client.

See Configure Keycloak for external authentication

Yes. You can use Keycloak with censhare standard authentication. You have to migrate your users into Keycloak once.  We provide a script for this purpose. You have to create a group in Keycloak which is mapped to group/role in the censhare Admin Client. When you migrate users to Keycloak, passwords are lost and need to be set again. Migrate users to Keycloak.

Note that Keycloak stores all usernames as lowercase in the Keycloak database.

If you create new usernames, we recommend to only use lowercase letters in usernames to avoid any duplicates that might arise from mixed-case letters.

If you migrate existing users, note that there might be username duplicates in this case, but that users can still be identified correctly.

• censhare Web uses Keycloak authentication.

For the other censhare clients, standard authentication is used:

• The censhare Service Client and Render Client still use censhare internal authentication.
• censhare Client (aka Java Client) and censhare Admin Client still use censhare standard authentication.

Yes. Keycloak can be used with other authentication methods, such as SAML or LDAP, or two-factor authentication.

We assume, yes. We are working on providing an answer and best practice on this topic.

For example, users should be logged in to censhare and single-signed on into an external web portal using censhare as an identity broker. So users are not prompted for their credentials when logging in to the external web portal.

Answer:

In this scenario, the censhare user logging into censhare has to authenticate through Keycloak. The same applies to the external web portal, where the user has to use the same authentication. So far, we do not have any experience in this scenario, and cannot advise on it.

There might be possible solutions with SAML or Kerberos in combination with Keycloak.

• The SAML solution could look like this: Depending on the configuration, SSO could be used. It might be possible to configure Keycloak with SAML for authentication on the censhare server and the external web portal. It might be necessary to redirect the "external web portal" to the SAML site, which does not ask for the user name and password, but redirects back to the "external web portal" with the already authenticated user.  SAML can be used with Microsoft AD FS, Octa, or Google G Suite, for example.

• For a solution using Kerberos with Keycloak, we currently don't have experience and cannot advise on it.

On the Keycloak login page, users have the option to click a Forgot Password link.

We are working on a solution here right now so that this can be supported and configured for censhare. 

censhare Web

• Customizations: If the project has its own customization in form of additional frontend code (placed in the censhare-Custom folder), you need to properly build and deployed the expansions.  See (2021.2) Release frontend bundles and (2021.2) Build, release & deploy bundles.
• Branding: The dynamic branding with a  Branding asset that is assigned in the  System asset does no longer work. The  Branding asset is deprecated. If you upgrade your branded censhare from an earlier version to censhare WP, you must implement the new branding. Your old branding will not work on censhare WP. See (2021.2) Custom branding (censhare WP).

At the moment, only the censhare default theme can be used. We are working on suppporting custom login pages again.

For information on logging of censhare WP and Keycloak-related services, see censhare WP and Keycloak - Monitor and logging.

Nothing really changes here as it is dependent on the web socket.

Currently, we do not have any experience with this. We will update this answer as soon as we have relevant test results.

Google Cloud AI service - This service is used to send requests from the censhare Server to analyze texts, images, or videos to Google Cloud AI. The service can be used with censhare WP. When setting up censhare WP, the Google Cloud AI service can be installed during this process as well. It is an optional component.

Social Media service - With the social media management integration, users can plan, create, publish, and evaluate their social media activities entirely in censhare Web . When setting up censhare WP, the Social Media service can be installed during this process as well. It is an optional component.

previously: The Sync party mapping was only used when creating a user, but not when updating a user.

now: On censhare Server, the Sync party mapping is now used for every login. censhare users can be created and updated when logged in via Keycloak to the censhare Client and censhare web-based Client.

The fix is released with censhare 2020.1.3.

Type some text into the Comment field of the configuration dialog. Click OK. Make your edits. Click OK again.

Your edits are now saved. You can update the server configuration.