Initial configuration of censhare WP, including Webpack and the required Keycloak settings.

Webserver service

By default, Webserver service is activated. 

If not, do the following:

  1. In the censhare Admin Client, go to Configuration > Services > Webserver and double-click Configuration.

  2. In the Configuration dialog, activate Service enabled and click OK.

Keycloak for censhare WP

If Keycloak is already set up for your organization, note down the required information as stated in Cloud Gateway.

If you just installed Keycloak, follow these steps before you continue to configure Cloud Gateway:

  1. Create a Keycloak system admin and start the Keycloak server
  2. Configure the censhare realm and realm keys
  3. Create internal admin user
  4. Configure the censhare web application client
  5. Optionally, configure censhare desktop client
  6. Configure the hosts.xml
  7. Configure censhare Server to access Keycloak

Cloud Gateway

Before you begin

(1) To configure the Cloud Gateway, complete the Keycloak configuration first. Y ou need the some keys from Keycloak for the Cloud Gateway configuration .

(2) The following configuration shows the minimal setup to access the application. Further configuration of the Cloud Gateway can be necessary for session handling and custom branding.

Obtain required Keycloak information

  1. Log into Keycloak as administrator.
  2. Note down the following information from the censhare web application client in the Clients section:

  • Keycloak client name
    If you follow the censhare Keycloak documentation, the default name is censhare 5 OpenID client. It may be different in your case.

  • Keycloak Client ID
    If you follow the censhare Keycloak documentation, the default name is censhare5. It may be different in your case.

  • Keycloak client secret
    The censhare WP client Secret from your Keycloak server

  • Keycloak server base URL
    For example: http://keycloak:8080/auth. Note that https requires the use of a Reverse Proxy.

The default configuration for the Cloud Gateway service are set in the code. As of that, you do not need to specify the default values in the application.yml file. Therefore, these settings are commented out. This prevents the application.yml file from overwriting the default values with older values if the values have been changed in the code. If you do not want to use the default settings, comment out the appropriate lines and change the settings.

When installing the RPM package, the application.yml file is not overwritten if it has changed. Instead, the installation creates an application.yml.rpmnew file. Compare both files for new or changed default settings.

Adapt the data for Cloud Gateway

Have the Keycloak configuration options at hand.

  1. Go to /censhare-product/core-cloud-gateway/application.yml.

  2. Open the file with an appropriate editor.

  3. Set the server port: 

    server.port: 8082
    YML

  4. Enable Load Balancer headers. These are required to use Load Balancer headers and send the right redirect_uri to the Keycloak server: 

    server.forward-headers-strategy: native
    YML

Adapt the data for Keycloak

  • Client ID

    spring.security.oauth2.client.registration.keycloak.client-id: <keycloak-client-id>
    YML

  • Client name

    spring.security.oauth2.client.registration.keycloak.client-name: <keycloak-client-name>
    YML

  • Client secret 

    spring.security.oauth2.client.registration.keycloak.client-secret:
    YML

    Uncomment the line and replace the secret with the respective censhare WP client secret in your Keycloak server.

  • External Keycloak URL

    For the following URIs, replace the URLs with your external Keycloak URL. For example, http://keycloak:8080/auth: 

    spring.security.oauth2.client.provider.keycloak.authorization-uri: https://authentication-example.censhare.com/auth/realms/censhare/protocol/openid-connect/auth
spring.security.oauth2.client.provider.keycloak.token-uri: https://authentication-example.censhare.com/auth/realms/censhare/protocol/openid-connect/token
spring.security.oauth2.client.provider.keycloak.user-info-uri: https://authentication-example.censhare.com/auth/realms/censhare/protocol/openid-connect/userinfo
spring.security.oauth2.client.provider.keycloak.jwk-set-uri: https://authentication-example.censhare.com/auth/realms/censhare/protocol/openid-connect/certs
    YML

Adapt URL for password change

Users need to manage password changes via the Keycloak Account Management. You have to configure the redirect from the password change dialog of censhare Web to the required Keycloak URL. 

To make that URL work, you have to configure a rule in Cloud Gateway, which maps it to the Keycloak Account Management page. Add an entry similar to this: 

spring.cloud.gateway.routes:
        - id: censhare5_change_password_redirect
          uri: http://localhost:8080
          predicates:
            - Path=/censhare5/client/change-password
          filters:
            - SetPath=/auth/realms/censhare/account
CODE

Important

(1) Replace  http://localhost:8080 with the correct host and port of your local Keycloak server.

(2) If you use one or multiple custom brandings, you must set the password change routes for each branding separately. For more information, see Custom branding.

