Technical FAQ censhare components and Keycloak

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.

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.

Authentication and user management

censhare clients

censhare desktop and admin clients can be used as before.

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 (2022.1) Release frontend bundles and (2022.1) Build, release & deploy 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 (2022.1) DevOps environment and (2022.1) Build, release & deploy 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 (2022.1) Create custom branding.

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

You can download the RPM packages from the following source: 

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

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

See censhare installation

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.

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

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

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

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

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

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 standard 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

• 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 (2022.1) Release frontend bundles and (2022.1) Build, release & deploy 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 (2022.1) DevOps environment and (2022.1) Build, release & deploy 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 (2022.1) Create custom branding.

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 and Keycloak related services, see censhare 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. When setting up censhare, 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, the Social Media service can be installed during this process as well. It is an optional component.