3. Architecture#

The ICS app architecture consists of the following elements:

  • The operating environment UCS with the App Center and the Docker engine running the ICS-Container.

  • The ICS software based on nodejs running in the ICS-Container.

  • The Keycloak Identity Access Management, which is used by ICS to authenticate sessions and obtain login tokens for applications.

  • A Redis container to store OIDC sessions.

  • The following sections may refer to the browser rather than to the client to avoid confusion with OIDC clients configured in Keycloak.

  • Backend communication as referred to in the following section is not related to Backchannel Logout, which is a specific OIDC protocol.

3.1. Design decisions#

The ICS app aims to provide a simple way to facilitate CORS-conform communication to different backends directly from the browser. It can proxy, modify and authenticate requests and use Keycloak and its own sessions storage to hold OIDC session. It can acquire those sessions via a silent background login, provided a valid OIDC cookie is already available in the browser.

3.2. Overview#

Starting from the basics, ignoring everything related to login, authentication and sessions for now, this is how ICS works on a basic level.

  • The browser opens the intended app normally.

  • The app contains ICS related (JavaScript-)code as part of it’s normal responses.

  • This code will instruct the browser to send a requests to ICS, once communication to a separate app is required.

  • The ICS then acts as a middleware to modify and forward those requests appropriately to the relevant, second app using a backend communication channel.

  • ICS receives the response back and finally sends an appropriately modified response back to the browser.

Refer to Fig. 3.1 for a visual representation.

Let’s consider how this fits into the wider OIDC authentication scheme. (see Fig. 3.2)

  • The browser starts unauthenticated at the login endpoint of an ICS supporting app.

  • The browser follows the OIDC login procedure, getting redirected to Keycloak and, assuming successful login, causing the App and by extension the browser to be assigned an OIDC session.

  • The browser requests an action, for example creating a video conference, as part of a calendar entry. This means an interaction from OX to Element (more specifically the Nordeck-bot running in Element) is requested.

  • A silent login happens in the background. This silent login uses the information stored in the browser to authentication the ICS with Keycloak via a hidden iframe.

  • The actual functional interaction begins, displayed in Fig. 3.1.

  • A requests to the correct backend (usually another Univention-app) is sent.

  • ICS acts as a middleware between the browser and the backend (app)

Note

ICS may use shared secrets rather than relying on OIDC authentication when communicating with app-backends.

Warning

Backend communication is only safe if done via HTTPS or a secured network. Secrets may be exchanged on Application-Layer.

ICS Abstract Overview

Fig. 3.1 Interactions of ICS without OIDC#

OX Univention-Portal Central Navigation Communication

Fig. 3.2 Interactions of ICS with OIDC, OX and Nordeck#

3.3. Portal Navigation#

OX Univention-Portal Central Navigation Communication

Fig. 3.3 Communication overview for the Central Navigation functionality, which requires cross-app communication between OX and the Univention-portal.#

3.4. Filepicker#

OX Filepicker OIDC Communication

Fig. 3.4 Communication overview for the Filepicker functionality, which requires cross-app communication between OX and Nextcloud.#

3.5. General#

/#

Alive test only

/silent#

Silent (OIDC) login endpoint

/backchannel-logout#

Endpoint for OIDC backchannel logout requests

3.6. App-Specific#

/fs#

Proxy for Nextcloud

/navigation.json#

Proxy to Univention-portal for central navigation data

/nob#

Proxy for the Nordeck-bot. This endpoint may also be used to send requests to the plain Matrix UserInfo-service in a testing environment.