Integration with UCS/LDAP
From Univention Wiki
In a UCS environment, LDAP is the single database for identity and infrastructure management.
Apps should use the LDAP database for tasks related to identity management, which often comes down to login (authentication and authorization). In this article, we focus on integration for Docker Apps.
Brief overview over the different server roles
UCS is a domain operating system. In easy or testing setups, this domain may consist of only one server. But in bigger companies, UCS may run many servers, potentially on multiple sites of the company. We distinguish four roles, UCS can take:
- Domaincontroller Master: The first and most important server. It hold the definitive copy of the LDAP database. Every UCS domain has exactly one DC Master.
- Domaincontroller Backup: A backup server that holds an exact copy of the DC Master's LDAP. Should the DC Master go down (as in "meltdown", not "temporary downtime"), a Backup may take its place permanently.
- Domaincontroller Slave: A server with a read-only copy of the LDAP. It may be used for "load balancing", as services may ask the local read-only LDAP instead of having to go against the DC Master. DC Slaves may be used in each location should a company have multiple. Note that in advanced settings (such as UCS@school), DC Slaves may only have access to a certain portion of the database.
- Memberserver: A normal server with no own LDAP database. They are used to run specific services (such as Apps).
The Domaincontroller Master is always the first server of a domain. More servers may "join" the domain.
App Providers should go against the LDAP server configured for the server the App is installed on. Docker Apps get the following environment variables to connect to LDAP:
- LDAP_SERVER_NAME: FQDN of the server the App may connect to
- LDAP_SERVER_IP: The IP address
- LDAP_SERVER_PORT: ... and the port
- LDAP_SERVER_ADDITION: Should the server above drop out, this list of servers may be asked instead
- LDAP_BASE: The base for the whole LDAP database, e.g., dc=mydomain,dc=intranet
- You should always use the LDAP_BASE for an LDAP query. While many environments save their users below cn=users,$LDAP_BASE, this does not hold for all environments. LDAP is fast enough to make such a restriction unnecessary.
- $LDAP_BASE is dc=...,dc=intranet by default (i.e. the name is suggested in the initial system setup). But the name can be chosen freely, e.g. o=mydomain,o=com.
When a Docker App is installed, a user account is created specifically for this container. The account has read access to the important parts of the LDAP directory. The username is passed as the environment variable LDAP_BASEDN. The password is written in the file /etc/machine.secret.
The credentials are not changed when a container is upgraded. But they change if an App is installed, uninstalled and installed again.
For Non-Docker Apps, LDAP integration possible, too, of course. The LDAP variables are not available as Environment variables, though, but instead are stored in the Univention Config Registry (UCR). You can access them via the command line:
ucr get ldap/server/name
The UCR keys are:
- $(cat /etc/machine.secret)
You may consider narrowing down the users that may use the App.
There are many ways to authorize users for Apps. One example would be creating a group and consider every user an App user that is a member of that group. In UCS, it is common to add one extra attribute to the user object: A checkbox that reads "Activate user for $APP_NAME".
This is easy when following the Integration with UCS/Attributes article. After that, a filter like this could be added to the LDAP settings of the App: