A technical Q&A around censhare WP, external authentication, and Keycloak topics.

Benefits

Why should we upgrade to censhare WP?

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.


New installation

We are new to censhare. How are we impacted?

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:

Frontend customization

Build and release web-packed frontend


Upgrade

We already use censhare. What does the upgrade to censhare WP with Keycloak involve?

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 Frontend customization and Build and release web-packed frontend.
  • 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 Custom branding.


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

What will change for our users when we upgrade to censhare WP?

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.


Deployment

Where can we find the RPM downloads for installation?

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


How do we install censhare Server for the censhare WP services?

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.


Is a Load Balancer required for censhare WP?

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.


Is a separate RPM for Keycloak provided or how should we install Keycloak?

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


What are the system requirements for 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

How many Keycloak servers are necessary - development/test/productive system?

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.


Does the Keycloak server need to be installed on a separate server?

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.


Do you recommend using Keycloak on AWS as an ECS cluster?

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


Does Keycloak require to install dedicated censhare clients?

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


Setup

What happens to the master data when we upgrade?

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


What about roles and permissions with censhare WP?

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. 


Authentication

How does password management and synchronization work between censhare and Keycloak?

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.


Is there a shared integration with Keycloak for the desktop and web client?

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


We are using the censhare standard login for our user management. Can we migrate our users and how?

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.


Is there anything we need to consider regarding usernames into 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.


How to authenticate at the censhare clients if we decide not to use Keycloak as Single sign-on?

  • 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.

Can we use Keycloak with other authentication methods?

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


Can we have a dedicated Keycloak to LDAP connection for named users?

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


Can we use censhare as SSO Identity Provider with Keycloak?

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.


Can users reset their password in Keycloak and how?

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. 



Frontend development

What will change for solution developers regarding frontend development?

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 Frontend customization and Build and release web-packed frontend.
  • 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 Custom branding.

We use a custom login page. How can we customize our login page now?

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


Operation

How to collect log information for censhare WP and Keycloak?

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


Will web time-out issues change with WP?

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


Sizing: how many users can work with one censhare WP before we should install a second one?

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


Optional components of censhare WP

Do we need to install Google Cloud AI with censhare WP?

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.


Do we need to install Social Media service with censhare WP?

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.


Known issues & workarounds

censhare users cannot be updated if they are logged in via Keycloak

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.


censhare Admin Client does not save my edits on the Keycloak service configuration

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.