Der Univention Directory Manager (UDM) ermöglicht den Zugriff auf die Inhalte im LDAP-Verzeichnisdienst, also z. B. das Betrachten, Verändern, Löschen und Verschieben von Objekten (Benutzer, Gruppen, Rechner, Drucker, Freigaben usw.). Der UDM lässt sich nicht nur über das Webinterface, sondern auch über die Kommandozeile steuern. Mit UCS 4.4-2 ist eine dritte Möglichkeit hinzugekommen: die REST API. Diese Schnittstelle verbindet Anwendungen per HTTPS mit dem UCS-Verzeichnisdienst und soll die Pflege von Benutzereigenschaften oder Rechnerobjekten der angebundenen Systeme erleichtern.
Dieser Artikel erklärt zunächst die technischen Hintergründe der REST API und die Implementierung in UCS.
Während der Implementierung der REST API fand ein reger Austausch mit den Entwicklern der EGroupware GmbH aus Kaiserslautern statt. Und so hat EGroupware als erste Lösung im Univention App Center die neue Schnittstelle eingesetzt. Im zweiten Teil des Artikels berichtet Ralf Becker von EGroupware von der Umstellung auf die neue API und erklärt, welche Vorteile diese für Hersteller von Drittanwendungen bereithält.

Was ist eine REST API?

Die Abkürzung REST steht für Representational State Transfer und API für Application Programming Interface. REST definiert einen Architekturstil, der die Grundidee des World Wide Web beherzigt und beschreibt, wie verteilte Dienste und Systeme miteinander kommunizieren können. Die grundlegenden Ideen hinter REST sind folgende:

  • Alle im Web befindlichen Informationen sind sogenannte Ressourcen, z. B. Benutzer in UCS.
  • Jede Ressource kann über einen eindeutigen URI (Uniform Resource Identifier) adressiert bzw. benannt werden (z. B. /univention/udm/users/user/uid=Administrator).
  • Der aktuelle oder ein gewünschter neuer Zustand einer Ressource wird über so genannte Repräsentationen im Netzwerk übertragen, z. B. eine HTTP-Nachricht. Die Repräsentationen sind explizit oder implizit als Cache-fähig oder nicht Cache-fähig markiert.
  • Repräsentationen bestehen aus Daten in einem MIME-Media-Format (z. B. text/html, application/hal+json, image/jpeg oder auch multipart/form-data) sowie Metadaten, die diese Daten beschreiben (z. B. MIME Media Type, Links, letzter Änderungszeitpunkt, Kontrolldaten, Caching-Informationen usw.).
  • Neben dem aktuellen Zustand der Ressource enthalten Repräsentationen alle momentan verfügbaren Interaktionsmöglichkeiten.

Ressourcen sind also durch Links und Beziehungstypen miteinander verbunden. So sähe der Programmcode beispielsweise aus, wenn ein Benutzer auf seine primäre Gruppe verlinkt:

<a href="/univention/udm/group/group/cn=Domain+Admins" rel="udm:users/user:primaryGroup">

Mögliche Zustandsveränderungen, wie etwa das Löschen, Bearbeiten oder Erstellen, sind über Formulare oder Links zu Formularen möglich. Hypermedia as the Engine of Application State (HATEOAS) ist der Motor der Anwendungen und enthält die Logik, die für die Zustandsveränderungen notwendig ist. Die Kommunikation ist zustandslos, das heißt, dass jede Nachricht ohne das Wissen einer vorherigen Nachricht verstanden werden kann.
Jede Nachricht beschreibt sich selbst, und es ist keine spezifische Client-seitige Logik oder eine Schnittstellendefinition erforderlich, lediglich standardisierte Protokolle und Datenformate. Auch eventuelle Zwischenschichten, wie Proxyserver, Gateways oder Caches, können die Nachrichten verstehen und erweitern bzw. verändern. Optional kann Programmcode wie z. B. JavaScript mitgeliefert werden, um die Client-Funktionalität zu erweitern.

Die UDM REST API

Die UDM REST-Schnittstelle ist ein in der Programmiersprache Python entwickelter Webdienst, der das asynchrone Tornado-Framework verwendet, um HTTP-Ressourcen für die UDM-Objekte bereitzustellen. Die Schnittstelle liefert die Inhalte des Verzeichnisdienstes im Format JSON HAL (Hypertext Application Language) aus. Außerdem steht für die Endpunkte eine OpenAPI-Schematisierung zur Verfügung. Ein Beispiel einer Schema-Definition für Objekte in der UDM REST API finden Sie auf unserer Demo-Instanz (User: Administrator, Passwort: univention). Unser Entwickler-Handbuch erklärt, wie Sie die Schnittstelle verwenden und welche Möglichkeiten diese im Detail bietet.
Die API richtet sich an Betreiber von UCS-Umgebungen, die bestehende Systeme integrieren möchten, beispielsweise zum Pflegen der Benutzereigenschaften durch Informationen aus HR-Systemen oder beim Abgleichen von Rechnerobjekten mit Inventarisierungs-Lösungen. Kurz gesagt: Die Schnittstelle ist für alle, die aus angebundenen Systemen heraus direkt lesend und schreibend auf UDM zugreifen möchten.
Auch Anbieter von Apps im Univention App Center profitieren von der REST API, weil sie den HTTPS-Zugriff auf den Verzeichnisdienst standardisiert. Da es keine Abhängigkeit mehr zur UDM-Python-Schnittstelle gibt, sind Entwickler nun nicht mehr an diese Programmiersprache gebunden, sondern können die Lösung in ihrer bevorzugten Sprache implementieren. Lesen Sie weiter, um zu erfahren, wie EGroupware die neue REST API zur Anbindung der eigenen Groupware-Lösung an UCS nutzt.


