Skip to main content

Python library to interact with the Univention UDM REST API. Implements the simple Python UDM API.

Project description

Python UDM REST Client

Python 3.6+ GNU AGPL V3 license Code style: black Code coverage Documentation Status travisci

Python library to interact with the Univention UDM REST API, implements the interface of the Python UDM API.


  • Asynchronous
  • Automatic handling of HTTP(S) sessions
  • Type annotations
  • 100% test coverage (unittests + integration tests)
  • Python 3.6, 3.7, 3.8


The UDM context manager opens and closes a HTTP session:

>>> import asyncio
>>> from udm_rest_client.udm import UDM
>>> async def get_obj(mod_name, dn):
...     async with UDM(
...         "USERNAME",
...         "PASSWORD",
...         "https://FQDN.OF.UCS/univention/udm",
...         ssl_ca_cert="ucs-root-ca.crt"
...     ) as udm:
...         mod = udm.get(mod_name)
...         return await mod.get(dn)
>>> # Python 3.6:
>>> loop = asyncio.get_event_loop()
>>> obj = loop.run_until_complete(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
>>> # Python 3.7+:
>>> obj ="users/user", "uid=foo,cn=users,BASE-DN"))
>>> print(obj)
UdmObject('users/user', 'uid=foo,cn=users,BASE-DN')
>>> print(obj.props.username)

There are more examples in the docs usage section.

If the SSL CA certificate is not available verify_ssl=False can be used in place of ssl_ca_cert=.... Obviously that is not safe! The CA of any UCS server can always be downloaded from http://FQDN.OF.UCS/ucs-root-ca.crt.


  1. Install Python UDM REST Client via pip from PyPI:

    $ pip install udm-rest-client
  2. Install the OpenAPI client library used by the udm-rest-client. It is created by software from the OpenAPI Generator project. You need to either have a local Java installation (Java 8+) or run the projects Docker container. The process is scripted:

    $ update_openapi_client --generator docker ucs.master.fqdn.or.ip  # use Docker
    $ update_openapi_client --generator java ucs.master.fqdn.or.ip  # use Java

Use --insecure to ignore SSL verification errors. See --help for more options.

Use --username and --password to provide credentials if access to your openapi.json is protected. This is the default in newer versions of UCS and thus credentials are needed.

Important: Whenever a new UDM module is installed in the domain, it is necessary to rerun update_openapi_client. The new UDM module will otherwise not be available in the Python UDM REST Client. Very few apps (like UCS@school and Open-Xchange) install new UDM modules. New extended attributes do not require to rebuild the OpenAPI client library.


There are some isolated unittests, but most tests run against a real UDM REST API. A UCS Docker container is used for this. The Makefile automates downloading and starting the Docker container (1 GB) and running the tests.

Run tests with current Python interpreter:

$ make test

Using tox the tests can be executed with all supported Python versions:

$ make test-all

It is also possible to use an existing UCS server for the tests. Export UCS_HOST (the servers IP/FQDN), UCS_USERDN (the DN of an administrator account, usually uid=Administrator) and UCS_PASSWORD (the accounts password), before starting the tests:

$ export UCS_HOST="my.server.local"
$ export UCS_USERDN="uid=Administrator,cn=users,dc=domain,dc=local"
$ export UCS_PASSWORD="s3cr3t"
$ make test

Don’t forget to update the OpenAPI client library before running the test against a new server:

$ update_openapi_client --generator <docker|java> $UCS_HOST

To get the IP address of the UCS Docker container run:

$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' udm_rest_only


Standard logging is used for tracking the libraries activity. To capture the log messages for this project, subscribe to a logger named udm_rest_client.

The UDM REST API on the UCS server logs into the file /var/log/univention/directory-manager-rest.log.

Repo permissions

  • Github: @dansan and @JuergenBS
  • Gitlab: @JuergenBS
  • PyPI: @dansan and @SamuelYaron
  • RTD: @dansan and @SamuelYaron


This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.


0.4.0 (2020-04-06)

  • Add the possibility to provide credentials in the update_openapi_client script to download the schema file.

0.3.1 (2020-03-19)

  • Update download URL of openapi-generator jar.

0.3.0 (2020-03-18)

  • allow setting properties that only exist after enabling an option (Bug #50972)

0.2.1 (2019-12-14)

  • fix not detecting changes in mutable property values

0.2.0 (2019-12-10)

  • Mapping and Iterable interfaces were added to the object properties class. Adds item access (obj.props["key"]), obj.props.get("key"), len(obj.props), key in obj.props, obj.props.keys(), obj.props.values(), obj.props.items()
  • documentation improvements
  • HTTP basic passwords are no longer logged
  • map options and policies back to original values (were being rewritten to pep8 conform keys by the OpenAPI client)

0.1.1 (2019-11-25)

  • allow specifying existing JAR for open api client build
  • various small fixes to handle RTD and Travis-CI

0.1.0 (2019-11-22)

  • First release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for udm-rest-client, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size udm_rest_client-0.4.0-py2.py3-none-any.whl (30.1 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size udm-rest-client-0.4.0.tar.gz (47.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page