Sometimes software can use LDAP, but does not use the user accounts directly but is restricted to one specific user who then is used for further user authentication. This LDAP bind can be done by creating a app specific user in UDM. This should be done in a Join script via

ldap_base="$(ucr get ldap/base)"
APP='myapp'
PASSWORD='secret'
touch "/etc/$APP.secret"
chown root:root "/etc/$APP.secret" # or so
chmod 600 "/etc/$APP.secret"
printf '%s' "$PASSWORD" > "/etc/$APP.secret"
udm users/user create "$@" --position "cn=users,$ldap_base" \
	--set username="$APP-user" --set lastname="$APP-user" \
	--set password="$PASSWORD" --option ldap_pwd || die

Now you can configure your software accordingly. Here the DN will be uid=$APP-user,cn=users,$ldap_base.

If more access is needed, it is also possible to use the machine account of the UCS system. Every computer joined into the UCS domain has certain permissions. Computers in cn=dc,cn=computers,$ldap_base (by default DC Master, DC Backup, DC Slave) can even access the (hashed) password attributes of users and computers. The password for the machine account is stored in /etc/machine.secret (readable by root). The machine DN can be found by

ucr get ldap/hostdn

The machine password rotates. This means the password changes over time. If your software needs to adapt, you may install a script (with executable bit set!) at /usr/lib/univention-server/server_password_change.d/xx$app with xx being two digits for ordering purposes with something like the following content:

#!/bin/sh
case "$1" in
prechange)
	# nothing to do before the password is changed
	exit 0
	;;
nochange)
	# nothing to do after a failed password change
	exit 0
	;;
postchange)
	# do something with /etc/machine.secret, e.g.
	cp /etc/machine.secret /etc/$app.secret
	# restart daemon after password was changed
	invoke-rc.d $app restart
	;;
esac

The data regarding identity and infrastructure management is saved in LDAP. Apps that are not LDAP-aware can use this data nonetheless by registering handlers that trigger when certain data is changed (e.g. a user is created, the IP of a computer is changed). This may be useful if

More details can be found in the Developer Reference.

A short example how to sync first name, last name, email of a user to a (theoretical) third-party database. This script is run every time a user is added, removed or any of these attributes change. As the email is unique (forced by UCS) and all three attributes are only single-valued (also forced by UCS), this may come down to:

name = "app_sync_users"
description = "always be in sync with UCS users"
filter = "(&(uid=*)(!(uid=*$))"
attributes = ["givenName", "sn", "mailPrimaryAddress"]

def handler(dn, new, old):
	if new and not old:
		add_user(new)
	elif not new and old:
		remove_user(old)
	elif new and old:
		modify_user(new, old)

def add_user(new):
	new_mailPrimaryAddress = new.get('mailPrimaryAddress', [''])[0]
	new_givenName = new.get('givenName', [''])[0]
	new_sn = new.get('sn', [''])[0]
	get_db_connection().add(new_givenName, new_sn, new_mailPrimaryAddress)

def remove_user(old):
	old_mailPrimaryAddress = old.get('mailPrimaryAddress', [''])[0]
	get_db_connection().remove(old_mailPrimaryAddress)

def modify_user(new, old):
	old_mailPrimaryAddress = old.get('mailPrimaryAddress', [''])[0]
	new_mailPrimaryAddress = new.get('mailPrimaryAddress', [''])[0]
	new_givenName = new.get('givenName', [''])[0]
	new_sn = new.get('sn', [''])[0]
	get_db_connection().modify(old_mailPrimaryAddress, new_givenName,
		new_sn, new_mailPrimaryAddress)

def get_db_connection():
	raise NotImplementedError()

The form for creating LDAP objects can be customized by apps. Technically this is done by writing special objects into LDAP. As such, customization is generally done in a join script. The objects are created with the Univention Directory Manager (UDM).

This example creates a checkbox in the users' form's tab "Advanced settings". This makes it possible to save whether the user should be allowed to use the app. The value has to be queried by the app afterwards.

