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 http://forge.univention.org/svn/dev/branches/ucs-4.0/ucs-4.0-0/\
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 http://forge.univention.org/svn/dev/branches/ucs-4.0/ucs-4.0-0/\
/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:

# postint

#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 admin password by reading /etc/mysql.secret. A dependency on the package mysql-server is enough as we patch the Debian package.