Initial configuration for censhare tools: Cloud Gateway and Static Resource Server

Cloud Gateway configuration

This needs to be done in the application.yml file that resides in the /opt/censer/core-cloud-gateway/ folder.

Important

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

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

(3) When installing a new RPM package, the application.yml file is not overwritten if it has changed since the previous installation. Instead, the new installation creates an application.yml.rpmnew file that contains changes added by censhare for the new release. Therefore, you need to compare both files for new or changed default settings. Only the application.yml file is later used by the system as the source of configuration. To avoid missing any changes, you need to add them from the application.yml.rpmnew file in the application.yml file. In doing so, you keep both your changes and changes made by censhare. 

Default Cloud Gateway configuration

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.

Cloud gateway can be configured with just the following options, if no custom brandings are used:

server.port: 8082
spring.zipkin.enabled: false
 
spring.security.oauth2.client.registration.keycloak.client-id: censhare5
spring.security.oauth2.client.registration.keycloak.client-name: censhare5
spring.security.oauth2.client.registration.keycloak.client-secret: *****************************
KEYCLOAK_DOMAIN: keycloak.example.com
CENSHARE_SERVER_HOST_PORT: localhost:9000
SRS_HOST_PORT: localhost:8081
XML

Therefore, you may not need to go through all the steps described below. However, we highly recommend to check them.

Adapt Keycloak-related configuration

  • Log in to Keycloak as administrator.
  • Note down the following information from the censhare web application client in the Clients section (or keep it open to have all information at hand):
    • 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.
  • Change Client ID
spring.security.oauth2.client.registration.keycloak.client-id: <keycloak-client-id>
YML
  • Change Client name
spring.security.oauth2.client.registration.keycloak.client-name: <keycloak-client-name>
YML
  • Change Client secret: Uncomment the line and replace the secret with the respective censhare client secret from your Keycloak server.
spring.security.oauth2.client.registration.keycloak.client-secret:
YML
  • Change External Keycloak URL
## Replace following domain with the correct one where Keycloak is running at
#KEYCLOAK_DOMAIN: authentication-dev.censhare.com
YML

Adapt URL for the password change

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

To make that URL work, you have to configure a rule in the 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

  • Uncomment entries for any of the affected routes in the list
    • censhare5_rest_endpoint
    • censhare5_forward_rest_endpoint
    • censhare5_upload_endpoint
    • censhare5_websocket_endpoint
  • 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 endpoints for each branding separately. For more information, see custom branding (partner login required)

Adapt the route to the Static Resource Server

For the ID static_resources, do the following:

  1. Uncomment the entry for the affected route.

  2. Change the URI to point to your Static Resource Server, depending on your physical infrastructure:

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

Optional | Change the server port

The default server port is already set to 8082 which does not need to be changed in the usual case. If you already run something not censhare-related that already occupies port 8082 and is not able to change the port for this other tool, you may set the server port to another value.

server.port: 8082
YML

Things to check | The forward setting

The Load Balancer headers must be enabled (and they are by default). These are required to use Load Balancer headers and send the right redirect_uri to the Keycloak server: 

server.forward-headers-strategy: native
YML

!! Restart the service

This is mandatory for the changes to take effect.

sudo systemctl restart censhare.core-cloud-gateway
BASH

Static Resource Server configuration

This needs to be done in the application.yml file that resides in the /opt/censer/static-resource-server/ folder.

Important

(1) To configure the Static Resource Server, complete the Keycloak configuration first. You need some keys from Keycloak for the Cloud Gateway configuration. See Configure Keycloak for exact information.

(2) When installing a new RPM package, the application.yml file is not overwritten if it has changed since the previous installation. Instead, the new installation creates an application.yml.rpmnew file that contains changes added by censhare for the new release. Therefore, you need to compare both files for new or changed default settings. Only the application.yml file is later used by the system as the source of configuration. To avoid missing any changes, you need to add them from the application.yml.rpmnew file in the application.yml file. In doing so, you keep both your changes and changes made by censhare. 

Default Static Resource Server configuration

The default configuration for the Static Resource Server 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.

Hostname configuration

If you need to change the default hostname, then you have two options:

  • You can use localhost as the hostname only if Cloud Gateway, Static Resource Server, Keycloak, and censhare Server are running on the same computer.
  • 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.

Auth URLs

Important to configure here are the Auth URLs taken from Keycloak. In the /opt/censer/static-resource-server/application.yml:

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

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

This is mandatory for the changes to take effect.

sudo systemctl restart censhare.static-resource-server
BASH


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.

Next steps

Check the censhare services and logs