1. Administration#
1.1. Admin overview#
Simplified overview of the ID Connector#
The ID Connector replication system is composed of four components:
An LDAP server containing user data.
A process on the data source UCS server, receiving user creation/modification/deletion events from the LDAP server and relaying them to multiple recipients via HTTP, called the ID Connector Service.
A process on the data source UCS server to monitor and configure the UCS@school ID Connector service, called the ID Connector HTTP API.
Multiple recipients of the directory data relayed by the ID Connector Service. They run an HTTP-API service, that the ID Connector Service pushes updates to.
1.2. Admin prerequisites#
This administration chapter is useful when you need to administer an ID Connector setup, or you need to integrate ID Connector. To follow this text, you should be familiar with the following aspects of the UCS environment:
- LDAP and LDAP listener#
LDAP is used because it is optimized for reading in a hierarchical structure. It shouldn’t be accessed directly, instead UDM should be used. OpenLDAP can have plugins, notifier being one of them that is heavily used in UCS. Upon changes in the LDAP directory, the notifier triggers listeners locally and on remote systems.
The listener service connects to all local or remote notifiers in the domain. The listener, when notified, calls listener modules, which are scripts (in shell and python)
You need to be able to:
understand the basic concepts of LDAP
See also
See LDAP directory service in UCS Manual [1].
- Univention Directory Manager#
Univention Directory Manager (UDM) is used for handling user data (and other data) that is stored in the LDAP server, one of two core storage places (the other one is UCR). Examples for data are users, roles or machine info. UDM adds a layer of functionality and logic on top of LDAP, hence LDAP shouldn’t be used directly, but only through UDM.
You need to be able to:
understand the concept of UDM
know the basic structure of UDM objects and their attributes
add and manage extended attributes
See also
See Univention Directory Manager (UDM) in Univention Developer Reference [2].
- Univention Configuration Registry#
The Univention Configuration Registry (UCR) stores configuration variables and settings to run the system, and creates and changes actual Linux configuration files as configured by these variables upon setting said variables.
You need to be able to:
understand basic UCR concepts
set and read UCR variables.
See also
See Administration of local system configuration with Univention Configuration Registry in UCS Manual [1].
- Univention App Center settings#
The Univention App Center is an ecosystem similar to the app stores known from mobile platforms like Apple or Google. It provides an infrastructure to build, deploy and run enterprise applications on Univention Corporate Server (UCS). The Univention App Center uses well-known technologies like Docker.
Within the app center, you can configure settings for the individual apps.
See also
App settings in Univention App Center for App Providers [3]
Setting of an application in the App Center in UCS Manual [1]
- UCS@school basics#
Schools have special requirements for managing what is going on inside them (teachers, students, staff, computer rooms, exams, etc.), and for managing the relation between multiple schools, their operator organizations (“Schulbetreiber”), and possibly ministerial departments above them.
There are several components used within UCS@school, Kelvin (see below) being one of them.
You need to be able to:
know about UCS@school objects
know the difference between UCS@school-objects and UDM objects
- UCS@school Kelvin REST API#
The UCS@school Kelvin REST API (Kelvin) provides HTTP endpoints to create and manage individual UCS@school domain objects like school users, school classes and schools (OUs). It is written in FastAPI, hence in Python 3.
You need to be able to install and configure Kelvin.
See also
UCS@school-Objekte im LDAP-Verzeichnisdienst in UCS@school - Handbuch für Administratoren [5]
If you want to also develop for the ID Connector, please also see the next chapter Development.
1.3. Installation#
1.3.1. Sending system#
The app is available in the Univention App Center. You can install it with:
$ univention-app install ucsschool-id-connector
This runs the join script 50ucsschool-id-connector.inst
, which creates:
the file
/var/lib/univention-appcenter/apps/ucsschool-id-connector/conf/tokens.secret
containing the key with which JWT tokens are signed.the group
ucsschool-id-connector-admins
(with DNcn=ucsschool-id-connector-admins,cn=groups,$ldap_base
) who’s members are allowed to access the ID Connector HTTP-API.
Use of both is explained later on in Authentication
Note
You can check the existence of the group with:
$ udm groups/group list --filter cn=ucsschool-id-connector-admins
Note
Join scripts are registered in LDAP and then executed on any UCS system either before/during/after the join process.
If the above didn’t get created, run:
$ univention-run-join-scripts --run-scripts --force 50ucsschool-id-connector.inst
This forces the (re-)running of the join script.
1.3.2. Receiving system#
In order for the ID Connector app to be able to create/modify/delete users on the target systems an HTTP-API is required on the target system. Currently only the Kelvin API is supported.
Note
This only makes sense if the sender and target systems are in different domains, because in the same domain, users and groups already get synced using other UCS mechanisms.
Install the Kelvin API on each target system:
$ univention-app install ucsschool-kelvin-rest-api
To allow the ID Connector app on the sender system to access the Kelvin-API on the receiving system, it needs an authorized user account. By default, the Administrator account on the receiving system is the only authorized user. To add a dedicated Kelvin API user for the UCS@school ID Connector consult UCS@school Kelvin REST API documentation [4] on how to do that.
1.4. Configuration#
Now that everything is installed, let’s configure the setups. We configure the receiving system first, because we need auth credentials used on the receiving system later on the sending system.
1.4.1. Configure receiving system - HTTP-API (Kelvin)#
You need to install and configure the Kelvin API. This is documented in UCS@school Kelvin REST API documentation [4].
We assume that you have a current version of Kelvin installed after reading the documentation.
Note
For the authorization of the UCS@school ID Connector at the target system
it needs credentials with special privileges.
Create a user with the name and password of your choice and add him to the group
ucsschool-kelvin-rest-api-admins
.
$ udm users/user create --position "cn=users,$(ucr get ldap/base)" \
--set username=USERNAME-OF-YOUR-CHOICE --set lastname=Kelvin --set firstname=UCS \
--set password="PASSWORD-OF-YOUR-CHOICE"
$ udm groups/group modify --dn "cn=ucsschool-kelvin-rest-api-admins,cn=groups,$(ucr get ldap/base)" \
--append users="uid=USERNAME-OF-YOUR-CHOICE,cn=users,$(ucr get ldap/base)"
Note down the credentials, they are needed for the school authority configuration on the sending system further down.
WARNING: the password is now in the command history. You might want to delete this using e.g:
$ history -d -2
After installation and basic configuration you might want to configure mapped UDM properties.
Beyond the standard object properties in UCS@school you can define additional UDM properties that should be available in the Kelvin API on the target system.
For this you would define a configuration in /etc/ucsschool/kelvin/mapped_udm_properties.json
, e.g.:
{
"user": ["title", "phone", "e-mail"],
"school": ["description"]
}
This would make the listed properties available for the user
and school
resources.
Kelvin needs to be restarted after changes to its configuration:
$ univention-app restart ucsschool-kelvin-rest-api
Note
When configuring Kelvin in detail, remember that the password hashes for LDAP and Kerberos authentication are collectively transmitted in one JSON object to one target attribute. This means it’s all or nothing: all hashes are synced, even if empty. You can’t select individual hashes.
Note
Please make sure that you configure all the mapped properties that the sending system sends, e.g.
displayName
. If the sender sends more than the receiver is configured to process,
you will end up with unexpected errors, e.g. 404
in the log.
1.4.2. Configure sending system#
The school authorities configuration must be done through the ID Connector HTTP API. Do not edit configuration files directly.
UCS@school ID Connector HTTP API#
The HTTP-API of the ID Connector app offers three resources:
queues: monitoring of queues
school_authorities: configuration of school authorities
school_to_authority_mapping: configuration of which school we sync to which authority
You can discover the API interactively using one of two web interfaces. They can be visited with a browser at their respective URLs:
Swagger UI:
https://FQDN/ucsschool-id-connector/api/v1/docs
ReDoc:
https://FQDN/ucsschool-id-connector/api/v1/redoc
The Swagger UI page is especially helpful as it allows sending queries directly from the browser.
The equivalent curl
command lines are then displayed.
An OpenAPI v3 (formerly “Swagger”) schema
can be downloaded from https://FQDN/ucsschool-id-connector/api/v1/openapi.json
Authentication#
Only members of the group ucsschool-id-connector-admins
are allowed to access the HTTP-API.
The user Administrator
is automatically added to this group for testing purposes.
In production, only the regular admin user accounts should be used.
You can authorize yourself in e.g. the Swagger UI using the Authorize
button.
To use the ID Connector HTTP API from a script, a JSON Web Token (JWT)
must be retrieved from https://FQDN/ucsschool-id-connector/api/token
.
The token will be valid for a configurable amount of time (default 60 minutes),
after which it must be renewed.
To change the TTL of the token, open the corresponding app settings in the Univention App Center.
Example curl
command to retrieve a token:
$ curl -i -k -X POST --data 'username=Administrator&password=s3cr3t' \
https://FQDN/ucsschool-id-connector/api/token
Role specific attribute mapping#
Note
This is an advanced scenario. If you don’t need this, jump to the next section.
Back to our example about telephone numbers. Imagine that while telephone numbers should not be transferred for students, they are actually needed for teachers. This means, that we have a need to define per role which properties should be transferred.
With version 2.1.0
role specific attribute mapping was added to the default Kelvin plugin.
This allows to define additional user mappings for each role (student
, teacher
, staff
and school_admin
)
by adding a new mapping next to the users
mapping suffixed by _$ROLE
,
e.g. users_student: {}
.
If a user object is handled by the Kelvin plugin, the mapping is determined as follows:
Determine the schools the current school authority is configured to handle.
Determine all roles the user has in these schools.
Order the roles by priority:
school_admin
being the highest, followed bystaff
,teacher
and thenstudent
.Find a
users_$ROLE
mapping from the ones configured in the plugin settings, pick the one with the highest priority (from step 3).If none was found, fall back to the
users
mapping as the default.
An example for such a configuration can be found in Role specific Kelvin plugin mapping
Note
The priority order for the roles was chosen in order of common specificity in UCS@school.
A student only ever has the role student
.
But teachers, staff and school admins can have multiple roles.
Note
The mappings for the different roles are not additive because that approach would complicate the option to remove mappings from a specific role. Therefore, only one mapping is chosen by the rules just described.
Warning
Users have the field school_classes
, which describes which school classes they belong to.
You might want to prevent certain user roles from being added or removed to school classes.
Please be aware that leaving out the school_classes
from the mapping is not sufficient to achieve this:
changing the school classes of a user does not only result in a user change event
but also a school class change event, which needs to be handled separately. You therefore need to use
a derivative of the Kelvin plugin, which is described in the next section.
Partial group sync mapping#
Note
This is an advanced scenario. If you don’t need this, jump to the next section.
Remember that in the last examples we had a property that we would send for some users, but not others, depending on their role? Turns out that we can have the same problem for groups.
Imagine that a school manages locally which teachers belong to which class.
In the role specific mapping we would not sync the classes attribute school_classes
,
preventing overwriting the local managed settings (see above).
This is not enough though: we would also need to make sure that we don’t sync
the property users
of groups which contains those teachers.
With version 2.1.0
a new derivative of the Kelvin plugin was added:
kelvin-partial-group-sync
. This plugin alters the handling of school class changes
by allowing you to specify a list of roles that should be ignored when syncing groups.
The following steps determine which members are sent to a school authority
when a school class is added:
Add all users that are members of the school class locally (Normal Kelvin plugin behavior).
Remove all users that have a configured role to ignore in any school handled by the school authority configuration.
Get all members of the school class on the target system that have one of the configured roles and add them.
Get all members of the school class on the target system that are unknown to the ID Connector and add them.
This results in school classes having only members with roles not configured to ignore,
members with roles to ignore that were added on the target system,
any users added on the target system which are unknown to the ID Connector.
Warning
To achieve this behavior, several additional LDAP queries on the ID Connector and one additional request to the target system are necessary. This affects performance.
To activate this alternative behavior replace the kelvin
plugin in a school authority configuration
with kelvin-partial-group-sync
.
The configuration options are exactly the same as for the kelvin
plugin,
except for the addition of school_classes_ignore_roles
,
which holds the list of user roles to ignore for school class changes.
See Partial group sync for an example configuration.
Warning
Please be aware that this plugin can only alter the handling of dedicated school class change events.
Due to the technical situation, changing the members of a school class often results in two events,
a school class change and a user change.
To actually prevent users of certain roles being added to school classes at all,
it is necessary to leave out the mapping of the users school_class
field
in the configuration as well - see above.
1.5. Trying it out#
Time has come to try it out. What we want to do:
Create a test user
Import the test user on the sending side
and watch the user being synced to the receiving side.
The slow way would be to create a user individually (and make sure to amend the required properties), or to use the UCS@school import. You can read all about importing users in UCS@school - Handbuch zur CLI-Import Schnittstelle [6] (German only).
We however do it the fast way, creating and importing the user in one step:
$ /usr/share/ucs-school-import/scripts/ucs-school-testuser-import \
--students 1 --classes 1 DEMOSCHOOL
This will create a user within a class in the school DEMOSCHOOL
.
Now watch the log file to see the sync action on the sender system:
$ tail -f /var/log/univention/ucsschool-id-connector/queues.log
In another terminal on the receiving system you can see the user being received by the Kelvin API:
$ tail -f /var/log/univention/ucsschool-kelvin-rest-api/http.log # kelvin log
You might need to wait a short moment before the queue picks up the new user. If everything went fine,
you should see some messages in the kelvin log, and you can confirm that the user was created in
either the Kelvin web interface at https://FQDN/ucsschool/kelvin/v1/docs
or in the UMC.
These log files are also a good starting point for debugging in case something went wrong.
Hint
When debugging always make sure that the following is correct and matches:
school authority configuration on the sender system (including auth credentials)
school to authority mapping on the sender system
mapped_udm_properties.json
on the receiving system has all extra attributes that are defined in the school authority mapping.
Good luck! :-)
1.6. Starting / Stopping services#
Both services (ID Connector Service and ID Connector HTTP API) run in a Docker container. The container can be started/stopped by using the regular service facility of the host system:
$ univention-app start ucsschool-id-connector
$ univention-app status ucsschool-id-connector
$ univention-app stop ucsschool-id-connector
$ univention-app restart ucsschool-id-connector
To restart individual services, the init scripts inside the Docker container can be used.
The univention-app
program has a command that makes it easy to execute commands inside
the Docker container:
# UCS@School ID Connector service
$ univention-app shell ucsschool-id-connector /etc/init.d/ucsschool-id-connector restart
# UCS@School ID Connector HTTP API
$ univention-app shell ucsschool-id-connector /etc/init.d/ucsschool-id-connector-rest-api start
1.7. Updates#
Updates are installed in one of the two usual UCS ways. Either via UMC or on the command line:
$ univention-upgrade
# or just:
$ univention-app upgrade ucsschool-id-connector