Integration with UCS/Attributes

From Univention Wiki

Jump to: navigation, search


In a UCS environment, LDAP is the single database for identity and infrastructure management.

LDAP is extensible in that one may add additional schema files and extend existing objects.

UCS supports this by having a mechanism to extend the user interface as well. The App Center utilizes this feature and gives App Providers an easy way to add custom attributes to objects that are useful for the App's functionality.

The easiest example would be a boolean attribute added to any user, whether or not s/he is allowed to use the App.

In fact, this use case is so common that the App Center supports exactly this with one checkbox in the App Provider Portal (Advanced / Add activation checkbox for App in UCS user management).

This is the result after the installation of the App:

Generic User Activation for one App

Extended Attributes

The whole feature in the App Center is based on Extended Attributes, a mechanism widely used in UCS. If you feel that the integration in the App Center is limited, you may try to use the raw feature: [1]

Adding your own attributes

Adding attributes is done by defining one text file in the "ini" file format. Currently, this file has to be uploaded directly to the Portal, see Provider_Portal/Apps#Commands. The filename extension is ".attributes"

Example:

[myappIsAdmin]
Description=User is an Admin
DescriptionDE=Benutzer ist Administrator
Syntax=Boolean

You can use multiple attributes and go even further with OIDs and object classes:

[myappIsAdmin]
OID=1.2.3.4.5.6.7.8.9.10.11.12.1
Description=User is an Admin
DescriptionDE=Benutzer ist Administrator
Syntax=Boolean
BelongsTo=myappUserClass

[myappSalutation]
OID=1.2.3.4.5.6.7.8.9.10.11.12.2
Description=Salutation for User
DescriptionDE=Begrüßung für den Benutzer
Syntax=String
Default=Hi,
BelongsTo=myappUserClass

[myappUserClass]
Type=ObjectClass
OID=1.2.3.4.5.6.7.8.9.10.11.12.3

Please do not use OIDs on your own, the App Center will generate them for you. But with OIDs and classes, one could migrate existing integration to App Attributes. (I.e., if your App existed in the App Center before this feature was introduced in UCS 4.1).

The same goes for some other fields that you may define. You are better off letting the App Center do most of the work and not use the advanced fields. Here is the complete list:

Name
This is not really a field, but he name of the section in the ini file. It is an internal name used for the CLI (e.g., udm users/user create ... --set myName=myValue)
OID
(advanced) A unique (world wide!!) identifier for the attribute. As Univention has its own namespace of OIDs, the App Center can generate unique OIDs automatically
Position
(advanced) The container, in which the Extended Attribute should be placed. There is a reasonable default.
Description
The description shown next to the widget in the UI
DescriptionDE
Same, but for German localization
LongDescription
The text shown in a tooltip in the UI
LongDescriptionDE
Same, but for German localization
Syntax
Currently, only Boolean, String and BooleanString (a string that shall represent a boolean...) are supported by default. (Using any known Syntax from the set of available Syntaxes in UCS does work, too, but is - again - advanced)
SingleValue
(advanced) Whether or not the attribute is SINGLE-VALUE in the LDAP schema
Default
The default for new objects
BelongsTo
(advanced) Useful if you need to add these attributes to certain LDAP classes. By default, an object class ${app}User is created
Module
(advanced) A list (comma separated) of UDM modules. By default, users/user is used, which makes the attribute available to all user objects

You can also further define the objectClass. This should not be needed unless you want finer grained control over the created schema file.

Type
Should be "ObjectClass"
OID
A unique (world wide!!) identifier for the object class. As Univention has its own namespace of OIDs, the App Center can generate unique OIDs automatically
Auxiliary
True or False, whether the class is AUXILIARY in LDAP
Sup
Base class for this ObjectClass, default to "top"
May
List of attributes this class may have
Must
List of attributes this class must have

How it works

Technically, the App Center compiles the .attributes file into a schema file. This file is saved in LDAP. On the DC Master, this triggers a mechanism which retrieves this file and saves it to the filesystem. The DC Master then includes this file in its slapd.conf and restarts the service.

After that Extended Attributes are generated form the .attributes file. (Extended Attribute is the name of the feature that Univention implemented to extend UCS' UI with custom attributes). These are saved in LDAP and read by UDM, the Univention Directory Manager at runtime. The attributes are available right after the creation of the Extended Attributes.

You may list them all on the DC Master with

udm settings/extended_attribute list

The schema file

You may ship a dedicated .schema file (just like the .attributes file). If this file is present, it is taken instead of the file that the App Center could have generated automatically. Again, this is an advanced feature that should not be used unless it is necessary.

Personal tools