3. Architecture#

The UCS Intercom Service 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 Node.js® running in the ICS container.

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

  • A Redis container to store OIDC sessions.

Note

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

Back end communication as referred to in the following section isn’t related to the Backchannel Logout path, which is a specific part of the OIDC protocol.

3.1. Design decisions#

The app UCS Intercom Service aims to provide a way to facilitate CORS conform communication to different back ends directly from the browser. It can proxy, modify, and authenticate requests and use Keycloak as IdP and its own session storage to hold OIDC sessions. It acquires those sessions through 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.

  1. The browser opens the intended app.

  2. The app contains ICS related JavaScript code as part of its responses.

  3. This code instructs the browser to send a requests to ICS, after the browser needs communication to a separate app.

  4. ICS acts as a middleware to modify and forward those requests appropriately to the relevant, second app using a back end communication channel.

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

For a visual representation, refer to Fig. 3.1.

The following list describes how this fits into the wider OIDC authentication scheme. See also Fig. 3.2.

  1. The browser starts unauthenticated at the login endpoint of an app that supports ICS, for example Matrix, Nextcloud, or OX App Suite.

  2. The browser follows the OIDC login procedure. The app redirects the browser to the IdP Keycloak and upon successful login assigns an OIDC session for the app to the browser.

  3. The browser requests an action, for example to create a video conference, as part of a calendar entry. The browser requests an interaction from OX App Suite to Matrix. In detail, the browser requests the Nordeck bot that runs in the Matrix user front end Element.

  4. A silent login happens in the background, that uses the information stored in the browser to authenticate ICS with the IdP Keycloak through a hidden IFrame.

  5. The functional interaction begins as displayed in Fig. 3.1.

  6. ICS sends a requests to the back end, usually another app on UCS. ICS acts as a middleware between the browser and back ends, for example apps.

Note

ICS may use shared secrets rather than relying on OIDC authentication when communicating with back ends.

Warning

Back end communication is only safe, if done through HTTPS or a secure network. Otherwise, attackers may eavesdrop secrets on application layer.

Abstract overview of ICS

Fig. 3.1 Interactions of ICS without OIDC#

Interactions of ICS with OIDC, OX App Suite and Nordeck

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

3.3. Portal navigation#

OX Univention-Portal Central Navigation Communication

Fig. 3.3 Communication overview for the Central Navigation capability, which requires cross app communication between OX App Suite and the UCS Portal.#

3.4. Filepicker#

OX Filepicker OIDC communication

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

3.5. Endpoints#

The app UCS Intercom Service offers the API endpoints listed below.

3.5.1. General#

/

Alive test only

/silent

Silent OIDC login endpoint

/backchannel-logout

Endpoint for OIDC backchannel logout requests

3.5.2. App specific#

/fs

Proxy for Nextcloud

/navigation.json

Proxy to Univention-portal for central navigation data

/nob

Proxy for the Nordeck bot. In a testing environment, developers can use this endpoint to requests to the plain Matrix UserInfo service.

3.6. Terms#

The document uses the terms that may not be clear to the reader. The following list provides context and explanation.

CORS#

CORS stands for Cross-Origin Resource Sharing and is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served.

For more information about CORS, refer to Wikipedia: Cross-origin resource sharing.

IdP#

stands for Identity Provider. An IdP offers user authentication as service. In the context of the app UCS Intercom Service the software Keycloak offers the IdP service to ICS and its app back ends.

OIDC audience#

The OIDC audience is a required claim within the ID Token for all OAuth 2.0 flows used by OIDC. According to the specification, it must contain the OAuth 2.0 client_id of the relying party as audience value.

For more information, see section ID Token in OpenID Connect Core 1.0 incorporating errata set 1 [3].