APP="myapp"
SERVICE="My App"
# for more details, see
#   https://docs.software-univention.de/developer-reference.html#udm:ea
# "$@" is here because this should go into a join script and there
# passing the arguments of the script invocation to udm is necessary
udm settings/extended_attribute create "$@" \
	--ignore_exists \
	--position "cn=$APP,cn=custom attributes,cn=univention,$ldap_base" \
	--set module="users/user" `# extending users` \
	--set ldapMapping="${APP}Enabled" `# LDAP attribute from the schema` \
	--set objectClass="${APP}-user" \
	--set name="$APP-enabled" `# this is the name for UDM` \
	--set shortDescription="Allow $SERVICE" \
	--set longDescription="Whether this user shall be allowed ..." \
	--set translationShortDescription="\"de_DE\" \"$SERVICE erlauben\"" \
	--set translationLongDescription="\"de_DE\" \"Zeigt an, ob ...\"" \
	--set tabName="$SERVICE" `# This may create a new tab in the form` \
	--set translationTabName="\"de_DE\" \"$SERVICE\"" \
	--set tabAdvanced='0' \
	--set tabPosition='1' \
	--set syntax='TrueFalseUp' `# should be a CheckBox` \
	--set mayChange='1' \
	--set default='TRUE' || die

Note the

--set syntax='TrueFalseUp'

which semantically turns this attribute into a boolean field. Other syntax definitions exist, for example string or ipAddress. More examples can be found in the following file /usr/share/pyshared/univention/admin/syntax.py.

It is also possible to create own drop downs. The following example adds a combo box with two options "Admin" or "User"

udm settings/extended_attribute create "$@" \
	--ignore_exists \
	--position "cn=$APP,cn=custom attributes,cn=univention,$ldap_base" \
	--set module="users/user" \
	--set ldapMapping="${APP}Role" \
	--set objectClass="${APP}-user" \
	--set name="$APP-role" \
	--set shortDescription="Role in $SERVICE" \
	--set longDescription="Which role the user has for $SERVICE" \
	--set translationShortDescription="\"de_DE\" \"$SERVICE-Rolle\"" \
	--set translationLongDescription="\"de_DE\" \"Welche Rolle ...\"" \
	--set tabName="$SERVICE" \
	--set translationTabName="\"de_DE\" \"$SERVICE\"" \
	--set tabAdvanced='1' \
	--set tabPosition='1' \
	--set syntax="${APP}UserOrAdmin" \
	--set mayChange='1' \
	--set default='user' || die

The syntax is a Python class and needs to be defined in a separate file:

class myappUserOrAdmin(select):
	choices=[('user', 'User'), ('admin', 'Admin')]

This file needs to be registered in a join script:

ucs_registerLDAPExtension "$@" \
	--udm_syntax "/usr/share/$APP/${APP}_syntax.py"

The Extended Attributes are generally stored in LDAP as attributes not defined by default. A schema file needs to be created and registered for the Extended Attributes to actually work. See this section for details of how to write a schema file.

The example above needs a file like this:

attributetype ( 1.3.6.1.4.1.10176.99998.xxx.1.1 NAME 'myapp-enabled'
	DESC 'My App allowed'
	EQUALITY caseIgnoreMatch
	SUBSTR caseIgnoreSubstringsMatch
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE
	)
attributetype ( 1.3.6.1.4.1.10176.99998.xxx.1.2 NAME 'myapp-role'
	DESC 'My App role'
	EQUALITY caseIgnoreMatch
	SUBSTR caseIgnoreSubstringsMatch
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE
	)
objectclass ( 1.3.6.1.4.1.10176.99998.xxx.0.1 NAME 'myapp-user'
	DESC 'My App user'
	SUP top AUXILIARY
	MUST ( cn )
	MAY ( myapp-enabled $ myapp-role )
	)

