2. Configuration

The app UCS Intercom Service offers various configuration options. Some settings don’t allow changes after installation. Therefore, you must set them before installation. You find those settings marked with Only before installation in Settings. You can change all other settings at any time after the installation.

To change settings after installation, sign in to the UCS management system with a username with administration rights and go to App Center ‣ UCS Intercom Service ‣ Manage Installation ‣ App Settings. On the appearing Configure UCS Intercom Service page, you can change the settings and apply them to the app by clicking Apply Changes.

The App Center then re-initializes the Docker container for the app UCS Intercom Service. Reinitialize means the App Center throws away the running ICS Docker container and creates a fresh ICS Docker container with the just changed settings.

2.1. Intercom Service

The app UCS Intercom Service provides the backend for inter-app communication of Nextcloud, the UCS Portal, Matrix through the Nordeck bot, OX App Suite and XWiki.

Warning

This app doesn’t configure any Keycloak settings. It requires an existing client and realm setup in Keycloak.

2.2. Secrets

The app UCS Intercom Service requires secrets, that aren’t automatically generated. Those secrets are:

/etc/intercom-client.secret

The client secret for authenticating with the IdP. You can retrieve the client secret from the Keycloak Admin Console in the Authorization tab of the intercom-client.

/etc/matrix.secret

The secret for backend communication with the Matrix server. You can retrieve it from the automatic join app service on the system running Matrix.

The following command shows how to retrieve the secret for the backend communication with the Matrix server:

$ kubectl exec --stdin --tty synapse-0 -n matrix-000-prod -- \
    /bin/bash -c "cat /data/autojoin-appservice.yaml \
    | grep as_token \
    | sed -e 's/as_token. \(.\+\)/\1/'"

/etc/intercom-portal.secret

The secret to communicate with the UCS Portal navigation service. You can retrieve the secret from /etc/portal-navigation-service.secret.

/etc/intercom-redis.secret

The secret to communicate with the app Redis, that stores the sessions. It is only needed if you use an external Redis server. Otherwise, it will be generated during installation.

2.3. Settings

The following references show the available settings within the app UCS Intercom Service. Univention recommends to keep the default values.

intercom-service/settings/client-id

Defines the OIDC client name of ICS in Keycloak. The file /etc/ics_client.secret stores the secret of this client.

Required	Default value	Set
Yes	intercom	Only before installation

intercom-service/settings/user-unique-mapper

Defines the Keycloak ICS client token claim name mapper configured. The field must uniquely identify the user across Matrix, Nextcloud, OX App Suite, and the Nubus. Only the value entryuuid is guaranteed to be unique in Nubus.

Required	Default value	Set
Yes	entryuuid	Only before installation

intercom-service/settings/username-claim

Defines the Keycloak ICS client token claim name mapper configured. The field must contain the username of the user.

Required	Default value	Set
Yes	phoenixusername	Only before installation

intercom-service/settings/intercom-url

Defines the URL where you can reach ICS. This needs to be a externally reachable address as it’s used by the browser to connect to ICS.

Required	Default value	Set
Yes	https://ics.@%@domainname@%@	Only before installation

intercom-service/settings/base-url

Defines the base URL used to identify with the IdP. This URL must match the base URL defined in the OIDC client used on the IdP. The value should be the same as in intercom-service/settings/intercom-url.

Required	Default value	Set
Yes	https://ics.@%@domainname@%@	Only before installation

intercom-service/keycloak/url

URL of the Keycloak instance that ICS uses as IdP. ICS ignores this value, if intercom-service/settings/issuer-base-url is defined.

Required	Default value	Set
Yes	https://id.@%@domainname@%@	Only before installation

intercom-service/keycloak/realm-name

Name of the realm containing the configured OIDC ICS client. ICS ignore this value, if intercom-service/settings/issuer-base-url is defined.

Required	Default value	Set
Yes	UCS	Only before installation

intercom-service/settings/issuer-base-url

Defines a full base URL for the OIDC token issuer. Usually, the IdP Keycloak issues OIDC tokens.

This variable overwrites intercom-service/keycloak/url and intercom-service/keycloak/realm-name.

Only set this variable, if you really need to change the default URL generated from the before mentioned variables.

Required	Default value	Set
No	None	Only before installation

intercom-service/settings/origin-regex

Defines the origin CORS regular expression. Normally this will be the shared domain name. Changing this value may have security implications.

Required	Default value	Set
Yes	@%@domainname@%@	Only before installation

