Mit dem Beta-Release der REST API für den Univention Directory Manager (UDM) steht eine Vorab-Version der zukünftigen Standardschnittstelle für die Integration von Anwendungen mit dem Verzeichnisdienst von Univention zur Verfügung. Im Folgenden möchte ich Ihnen einen kurzen Überblick über die Ziele und Anwendungsfälle zum aktuellen Stand der API geben und Sie zum Testen animieren – wir freuen uns auf Ihr Feedback für weitere Verbesserungen für die finale Version!

Was ist die „UDM REST API“?

Eine „REST API“ (oder auch „RESTful API“) ist ein Webservice, über den eine Integration zwischen Anwendungen realisiert werden kann.
Über die REST API des Univention Directory Managers wird ein Zugriff auf alle Inhalte des Verzeichnisdienstes von Univention Corporate Server (UCS) ermöglicht. Sie ist damit in der Funktionalität vergleichbar mit den bereits vorhandenen und weiter bestehenden Skritping-Schnittstellen (z. B. dem „udm“ Kommandozeilen-Tool). Im Gegensatz zu diesen ist die API aber über das Netz per HTTPS erreichbar und über standardisierte Datenformate (JSON) einfacher in bestehenden Anwendungen integrierbar.

An wen richtet sich die „UDM REST API“?

Univention Directory Manager erlaubt den Zugriff auf die Inhalte des Verzeichnisdienstes und stellt dabei sicher, dass die Inhalte konsistent und standardkonform bleiben. Daher werden in UCS alle Veränderungen am Verzeichnisdienst nur über UDM durchgeführt.
Mit der REST API kann diese Schnittstelle jetzt vereinfacht von anderen Systemen bzw. anderer Software angesprochen werden. Wir möchten damit vor allem die Integration für beispielsweise folgende Einsatzszenarien erleichtern:

Betreiber von UCS Umgebungen: Integration mit bestehenden Systemen

Anwendungsfälle können die Pflege von Benutzereigenschaften durch Informationen aus HR-Systemen oder der Abgleich von Rechnerobjekten mit Inventarisierungslösungen sein. Betreiber einer IT-Infrastruktur können die REST API nutzen, um aus den anzubindenden Systemen heraus direkt lesend und schreibend auf UDM zuzugreifen.

Anbieter von Apps im Univention App Center: Integration der Apps

Hersteller von Software-Lösungen im Univention App Center können über die UDM REST API standardisiert auf den Verzeichnisdienst zugreifen. Dabei profitieren die Entwickler der jeweiligen Lösung von den standardisierten und von vielen Programmiersprachen unterstützten Datenmodellen genauso wie von dem Zugriff per HTTPS. Entwicklungen können direkt in der gewohnten Programmiersprache erfolgen, da keine Abhängigkeit zu den UDM Python-Schnittstellen mehr besteht.
Anwendungsfälle können die Abfrage von Informationen zum angemeldeten Benutzer oder auch Pflege von Inhalten des Verzeichnisdienstes aus den eigenen Anwendungen heraus sein.

Vereinfachungen innerhalb der UCS Produktentwicklung:

In der zukünftigen Weiterentwicklung von UCS wollen wir verstärkt auf die REST API anstelle der bisher auf jedem System ausgerollten Python Bibliotheken setzen. Wir versprechen uns damit einen Abbau von Risiken durch unterschiedliche Bibliotheksversionen in UCS-Umgebungen, sowie Vereinfachungen bei der Integration mit Software unterschiedlicher Programmiersprachen.


UCS Ambassador-Programm Anzeige

Wie kann die UDM REST API getestet werden?

Die REST API ist zur Installation auf dem DC Master oder einem DC Backup der UCS-Domäne vorgesehen. Für die Installation des Beta Release ist es noch notwendig, das „unmaintained“ Repository zu aktivieren. Nach Aktualisierung auf UCS 4.4-0 Errata 168 kann das Paket „univention-management-module-udm“ installiert und der gleichnamige Service neu gestartet werden:

ucr set repository/online/unmaintained=yes
univention-install univention-management-module-udm
service univention-management-module-udm restart

Danach ist die REST API unter folgenden URLs erreichbar:

  • API mit interaktivem Webinterface: https://<FQDN des Servers>/univention/udm/
  • Vereinfachter API-Zugriff und interaktive Beispiele per Swagger: https://<FQDN des Servers>/univention/udm/schema/

Zur Authentifikation an der REST API können alle LDAP Accounts verwendet werden, die Möglichkeiten richten sich auch hier nach den LDAP ACLs. Einen Vollzugriff auf alle Eigenschaften der Objekte im Verzeichnisdienst haben die Mitglieder der Gruppe „Domain Admins“.
Der folgende Screenshot zeigt einen Beispiel-Aufruf zum Auslesen des Benutzerobjekts des Administrator-Kontos, der aus der interaktiven Dokumentation per „Swagger“ stammt:

