LDAP Listener

The LDAP listener for docker apps provides an interface for objects like users and groups. It enables apps to get notified about changes from the directory services and act upon them accordingly. The primary use case is to provision user accounts to your solution, for example by taking the input and sending out HTTP API calls. This article explains how the mechanism works and how it can be used for an app.

Requirements

1. The target UCS system needs to have at least version UCS 4.3-1 errataxxx. If your app needs this feature, you must set Supported UCS versions for App to 4.3-1 errataxxx. You can find this setting on the Software tab in the section Advanced software settings.
2. The software for the app has to be provided as docker image.

Setup in App configuration

In order to use the LDAP listener, you need to specify the objects needed and a script that the App Center calls inside the container. Upon app installation, the App Center copies the script into the container. You don't have to include the script in the container and you should therefore use your vanilla docker image. The settings need to be made on LDAP Listener tab in the provider portal.

1. In Object types that shall be watched for changes select either Users or Groups
2. Enter the script in the text field.

Please note that the script needs to be in an interpreted programming language. Choose the language you prefer, like Python, PHP, Perl, Bash, etc. If you want to implement the functionality in a compiled language liko Go oder Java, you need to specify a script anyway that simply calls your compiled program. The compiled program though needs to be present in the image.

How the mechanism works

For the explanation it is assumed that a UCS system with 100 users is running. As soon as your app is installed on a UCS system, the listener starts working and provides the requested data.

1. The App Center generates 100 files in JSON format and saves them in the directory /var/lib/univention-appcenter/apps/<your app's id>/data/listener/ in your app container. Each JSON file represents one object from the directory service.
2. A JSON file has the following schema:
   • entry_uuid: A unique identifier for an object. In contrast to "dn", it stays the same even after it is moved. The script certainly wants to identify objects by this attribute.
   • dn: The distinguished name of the LDAP object.
   • type: The type of the object, i.e., "users/user", or "groups/group", etc.
   • attributes: A dictionary of the attributes of this object. The content is defined by the UDM representation of the object. If it is null instead, the object got deleted.
3. A JSON file looks like the example below.
4. As soon as any attribute on any object changes, a new object is created or an existing one is deleted, the listener generates another JSON file and saves it to the directory in the container.
5. The script in the container is called in a defined and configurable interval by the App Center, if at least JSON file has been written. There may have been multiple changes in the Directory service since the last call which would result in multiple JSON files.

What should the script cover?

1. The listener does not filter the data. Every change will be saved in JSON files. If only a subset of users, e.g. a certain user type like students, shall be processed, the script should filter on it and only continue with the relevant data.
2. UCS can "resync" a listener. In this case, each and every object appears once again as a JSON file. As in the previous point, the script needs to cover the case where no real modification to the object has been made.
3. The script has to exit with exit code = 0 on success and != 0 on failure.
4. The script has to delete the JSON file that has been already processed. If the files are not deleted, the script should detect duplicates and make sure to handle the same change accordingly.
5. If a mapping between the entry_uuid of the JSON file and the primary user key in the solutions database is not possible, consider maintaining a mapping table by the script, if necessary. The entry_uuid is the only attribute that remains the same for an object.
6. It may happen that the same entry_uuid appears twice in the set of JSON files. This means that multiple modifications on the object have been made since the last time your script processed the object.

JSON example

{
    "dn": "uid=Administrator,cn=users,dc=sparka-43,dc=intranet", 
    "id": "b2f13544-e3cb-1037-810e-23ad4765aade", 
    "object": {
        "description": "Built-in account for administering the computer/domain", 
        "disabled": "0", 
        "displayName": "Administrator", 
        "gecos": "Administrator", 
        "gidNumber": "5000", 
        "groups": [
            "cn=Domain Admins,cn=groups,dc=sparka-43,dc=intranet", 
            "cn=Domain Users,cn=groups,dc=sparka-43,dc=intranet", 
            "cn=DC Backup Hosts,cn=groups,dc=sparka-43,dc=intranet", 
            "cn=Schema Admins,cn=groups,dc=sparka-43,dc=intranet", 
            "cn=Enterprise Admins,cn=groups,dc=sparka-43,dc=intranet", 
            "cn=Group Policy Creator Owners,cn=groups,dc=sparka-43,dc=intranet", 
            "cn=Administrators,cn=Builtin,dc=sparka-43,dc=intranet"
        ], 
        "lastname": "Administrator", 
        "locked": "0", 
        "lockedTime": "0", 
        "mailForwardCopyToSelf": "0", 
        "mailPrimaryAddress": "admin@sparka-43.intranet", 
        "mailUserQuota": "0", 
        "password": "{crypt}$6$0kS4GowCZEAJRqWG$8LkK6iBeKFCInoxy9bCG1SFfGpajOy//ZgBSuuMOs2MJcUQQAI2zgoU1/KcQ6e7Ldqz/oMPOdTdjTNCebDQpX.", 
        "passwordexpiry": null, 
        "primaryGroup": "cn=Domain Admins,cn=groups,dc=sparka-43,dc=intranet", 
        "sambaRID": "500", 
        "shell": "/bin/bash", 
        "uidNumber": "2002", 
        "umcProperty": [
            [
                "appcenterDockerSeen", 
                "true"
            ], 
            [
                "appcenterSeen", 
                "2"
            ], 
            [
                "udmUserGridView", 
                "default"
            ]
        ], 
        "unixhome": "/home/Administrator", 
        "unlockTime": "", 
        "userexpiry": null, 
        "username": "Administrator", 
        "webweaverActivated": "TRUE"
    }, 
    "udm_object_type": "users/user"
}