Skip to main content
Skip table of contents

Technical FAQ censhare components and Keycloak

Answers to technical questions around the new technology, Keycloak, and external authentication.

Benefits

Why should we upgrade?

Answer

censhare 2022.x brings performance improvements and increased speed for the web-based client application.

censhare 2022.x uses external authentication with Keycloak. Keycloak is an open-source identity and access management solution. You can use two-factor authentication, LDAP and SAML as well as integrate your existing identify solutions. 

This is the first step on our journey to the next censhare evolution - censhare Hybrid.

Also, we have implemented long-awaited and convenient new functionality and enhanced and improved many existing features.


Changes

What does the upgrade involve?

Answer

censhare server and additional components

You or your partner or project manager can upgrade by:

  • upgrading the censhare Server to the latest version
  • installing additional censhare tools and services
  • carry out the initial configuration

censhare installation

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.
  • 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 or migrate your users to Keycloak.
  • 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

censhare clients

censhare desktop and admin clients can be used as before.

censhare Web

Partner login is required to access the instructions below.

  • Customization updates: If the project has its own customization in form of additional frontend code (placed in the censhare-Custom folder), and for any locale that is used, you need to properly build and deploy the extensions. See Release frontend bundles and Build, release, deploy frontend bundles. This can be prepared in a local Dev environment. See Getting started censhare
  • Customization workflow: Developing censhare custom solutions now involves additional steps. You have to set up a DevOps environment that allows you to track, merge, test, stage and deploy the desired scope of changes. Customizations involved building, releasing, and deploying weppacked frontend bundles. See DevOps environment and Build, release, deploy frontend bundles.
  • Branding: The dynamic branding with a  Branding asset that is assigned in the  System asset no longer work. The  Branding asset is deprecated. If you upgrade your branded censhare from an earlier version below 2021.2, you must implement the new branding. Your old branding will not work anymore. See Custom branding.
Keep in mind that an upgrade can therefore involve additional efforts!

What will change for our users when we upgrade from 2020.x or below?

Answer

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. The login page can be branded.


Deployment

Where can we find the RPM downloads for installation?

Answer

You can download the RPM packages from the following source: 

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

For example:

https://rpm.censhare.com/censhare-release-rpm/stable/censhare/2022/2/

Additional components are required and can be downloaded from:
https://rpm.censhare.com/tools-release-rpm/

See censhare installation


Is a Load Balancer required?

Answer

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 Initial configuration.


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

Answer

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-20-0.3-1

(Keycloak server version)

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?

Answer

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 for a development, test, and productive system?

Answer...

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?

Answer

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?

Answer

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?

Answer

Keycloak requires the installation of censhare 2022.x or above. 

The censhare clients can be used as before with Keycloak. Some initial configuration is required in Keycloak to use the clients. 

See Configure Keycloak


Setup

What happens to the master data when we upgrade?

Answer

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


What about roles and permissions?

Answer

The governance model does not change. Domains, roles and permissions work as before.

In Keycloak, you create user groups and optionally user attributes for this purpose. These are mapped to the censhare roles and domains. In Keycloak, a user group matches a censhare role. The censhare authorization mapper synchronizes these user data from Keycloak with the user table of the censhare server.

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. 

See Authorization mapper


Authentication

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

Answer...

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.

See Authorization mapper


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

Answer

You can use the same Keycloak instance for the Java and the web-based client. For the web-based client, censhare 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


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

Answer

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 in Keycloak?

Answer

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. This needs to be corrected.


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

Answer...
  • censhare Web uses Keycloak authentication.

For the other censhare clients, standard authentication is used:

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

Can we use Keycloak with other authentication methods?

Answer

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?

Answer

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?

Answer

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?

Answer

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?

Answer

censhare Web

  • Customization updates: If the project has its own customization in form of additional frontend code (placed in the censhare-Custom folder), and for any locale that is used, you need to properly build and deploy the extensions. See Release frontend bundles and Build, release, deploy frontend bundles. This can be prepared in a local Dev environment. See Getting started censhare
  • Customization workflow: Developing censhare custom solutions now involves additional steps. You have to set up a DevOps environment that allows you to track, merge, test, stage and deploy the desired scope of changes. Customizations involved building, releasing, and deploying weppacked frontend bundles. See DevOps environment and Build, release, deploy frontend bundles.
  • Branding: The dynamic branding with a  Branding asset that is assigned in the  System asset no longer work. The  Branding asset is deprecated. If you upgrade your branded censhare from an earlier version below 2021.2, you must implement the new branding. Your old branding will not work anymore. See Custom custom branding.

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

Answer

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?

Answer

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


Will web time-out issues change?

Answer

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


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

Answer

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


Optional components

Do we need to install Google Cloud AI?

Answer

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. When setting up censhare, the Google Cloud AI service can be installed during this process as well. It is an optional component.


Do we need to install the Social Media service?

Answer

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, the Social Media service can be installed during this process as well. It is an optional component.


JavaScript errors detected

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

If this problem persists, please contact our support.