Answers to technical questions around the new technology, Keycloak, and external authentication.
Benefits
Why should we upgrade?
Answer
censhare 2022.x bringsperformance 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
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.
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 aBranding asset that is assigned in theSystem asset no longer work. TheBranding 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:
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.
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.
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.
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.
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.
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.
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 aBranding asset that is assigned in theSystem asset no longer work. TheBranding 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.
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.