Der Aufbau der URLs orientiert sich an der Struktur der UDM-Module. Im gezeigten Beispiel ist das Modul „users/user“ für die Verwaltung von Benutzern Teil der URL. Zur Identifikation eines einzelnen LDAP-Objekts wird in unserem Beispiel die DN an das Ende der URL gestellt. Alternativ können Sie auch das Attribut entryUUID verwenden (URL ist dann „/univention/udm/object/<entryUUID>/“). Letztere URL hat den Vorteil, dass sie über die gesamte Lebensdauer eines Objektes unverändert bleibt. Wird keine DN angegeben, kann entweder nach Objekten gesucht werden („GET“), oder es können neue Objekte angelegt werden („POST“). Weitere Beispiele und Details der JSON-Datenstrukturen können Sie am einfachsten der interaktiven Dokumentation entnehmen.

Wie geht es bis zur finalen Version der REST API weiter?

Im nächsten Schritt würden wir uns wirklich sehr über Ihr Feedback zur Vorab-Version freuen. Was gefällt ihnen gut? Was können wir noch verbessern? Gibt es Anwendungsfälle, die mit der API noch nicht abgedeckt werden können?
Auf Basis dieses Feedbacks werden wir entscheiden, ob wir noch Änderungen an der API vornehmen werden und welche Erweiterungen für eine finale Version notwendig sind. Unser Ziel ist es, eine finale Version der REST API innerhalb des dritten Quartals 2019 zu veröffentlichen und auf allen UCS DC Master und DC Backup zu aktivieren.
Wir sind hier also auf Ihr Feedback angewiesen: Kommentieren sie gerne hier im Blog. Falls Sie konkretere Fragen haben oder gerne Unterstützung beim Testen haben möchten, schreiben Sie dies am besten auf unserem Forum help.univention.com.

Ingo Steuwer beschäftigt sich seit 1999 mit Linux und ist seit 2004 bei Univention. Als Head of Product Management liegt sein Fokus auf der Weiterentwicklung von UCS.

Was ist Ihre Meinung? Hinterlassen Sie einen Kommentar!

Kommentare

  1. Super! Eine API war schon lange überfällig. Anbindung an externe Systeme endlich „standardkonform“ möglich. Danke

  2. Update des Artikels: Für die Installation der Beta ist das Einbinden des „unmaintained“ Repositories notwendig.

    • Die Informationen sind mir zu dürftig.
      Wo ist die Dokumentation genau zu finden? Wie sehen Beispiele aus?
      Woher bekommt man das Basic – Auth – Token?
      Sind noch andere Authentifizierungsmechanismen geplant?
      Kann man Listen von den LDAP – Baumknoten abrufen?
      Es ergeben sich beim Test sicher noch mehr Fragen, sobald ich damit erstmal anfangen kann.

      • Danke für die Initiative zu testen!

        Ich versuche erste Antworten zu geben:
        > Wo ist die Dokumentation genau zu finden? Wie sehen Beispiele aus?

        Wie im Blogartikel beschrieben gibt es bisher eine interaktive Dokumentation inklusive Beispiele direkt durch die Rest API, die Links finden sich auch im obigen Blog-Artikel. Für das finale Release werden wir den Einstieg in unserer offiziellen Dokumentation beschreiben, führend wird aber weiter die interaktive Dokumentation sein: nur diese kann sich an die jeweiligen Anpassungen des Systems anpassen, z.B. durch neue Module und Attribute durch Nachinstallation von Apps.

        > Woher bekommt man das Basic – Auth – Token?
        > Sind noch andere Authentifizierungsmechanismen geplant?

        Bisher ist nur Authentifikation per HTTP Basic umgesetzt, die Credentials entsprechen denen eines LDAP Accounts (z.B. dem bei der Installation von UCS angelegtem „Administrator“ Konto oder jedem anderen Account in „Domain Admins“).

        > Kann man Listen von den LDAP – Baumknoten abrufen?

        Ich bin mir nicht sicher ob ich die Frage richtig verstehe. Das Suchen z.B. nach Containern oder Organisationseinheiten wird unterstützt.

        > Es ergeben sich beim Test sicher noch mehr Fragen, sobald ich damit erstmal anfangen kann.

        Für konkrete Fragen und Beispiele empfehle ich, einen Thread auf https://help.univention.com zu öffnen

  3. univention-management-module-udm zur Zeit nicht installierbar:

    hängt ab von python-mimeparse, python-concurrnet-futures
    nicht installierbar

    • Ist auf dem System wie nach dem Update dieses Artikels beschrieben das „unmaintained“ Repository eingebunden?

      ucr set repository/online/unmaintained=yes

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