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

Server configuration

If not configured already, take care of the initial server configuration. For more information, see Initial censhare Server configuration.

Webserver service

By default, the 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.

  3. You can test if the service is activated using curl:

    curl -I -k https://localhost:9443/censhare5/client
HTTP/1.1 301 Moved Permanently
Date: Mon, 01 Aug 2022 10:06:45 GMT
X-Frame-Options: SAMEORIGIN
Location: /censhare5/client/
Content-Length: 0
    CODE

    A "connection refused" error indicates that the service is not activated:

    curl -I -k https://localhost:9443/censhare5/client
curl: (7) Failed connect to localhost:9443; Connection refused
    CODE

Keycloak 

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

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. Initial censhare Server configuration
  8. Configure censhare Server to access Keycloak

Cloud Gateway

Before you begin

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

(2) For custom branding, further configuration of the Cloud Gateway is required. See custom branding (partner login required).

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 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 is set in the code. 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 /opt/censer/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 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 custom brandings, you must set the password change routes for each branding separately. For more information, see custom branding (partner login required).

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, ws://localhost:9000. Ensure to use "ws" instead of HTTP in this case.

    • 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 custom brandings, you must set the endpoints for each branding separately. For more information, see custom branding (partner login required)

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

All session requests from the user client to the censhare Server are routed through the Cloud Gateway. For secure session handling, you must configure the involved components accordingly and set the appropriate session timeouts and cookie attributes. To avoid broken UI and other issues, check if the cg.censhareLogoutUrl parameter is missing in the application.yml and add it. 

For more information, see Configure session handling. 

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 are the Auth URLs taken from Keycloak.

You can use the server name as a 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 addition, 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

Restart the service

sudo systemctl restart censhare.static-resource-server
BASH

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 webpack bundles as is. The download includes the bundles for German and English user interfaces.

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

  3. Download the bundle and unpack it directly to /opt/webpack, for example, webpack-2022.1.0.tar.gz:

    mkdir /opt/webpack
curl --user repo-user https://rpm.censhare.com/artifactory/webpack-release/2022.1.0/webpack-2022.1.0.tar.gz | tar -C /opt/webpack -xzf -
    BASH

censhare Web with customization

For update installations, 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 Build, release & deploy bundles (partner login required).

Redirects 

If you use a load balancer such HAProxy, 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

Modern mail service. For more information, see Install Mail 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 services and logs