Note the "xxx" in the so called OIDs. You need a unique (worldwide!) identifier for your attributes and object classes. Either request one or (probably better) talk to us, as Univention has its own namespace and any schema extension can be defined "beneath" it.

This file needs to be registered in a join script:

ucs_registerLDAPExtension "$@" --schema "/usr/share/$APP/$APP.schema"

The Univention Directory Manager (UDM) is a collection of modules written in Python to add powerful capabilities around Python's LDAP bindings. In general, vendors will extend those existing modules using Extended Attributes. But if a completely new class of object shall be saved, a new UDM module may be useful, e.g., if the app manages buildings which cannot be simply "extended groups or containers".

When writing a UDM module, it is best to look out for existing modules that can be copied and customized for one's own needs. They live in /usr/share/pyshared/univention/admin/handlers/. The module appcenter/app.py is a rather simple module which shows how a basic module should look like:

svn co https://forge.univention.org/svn/dev/branches/ucs-4.1/ucs-4.1-4/\
management/univention-management-console-module-appcenter/\
udm/handlers/appcenter/

The Univention Management Console (UMC) is the web based frontend which is used to administrate the UCS domain. It consists of separate modules and vendors may write such modules to further extend the Console. This may be a good idea if

Note that many UCS users are used to UMC and the fact that everything can be configured in one place. So adding a UMC module may greatly enhance the user experience.

UMC modules are very versatile (both the JavaScript based frontend part as well as the Python backend part) and can be used for nearly anything. This guide cannot cover everything there is about UMC modules. One starting point may be

univention-install univention-management-console-dev
umc-create-module --help

Or you use UMC and look out for modules that to some extend do what you are trying to accomplish and copy the source code, e.g.

svn co https://forge.univention.org/svn/dev/branches/ucs-4.1/ucs-4.1-4/\
/management/univention-management-console-module-top

In the default setting, all incoming ports are blocked by the UCS firewall. Every package can provide rules, which free up the ports required. In this example the port 6644 is opened for TCP and UDP. It can be run in the postinst script or in the join script:

# configure firewall
univention-config-registry set \
	security/packetfilter/package/"$APP"/tcp/6644/all="ACCEPT" \
	security/packetfilter/package/"$APP"/tcp/6644/all/en="$APP" \
	security/packetfilter/package/"$APP"/udp/6644/all="ACCEPT" \
	security/packetfilter/package/"$APP"/udp/6644/all/en="$APP"
[ -x "/etc/init.d/univention-firewall" ] &&
	invoke-rc.d univention-firewall restart

UCS comes with a running Apache HTTP Server used by the UMC server as a proxy. This means that apps cannot use port 80/443 easily: It is already used. Apps can use Apache, though, by shipping a file /etc/apache2/sites-available/$APP. Apache can then act as a proxy to the app's server (running on a different port).

# minimal
ProxyPass /$APP/ http://127.0.0.1:$APP_PORT/
ProxyPassReverse /$APP/ http://127.0.0.1:$APP_PORT/

The site needs to be enabled by a line in the postinst of the package:

a2ensite "$APP"

It is highly recommended to use Apache for it is the service with port 80/443. While it is possible to just let the app respond to requests on port say, 8080, many firewalls will block the app without taking further actions. One prominent example are the default security rules of the Amazon Web Services. The app may not be accessible without using Apache as a proxy!