Adapt the routes to the censhare Server

For the following IDs:

  • censhare5_rest_endpoint

  • censhare5_forward_rest_endpoint

  • censhare5_upload_endpoint

  • censhare5_websocket_endpoint

  1. Uncomment all entries for the affected routes.

  2. In the uri of each route, change the http://censhare-server URLs to point to your censhare Server :

    • If Cloud Gateway and censhare Server are running on the same computer, you can use the localhost. For example, http://localhost:9000

    • If Cloud Gateway and censhare Server are not running in the same subnet, use the server name or full server name. For example, server name , full server name <censhare-server>.com .

Important

If you use one or multiple custom brandings, you must set the endpoints for each branding separately. For more information, see  Custom branding.

Adapt the route to the Static Resource Server

For the following ID: 

  • static_resources

  1. Uncomment the entry for the affected route.

  2. Change the uri to point to your Static Resource Server.

    • If Cloud Gateway and Static Resource Server are running on the same computer, you can use the local host. For example, http://localhost:8081 .

    • If Cloud Gateway and Static Resource Server are not running in the same subnet, use the server name or full server name. For example, server name , full server name <static-resource-server>.com .

  3. If you have adapted any ports, you find them here: 

    /opt/censer/static-resource-server/application.yml
    BASH

    Variable: server.port

Configure session handling

To avoid broken UI and other issues, check if the cg.censhareLogoutUrl parameter is missing in the application.yml and add it. See Configure session handling for the complete session handling configuration.

Restart the service

sudo systemctl restart censhare.core-cloud-gateway
BASH

Static Resource Server

Here you can use localhost as hostname only if Cloud Gateway, Static Resource Server, Keycloak, and censhare Server are running on the same computer.

Important to configure here is the Auth URLs taken from Keycloak.

You can use the server name as hostname instead of the full server name if Cloud Gateway, Static Resource Server, Keycloak, and censhare Server are running in the same subnet of your network.

Default configuration settings for the service are set in the code. As of that, you do not need to set the default values in the application.yml file. To show this, these settings are commented out. This prevents the application.yml file overwrites default settings with older values when the settings have been changed in the code. Only uncomment settings if you want to change them.

The installation of the RPM package does not overwrite the application.yml file if it has changed. Instead, the installation creates a new application.yml.rpm file. Compare both files to detect new or changed default settings.

Adapt the application.yml file for the Static Resource Server

  1. Go to /opt/censer/static-resource-server.

  2. Open application.yml  in an editor.

  3. Uncomment the line with application.server.rest.url. If the Static Resource Server is running on the same computer as the censhare Server, you can use the local host, for example,  http://localhost:9000/ . If the censhare Server is running on a different computer, replace localhost with the external URL, for example, http://censhare.your-company.com:9000/ws/rest/. In addtion, HAProxy will take care of the correct redirection.

  4. Uncomment the line with spring.security.oauth2.resourceserver.jwt.jwk-set-uri and replace localhost with the server name where Keycloak is running. For example, http:// authentication.your-company.com:8080/auth/realms/censhare/protocol/openid-connect/certs

Webpack

The configuration for the webpack files depends on whether you have customized the censhare Web user interface or added additional user interface languages.

Before you begin

Ensure that Node.js 10 or higher is installed.

censhare Web without customization

If you have not yet done any customization of the web interface, you can download and deploy the frontend bundles as is. The download includes the bundles for German and English user interface.

  1. You find the frontend bundles for the censhare releases here: https://rpm.censhare.com/artifactory/webpack-release/. 
  2. Change to the directory containing your censhare version, for example https://rpm.censhare.com/artifactory/webpack-release/2021.2.2/.

  3. Download the bundle, for example webpack-2021.2.3.tar.gz:

    curl --user repo-user https://rpm.censhare.com/artifactory/webpack-release/2021.2.4/webpack-2021.2.4.tar.gz -o webpack-2021.2.4.tar.gz
    BASH

censhare Web with customization

If you want to customize the censhare Web frontend, you must build and deploy the customized frontend bundles to the censhare host. For more information, see Getting started censhare WP.

Redirects 

If you use a load balancer such HAProxy or a reverse proxy, such as NGINX, set the relevant redirects. For more information, see Load balancing with HAProxy.

censhare Google Cloud AI

Optional service. For more information, see Configure Google Cloud AI service.

censhare Social Media 

Optional service. For more information, see Social media management.


censhare Email service

User login to censhare Web

Once you have set up all services, users can log in to the censhare web client. They enter their credentials in the Keycloak login screen. They are then logged into censhare Web.

Next steps

Check the censhare WP services and logs