intercom-service/settings/log-level

Logging level for the standard output, as well as, log file at intercom-service.log.

Required	Default value	Set
Yes	info	Only before installation

intercom-service/settings/proxy

This setting is passed to node-axios within the container. It allows or disallows connections through a proxy server between ICS and apps like Matrix, Nextcloud, or OX App Suite, instead of a direct connection to the backends.

Required	Default value	Set
Yes	False	Before installation or application settings afterwards.

intercom-service/redis/host

Defines the host name of the Redis server. By default ICS uses the bundled Redis server.

Required	Default value	Set
Yes	redis-intercom	Before installation or application settings afterwards.

intercom-service/redis/port

Port where the Redis server is available.

Required	Default value	Set
Yes	6379	Before installation or application settings afterwards.

intercom-service/redis/user

The user name for the Redis server. By default ICS uses the default user.

Required	Default value	Set
Yes	default	Before installation or application settings afterwards.

intercom-service/matrix/url

Defines the URL, where you can reach the Matrix server. The file /etc/ics_matrix_as.secret stores the Matrix secret.

Required	Default value	Set
Yes	https://matrix.@%@domainname@%@	Only before installation

intercom-service/matrix/enabled

Defines if the Matrix proxy functionality is enabled. Set to False to disable Matrix.

Required	Default value	Set
Yes	True	Only before installation

intercom-service/matrix/server-name

Defines the server name of the Matrix server, that is a unique identifier configured in Matrix. The server name must match the configured server name in Matrix.

It isn’t necessarily the server name defined in intercom-service/matrix/url.

Required	Default value	Set
Yes	matrix.@%@domainname@%@	Only before installation

intercom-service/matrix/login-type

Defines the login type that ICS uses for the Matrix server.

Refer to the Matrix documentation for more information about login types.

Required	Default value	Set
Yes	uk.half-shot.msc2778.login.application_service	Only before installation

intercom-service/matrix/nordeck-mode

Defines the connection mode of the Nordeck bot.

Possible values: test, live, test proxies.

Required	Default value	Set
Yes	test	Only before installation

intercom-service/matrix/nordeck-url

Defines the URL, where you can reach the Nordeck bot.

Required	Default value	Set
Yes	https://meetings-widget-bot.@%@domainname@%@	Only before installation

intercom-service/portal/portal-url

Defines the URL for the UCS portal. The file /etc/ics_portal.secret stores the Portal API key.

Required	Default value	Set
Yes	@%@ucs/server/sso/fqdn@%@	Only before installation

intercom-service/xwiki/url

Defines the URL where you can reach XWiki. Set to empty to disable XWiki.

Required	Default value	Set
Yes	https://xwiki.@%@domainname@%@	Only before installation

intercom-service/xwiki/enabled

Defines the XWiki proxy functionality is enabled. Set to False to disable XWiki.

Required	Default value	Set
Yes	True	Only before installation

intercom-service/xwiki/audience

Defines the OIDC audience setting for XWiki that XWiki uses in the IdP Keycloak.

Required	Default value	Set
Yes	xwiki	Only before installation

intercom-service/nextcloud/audience

Defines the OIDC audience setting for Nextcloud that Nextcloud uses in the IdP Keycloak.

Required	Default value	Set
Yes	ncoidc	Only before installation

intercom-service/nextcloud/url

Defines the URL where you can reach Nextcloud. Set to empty to disable Nextcloud.

Required	Default value	Set
Yes	https://fs.@%@domainname@%@	Only before installation

intercom-service/nextcloud/enabled

Defines the Nextcloud proxy functionality is enabled. Set to False to disable Nextcloud.

Required	Default value	Set
Yes	True	Only before installation

intercom-service/nextcloud/origin

Defines the Nextcloud CORS setting. Usually this value is the same as intercom-service/nextcloud/url.

Required	Default value	Set
Yes	https://fs.@%@domainname@%@	Only before installation

intercom-service/certificates/external/root-ca-pem

Defines the host path to self-signed external certificates, allowing for secure communication with Nextcloud, Matrix and OX App Suite. The file must be in PEM format, allowing for multiple certificates in one file.

Required	Default value	Set
No	Empty	Only before installation

intercom-service/certificates/external/root-ca-crt

Defines the host path to self-signed external certificates, allowing for secure communication with Nextcloud, Matrix and OX App Suite. The file must be in CRT format.

Required	Default value	Set
No	Empty	Only before installation