Architecture

4. Architecture#

The OX Connector app architecture consists of the following elements:

  • The operating environment UCS with the App Center and the Docker engine running OX Connector.

  • The OX Connector software inside a Docker image.

  • The OpenLDAP LDAP directory in UCS as identity management source for OX App Suite.

4.1. Overview#

The OX Connector app consists of a Docker image with all the software needed to provision user identities from UCS identity management to OX App Suite. The OX connector connects to the OX App Suite SOAP API and creates, updates, or deletes object entries in OX App Suite depending on what changed in the UCS LDAP directory with relevance to OX App Suite.

OX Connector app architecture

Fig. 4.1 OX Connector app architecture#

The diagram shows the LDAP directory, Provisioning Service, Provisioning API, OX Connector with the Provisioning Consumer, OX App Suite, and its SOAP API.

LDAP#

The OpenLDAP software provides the LDAP directory in UCS. The LDAP directory stores all identity and infrastructure data of the UCS domain. For more information, see LDAP directory in UCS 5.2 Manual [2].

Provisioning Service#

The Provisioning Service is a Nubus app that you install in the Nubus for UCS domain. It’s an event and messaging service that watches the LDAP directory for changes. When data changes on the Primary Directory Node, the Provisioning Service notifies subscribed services about the change.

In contrast to the Univention Directory Listener, it provides the UDM representation of the changed objects instead of the LDAP representation. The OX Connector app subscribes to the Provisioning Service through the Provisioning API for the UDM modules it provisions.

On a fresh install of the OX Connector, the Provisioning Service sends all existing UDM objects of the subscribed modules to the OX Connector (a prefill).

Provisioning API#

The Provisioning API runs on the Primary Directory Node and Backup Directory Nodes. It’s the API that applications use to subscribe to events of the Provisioning Service. The Provisioning Consumer of the OX Connector app subscribes through the Provisioning API for the UDM modules the connector provisions. You can access the Provisioning API locally through http://localhost:7777 or remotely through https://<primary FQDN>/univention/provisioning/.

OX Connector#

OX Connector connects the UCS identity management with OX App Suite. The connector receives data about changes in the LDAP directory. A Provisioning Consumer handles the data, processes it, and sends it to the SOAP API in OX App Suite.

Provisioning Consumer#

The Provisioning Consumer runs inside the Docker container of the OX Connector. It subscribes to the Provisioning API for the UDM modules the connector provisions. For every message it receives, it stores a task in its SQLite database and processes the tasks in a fixed module order, sending the data to the SOAP API.

OX App Suite#

OX App Suite is the groupware and collaboration software from Open-Xchange.

SOAP API#

OX App Suite uses SOAP as network protocol to receive data and run remote procedure calls. The connector uses the SOAP API to create, update, or delete object entries in OX App Suite.

4.2. How the connector works#

The OX Connector reacts on changes in the LDAP directory in UCS and relies on modules in the Univention Directory Manager (UDM) modules. UDM is a layer on top of the LDAP directory in UCS.

UCS provides the following UDM modules:

  • users/user

  • groups/group

The OX Connector provides the following UDM modules:

  • oxmail/oxcontext

  • oxresources/oxresources

  • oxmail/accessprofile

The OX Connector reacts on changes to the listed UDM modules and sends data to the SOAP API in OX App Suite.

4.2.1. Access profiles#

Upon changes in the UDM module oxmail/accessprofile, the connector rewrites the local file /var/lib/univention-appcenter/apps/ox-connector/data/ModuleAccessDefinitions.properties and doesn’t send data to the SOAP API in OX App Suite. The module handles the user rights and roles in OX App Suite. Administrators find the access profiles in UMC in the module LDAP directory at open-xchange ‣ accessprofile.

4.2.2. Provisioning#

In detail, the provisioning has the following steps, see Fig. 4.2:

  1. The Provisioning Service detects the change in the LDAP directory and sends a message with the UDM object through the Provisioning API.

  2. In the container, the Provisioning Consumer receives the message and stores it as a task in its SQLite database.

  3. The Provisioning Consumer processes the tasks in a fixed module order and sends the data of each task to the SOAP API in OX App Suite.

  4. After the SOAP API receives and processes the data successfully, the Provisioning Consumer stores the state of the object in its database of old entries, see Database of old entries.

provisioning procedure

Fig. 4.2 Provisioning procedure#

4.3. Provisioned attributes#

The OX Connector provisions a lot of attributes to OX App Suite. A detailed description is beyond the scope of this document.

The OX Connector comes with the source code. The user attributes for provisioning locate in the function update_user() in univention-ox-provisioning/univention/ox/provisioning/users.py inside the Docker container. To view the attributes, for example with vim, run the following command on the UCS system with OX Connector installed. Replace $version with the proper Python version used in the Connector:

Listing 4.1 Example for how to view the definition of provisioned attributes.#
$ univention-app shell ox-connector \
  cat /usr/lib/python"$version"/site-packages/univention/ox/provisioning/users.py \
  | vim -

Likewise, the attributes for groups, context, and resources locate in the respective source files in the update_*() function.

4.4. Database of old entries#

Added in version 3.0.0.

OX App Suite creates an internal ID for every user object it creates or updates. The OX Connector saves this internal ID in its own database, when it processed the objects without errors. The connector doesn’t store that ID in the UCS LDAP directory, but maintains a database in which it stores the data old object’s it processed for later reference (i.e., for retrieving the internal ID)

The OX Connector stores its database file at /var/lib/univention-appcenter/apps/ox-connector/data/ox-connector.db. The database contains a table named old. Use the command-line interface that the app provides to modify this database. For more information, see CLI to monitor the current state.

When the Provisioning Consumer updates groups in OX App Suite, the request to the SOAP API must include the internal ID of all group members. The connector would need to ask the database of OX App Suite for the internal ID of each group member, involving network requests and database queries. To speed up the processing, the OX Connector uses the internal ID from the database.

On this page