Lösungen für Teams zur Zusammenarbeit im Home Office bereit stellen

Remote Arbeit und die Zusammenarbeit mehrerer aus dem Home Office stellen besondere Anforderungen an die Arbeitsweise im Team und an die Werkzeuge, mit denen gearbeitet wird. Vorkonfigurierte virtuelle App Appliance können Sie mit einem sehr überschaubaren Einsatz in Betrieb nehmen und …  mehr erfahren


EGroupware und die REST API

egroupware logoWie erwähnt ist EGroupware die erste Lösung im Univention App Center, die die neue REST API nutzt; Vorgängerversionen setzten auf UDM. Die Umstellung ist im Zuge des Upgrades der EGroupware-App von Version 17.1 auf 19.1 passiert und wir wollen im Folgenden einen Blick hinter die Kulissen werfen.
Die EGroupware-App ist eine App, die sehr intensiv mit dem Verzeichnisdienst spricht. Anders als manch andere Anwendung nimmt sie nicht nur Daten entgegen, sondern erlaubt auch Änderungen am Verzeichnisdienst. Typische EGroupware-Benutzer bzw. -Administratoren verwalten die Benutzer und Gruppen in der Regel über die eigene Groupware-Lösung und nicht über UCS – was in der Vergangenheit schon mal zu Komplikationen geführt hat, insbesondere im Hinblick auf das Erzeugen und Ändern von Gruppen- oder Benutzerobjekten in LDAP.

Ein Container für alles

Die neue EGroupware-Version setzt außerdem auf Docker Compose, ein Werkzeug zum Erstellen, Ändern und Starten von mehreren Docker-Containern. Docker Compose löst damit die UCS AppBox ab, und der EGroupware-Docker-Container basiert auch nicht länger auf UCS. Der Container, der jetzt zum Einsatz kommt, ist kein speziell für UCS erzeugter. Stattdessen kann dank der REST API der Container benutzt werden, den EGroupware auch sonst überall verwendet – ein riesiger Vorteil, denn dieser Container durchläuft viel mehr Tests als ein reiner UCS-Container.
Erst die neue Schnittstelle hat das möglich gemacht, denn die Kommunikation zwischen Container und UCS-System läuft deutlich besser. Es ist jetzt möglich, in EGroupware einen neuen Benutzer anzulegen, diesem ein initiales Passwort zuzuweisen und ohne Umweg alle Einstellungen für Samba und Active Directory auf UCS-Ebene festzulegen.
Es gibt noch einen weiteren Vorteil für UCS-Administratoren: Der EGroupware-Container integriert sich besser ins System und kann alle UCS-Update-Mechanismen nutzen.

Auf gute Zusammenarbeit!

Der Austausch zwischen EGroupware– und Univention-Mitarbeitern war für beide Seiten fruchtbar. Als Hersteller einer Groupware-Lösung, die aus dem Univention App Center verfügbar ist, schätzen wir sehr, dass es Dialoge auf Augenhöhe gibt und bei Univention kompetente Ansprechpartner erreichbar sind. Es gibt einen persönlichen Kontakt anstelle einer Hotline oder eines Ticket-Systems. Als Entwickler bei Univention freuen wir uns im Gegenzug sehr über den Input von außen: Mit EGroupware hat ein fachkundiger Partner die neue REST API getestet und uns wertvolles Feedback geliefert, um die neue REST API noch besser zu machen.

UCS Core Edition jetzt kostenfrei einsetzen!

Zum Downloadbereich
Ralf Becker

Ralf Becker hat das Open-Source-Projekt EGroupware 2003 mit gegründet und ist seit vielen Jahren einer der Hauptentwickler.
In der 2016 gegründeten EGroupware GmbH ist er zuständig für Software-Entwicklung und Technik, sowie den Betrieb des Cloud-basierten SAAS Hosting von EGroupware.

Florian Best

Florian Best ist Open Source Software Engineer bei Univention und hauptsächlich in der Entwicklung von UMC sowie UCS@school tätig. Seine persönlichen Interessen liegen im Bereich HTTP, REST, Sicherheitstechnik und Python.

Was ist Ihre Meinung? Hinterlassen Sie einen Kommentar!

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert