How a UCS@school user should look like

twenzel · July 17, 2020, 12:22pm

The differences between UCS users and UCS@school users

Users, who are created with the UMC module Users (school) automatically receive a number of groups and roles. When creating users via UDM command or the UMC module users, one can easily miss one of these essential features, which might lead to errors. Thus, the safest way to create new users is by the school module or via the UCS@school import.

To illustrate missing groups and attributes, this article compares the UDM attributes of common UCS users and UCS@school users. The goal is to understand how school users differ in their groups and roles from normal users, as well as how to detect broken users. A similar german article has been published here.

In UCS@school 4.4 v8 users are now validated before usage, when loading them from LDAP and errors will be logged to the regular log files (cf. manual).
In UCS@school 4.4 v9 the diagnostic module UCS@school Consistency Check is introduced. It checks, amongst other things, if existing users are consistent. If this diagnostic module displays errors, this does not necessarily mean that the UCS@school system is not working. Rather, it warns of objects that do not look the way UCS@school expects and that could cause future problems when using them.

School membership

Every school user must be a member of at least one school (OU). When a school user is removed from its last school, it is deleted.

One of the user’s schools must be the OU below which the users LDAP object is located (see section Position in LDAP tree below).
For each school the user is a member of, it must:
2.1 be member of a few groups (see section Group membership below),
2.2 the schools (OUs) name must be listed in the users schools attribute,
2.3 there must be (at least) one entry in the ucsschoolRole attribute (see section Role attribute below)

Group membership

As mentioned earlier, school users have to be placed inside the special school groups. A user created via UDM or the UMC module users, will only be placed in

  groups: cn=Domain Users,cn=groups,$ldap_base

Let’s compare the group against the groups of a valid UCS@school student:

Every school user is in a $ROLE-$SCHOOL group (with $ROLE being schueler, lehrer, mitarbeiter or school_admin).
All members of a school (OU) must be in the Domain Users $SCHOOL group
Students are usually part of at least one school class. Staff members and teachers do not have to be assigned to a class. The OU a class belongs to, must be listed in the users schools attribute.

  groups: cn=schueler-$SCHOOL,cn=groups,ou=$SCHOOL,$ldap_base
  groups: cn=Domain Users $SCHOOL,cn=groups,ou=$SCHOOL,$ldap_base
  groups: cn=$SCHOOL-Democlass,cn=klassen,cn=schueler,cn=groups,ou=$SCHOOL,$ldap_base

School admins, who are usually teachers or staff members, need the group

  groups: cn=admins-$SCHOOL,cn=ouadmins,cn=groups,$ldap_base

For detailed information about the special group types work group and school classes please see this article.

Position in LDAP tree

UCS@school users will be placed at position cn=$ROLE,cn=users,ou=$SCHOOL,$ldap_base, instead of cn=users,$ldap_base.

staff: cn=mitarbeiter,cn=users,ou=$SCHOOL,$ldap_base
student: cn=schueler,cn=users,ou=$SCHOOL,$ldap_base
teacher: cn=lehrer,cn=users,ou=$SCHOOL,$ldap_base
staff and teacher: cn=lehrer und mitarbeiter,ou=$SCHOOL,$ldap_base
school-admin: cn=admins,ou=$SCHOOL,$ldap_base - only if they’re created as admin only

To use the position of objects in LDAP to identify their role is deprecated, try to avoid relying on it. Nevertheless - until further notice - the above positions should be used when creating new users!

Role attribute

UCS@school users have the attribute ucsschoolRole, which is used internally. It is composed as follows:

$ROLE:school:$SCHOOL

Staff users have an attribute ucsschoolRole: staff:school:$SCHOOL
Students have an attribute ucsschoolRole: student:school:$SCHOOL
Teachers have an attribute ucsschoolRole: teacher:school:$SCHOOL
School Administrators have an attribute ucsschoolRole: school_admin:school:$SCHOOL

There will be one entry per role and school of the user.

Currently a user must not hold 2 different roles at the same time. UCS@school is still in the migration process of using the new roles, but there are still places where the objectClasses are used to determine the user’s role. While the ucsschoolRole attribute is able to assign a role to a specific school, the corresponding objectClass does not have this feature. So according to objectClasses a user cannot be teacher at one school and school admin at another school (see also the warning at the section UDM options / LDAP objectClasses).

UCS@school users also have the attributes departmentNumber and school which both hold the short form of the school name. Try to avoid relying on them, as they are deprecated.

Required attributes

The firstname and lastname attributes must be set for a school user.

Import related attributes

When using the UCS@school import, the attributes ucsschoolRecordUID and ucsschoolSourceUID are set as well. Users, which are created by UMC leave the values unset as well as ucsschoolPurgeTimestamp.
UCS@school users also have an additional e-mail attribute, which holds the same value as mailPrimaryAddress.

UDM options / LDAP objectClasses

Last but not least, at least one of the following options has to be activated:

UCS@school-Administrator
UCS@school-Klassenarbeitsbenutzer
UCS@school-Lehrer
UCS@school-Mitarbeiter
UCS@school-Schüler

This can be done by adding --append-option=ucsschoolStudent to the UDM command or by activating the checkbox in the Users (school) module.

The UDM options are saved as objectClass in the LDAP objects:

administrator: ucsschoolAdministrator
exam user: ucsschoolExam
staff: ucsschoolStaff
student: ucsschoolStudent
teacher: ucsschoolTeacher
staff and teacher: both ucsschoolStaff and ucsschoolTeacher

Please note, that it is not possible to assign the objectClasss/UDM options to specific schools in case of inter-school users. Activated UDM options are always effective at all of the user’s schools (see also the warnings at the section Role attribute).

A sample command

Putting everything together, this command creates a valid UCS@school user via UDM:

udm users/user create \
	--position 'cn=schueler,cn=users,ou=DEMOSCHOOL,'$(ucr get ldap/base) \
	--set firstname='Demo' \
	--set lastname='Student' \
	--set username='demo_student2' \
	--set password='secret123' \
	--set displayName='Demo Student' \
	--append groups='cn=schueler-demoschool,cn=groups,ou=DEMOSCHOOL,'$(ucr get ldap/base) \
	--append groups='cn=Domain Users DEMOSCHOOL,cn=groups,ou=DEMOSCHOOL,'$(ucr get ldap/base) \
	--append groups='cn=DEMOSCHOOL-Democlass,cn=klassen,cn=schueler,cn=groups,ou=DEMOSCHOOL,'$(ucr get ldap/base) \
	--set primaryGroup='cn=Domain Users DEMOSCHOOL,cn=groups,ou=DEMOSCHOOL,'$(ucr get ldap/base) \
	--append school=DEMOSCHOOL \
	--append ucsschoolRole=student:school:DEMOSCHOOL \
	--append-option=ucsschoolStudent

For every school the user is a member of, there must be additional groups, school and ucsschoolRole entries.

To fix groups or attributes, use the udm users/user modify command to modify the broken user object.

twenzel · July 17, 2020, 12:22pm

twenzel · July 21, 2020, 11:37am