The start page of any UCS system (http://$hostname/) lists available services on this server, notably UMC. If an app provides a web interface, this can be listed, too. The easiest way is by stating this in the ini file:

WebInterface=/$APP/
#WebInterfaceName=... # defaults to Name=
# one of the two categories in /ucs-overview.
#   "services" (default) or "admin"
#UCSOverviewCategory=services

If WebInterface is given in the ini, the App Center takes care of the integration on the overview site. But sometimes this is not powerful enough. This level of "automated integration" cannot handle ports other than 80/443 (as it will always use the current port which is 80 or 443) and cannot add more than one link. If a deeper level is required, this should be done in the postinst and postrm scripts of the integration package using UCR:

# postinst

#DEBHELPER#

# ucs/web/overview/entries/service/... or
# ucs/web/overview/entries/admin/...

export P="ucs/web/overview/entries/service"
ucr set \
	"$P/$APP"/description/de="Description of link to $APP (German)" \
	"$P/$APP"/description="Description of link to $APP (English)" \
	"$P/$APP"/icon="/url/to/icon/$APP.png" \
	"$P/$APP"/label/de="Headline of link to $APP (German)" \
	"$P/$APP"/label="Headline of link to $APP (English)" \
	"$P/$APP"/link="https://$hostname.$domainname:$APP_PORT/webinterface/" \
	"$P/$APP"/priority=xx-digits-for-sorting-or-just-dont-set

# postrm

#DEBHELPER#

ucr unset \
	ucs/web/overview/entries/service/"$APP"/description/de \
	ucs/web/overview/entries/service/"$APP"/description \
	ucs/web/overview/entries/service/"$APP"/icon \
	ucs/web/overview/entries/service/"$APP"/label/de \
	ucs/web/overview/entries/service/"$APP"/label \
	ucs/web/overview/entries/service/"$APP"/link \
	ucs/web/overview/entries/service/"$APP"/priority

When your application uses PostgreSQL, your package should depend on univention-postgres and you need to ship a file in /etc/postgresql/9.1/main/pg_hba.conf.d/ or, maybe even better, in /etc/univention/templates/files/etc/postgresql/9.1/main/pg_hba.conf.d/ (see UCR):

local $app_db_name $app_db_user md5

When your application uses MySQL, you may access the administrator password by reading /etc/mysql.secret. A dependency on the package mysql-server is enough as we patch the Debian package.

You need a running UCS 4.1 system (master domain controller for the sake of convenience). As Radicale will be installed from the UCS repository, not from the App Center and Radicale is unmaintained by Univention, you need to activate the unmaintained repository:

ucr set repository/online/unmaintained='yes'

Also, make sure your system has the following packages installed: univention-appcenter, univention-appcenter-docker, univention-appcenter-dev

After this has been done, run

univention-app dev-setup-local-appcenter

An App consists of the actual packages and meta information about the App. The App may ship one or more screenshots, various README files and so on. But every App has to have an ini file.

Create a file ~/radicale.ini (name it as you like...) and put the very first content in it:

[Application]
# Can be chosen arbitrarily but after it has been chosen,
# needs to stay the same in each version
ID=radicale
# Code is necessary, but given by Univention. Normally, you do not
# need to specify it
Code=RD
Name=Radicale

The version will be set to that of the repository:

Version=0.7

Radicale is developed by Kozea, we are "only" doing the integration work. If you develop the software and do the integration, you only need the first two lines:

Vendor=Kozea
WebsiteVendor=http://kozea.fr/
Maintainer=Univention
WebsiteMaintainer=http://www.univention.de/

Radicale can be used to manage shared calendars, so this makes it a Collaboration App:

Categories=Collaboration

Now the important parts: The Debian package that is to be installed is called radicale. It will live in a repository created for this App on the App Center server. The package is unmaintained by Univention, so it needs to be copied from the unmaintained repository to the App's repository (this is done later).

DefaultPackages=radicale

It shall be installed as a Docker App, so the following needs to be specified:

DockerImage=docker.software-univention.de/ucs-appbox-amd64:4.1-0

This means that the package is not installed on your system but rather in a Docker Container running on your system. To access the relevant bits of the container (i.e. the calendars and contacts), you need to forward the port (which happens to be 5232 for Radicale):

PortsExclusive=5232
# You could also use PortsRedirection=1234:5232

Together, this makes:

[Application]
ID=radicale
Code=RD
Name=Radicale

Version=0.7

Vendor=Kozea
WebsiteVendor=http://kozea.fr/
Maintainer=Univention
WebsiteMaintainer=http://www.univention.de/

Categories=Collaboration

DefaultPackages=radicale

DockerImage=docker.software-univention.de/ucs-appbox-amd64:4.1-0

PortsExclusive=5232

Finally, put the ini file into the (local) App Center (do not forget to upload the Debian packages - here this means two unmaintained packages already built):

univention-app dev-populate-appcenter --new \
	--ini ~/radicale.ini \
	--unmaintained radicale python-radicale

Radicale should already be installable. Alas, it will not work. This is due to the way Radicale is packaged in Debian. To make it work as expected, we need to modify it. Here starts the integration work of the App.

First of all, Radicale is not started by default. To change that, we need to modify /etc/default/radicale and uncomment #ENABLE_RADICALE. The Univention App Center supports various scripts that can be added to the App and will be executed at various points in time. Maybe the most important one is the join script.

#!/bin/sh

VERSION=1

. /usr/share/univention-appcenter/joinscripthelper.sh

joinscript_init

eval "$(ucr shell ldap/base)"

joinscript_run_in_container sed -i /etc/default/radicale -e "s/#ENABLE_RADICALE/ENABLE_RADICALE/" || die

joinscript_save_current_version

exit 0

univention-app dev-populate-appcenter --new \
	--ini ~/radicale.ini \
	--join ~/radicale.inst \
	--unmaintained radicale python-radicale

univention-app dev-populate-appcenter --new

univention-app dev-populate-appcenter \
	--component radicale_20150929 \
	--join ~/radicale.inst

#!/bin/sh

/usr/share/univention-docker-container-mode/restore_data_after_setup \
	"$@"

cp -r /var/lib/radicale/collections \
	/var/lib/appcenter/app/radicale/data/

exit 0

#!/bin/sh

/usr/share/univention-docker-container-mode/restore_data_after_setup \
	"$@"

rm -r /var/lib/radicale/collections
cp -r /var/lib/appcenter/app/radicale/data/collections \
	/var/lib/radicale/

exit 0

DockerScriptStoreData=/usr/share/univention-appcenter/app/radicale/store_data
DockerScriptRestoreDataAfterSetup=/usr/share/univention-appcenter/app/radicale/restore_data

univention-app dev-populate-appcenter --new \
	--ini ~/radicale.ini \
	--join ~/radicale.inst \
	--store-data ~/radicale.store_data \
	--restore-data-after-setup ~/radicale.restore_data \
	--unmaintained radicale python-radicale

The App should be in a functional state now.

univention-app install radicale

should give you a running CalDAV/CardDAV service at port 5232 on your Docker Host.

The configuration of the service is not optimal, though. Every user, even an anonymous user can create and change any calender and contact. We want to limit the access to domain users. And they should only be able to change their own calendars. Note that Radicale provides mechanisms for even finer grained control. This is not scope of this example, though.

[radicale/rights/type]
Description[de]=Rechtevergabe für Kalender, Kontakte
Description[en]=Access control for calendars, contacts
Type=list
Labels[de]="Alle lesen, eigene schreiben" "Alle lesen, alle schreiben"
Labels[en]="Read all, write own" "Read all, write all"
Values=owner_write authenticated
Default=owner_write
Categories=apps

#!/bin/sh

VERSION=1

. /usr/share/univention-appcenter/joinscripthelper.sh
. /usr/share/univention-lib/all.sh

joinscript_init

eval "$(ucr shell ldap/base)"

ucs_addServiceToLocalhost "${SERVICE}" "$@"

joinscript_add_simple_app_system_user "$@"

cat > "$(joinscript_container_file_touch /etc/univention/templates/files/var/lib/radicale/.config/radicale/config)" <<- EOF
@%@UCRWARNING=#@%@

[rights]
type = @%@radicale/rights/type@%@

[auth]
# Access method
# Value: None | htpasswd | LDAP | PAM | courier
type = LDAP

# Usernames used for public collections, separated by a comma
#public_users = public
# Usernames used for private collections, separated by a comma
#private_users = private

# Htpasswd filename
#htpasswd_filename = /etc/radicale/users
# Htpasswd encryption method
# Value: plain | sha1 | crypt
#htpasswd_encryption = crypt

# LDAP server URL, with protocol and port
ldap_url = ldap://@%@ldap/server/name@%@:@%@ldap/server/port@%@/
# LDAP base path
ldap_base = @%@ldap/base@%@
# LDAP login attribute
#ldap_attribute = uid
# LDAP filter string
# placed as X in a query of the form (&(...)X)
# example: (objectCategory=Person)(objectClass=User)(memberOf=cn=calenderusers,ou=users,dc=example,dc=org)
# leave empty if no additional filter is needed
#ldap_filter =
# LDAP dn for initial login, used if LDAP server does not allow anonymous searches
# Leave empty if searches are anonymous
ldap_binddn = uid=radicale-systemuser,cn=users,@%@ldap/base@%@
# LDAP password for initial login, used with ldap_binddn
@!@
#ldap_password =
print 'ldap_password = %s' % open('/etc/radicale.secret').read()
@!@
# LDAP scope of the search
ldap_scope = SubTree

# PAM group user should be member of
#pam_group_membership =

# Path to the Courier Authdaemon socket
#courier_socket =
EOF

cat > "$(joinscript_container_file /etc/univention/templates/info/univention-radicale.info)" <<- EOF
Type: file
File: var/lib/radicale/.config/radicale/config
Variables: radicale/.*
Variables: ldap/base
Variables: ldap/server/port
Variables: ldap/server/name
EOF

joinscript_run_in_container ucr update
joinscript_run_in_container ucr commit /var/lib/radicale/.config/radicale/config

joinscript_run_in_container sed -i /etc/default/radicale -e "s/#ENABLE_RADICALE/ENABLE_RADICALE/" || die
joinscript_run_in_container invoke-rc.d radicale restart

joinscript_save_current_version

exit 0

#!/bin/sh

VERSION=1

. /usr/share/univention-appcenter/joinscripthelper.sh
. /usr/share/univention-lib/all.sh

joinscript_init

ucs_removeServiceFromLocalhost "${SERVICE}" "$@"

joinscript_remove_script_from_status_file radicale

exit 0

univention-app dev-populate-appcenter --new \
	--ini ~/radicale.ini \
	--join ~/radicale.inst \
	--unjoin ~/radicale.uinst \
	--store-data ~/radicale.store_data \
	--restore-data-after-setup ~/radicale.restore_data \
	--ucr ~/radicale.ucr \
	--unmaintained radicale python-radicale

univention-app install radicale

univention-app configure radicale \
	--set radicale/rights/type=authenticated
univention-app restart radicale

For every App, the App Center server holds a repository containing the Debian packages. But it also may hold several scripts that do not need to be packaged. In theory one may integrate one's App without needing to build an additional integration package. That being said, with increasing complexity, it is advised to build such a package nonetheless. Furthermore, not everything can be achieved easily with these scripts. There are interfaces rarely used that the App Center does not support. Should your App require these interfaces, it may be necessary to create a package.

We need to distinguish between outer scripts and inner scripts. An outer script is called on the Docker Host, inner scripts are called in the running Docker Container.

All scripts are called with root privileges. For inner scripts this means the local root of the Docker Container. Some scripts may get LDAP credentials. Normally these credentials are that of the Administrator account.

The following scripts are for installation and uninstallation. Upgrades use these scripts, too, if (and only if) the upgrade includes an image exchange (i.e. the new version with the new ini file specifies a different DockerImage). In that case the old App is uninstalled and the new App is installed.

The following scripts are for upgrading the software within the Docker Container. Three possible scenarios have to be covered:

We used some of the ini's variables to adjust the Docker App to our needs. Here is a brief overview regarding all Docker related variables:

Please refer to the Developer Reference for a template and the description of every attribute in the ini file.