Configuration for UCS

4.1. Configuration for UCS#

Use this reference to configure the OX Connector app on Nubus for UCS. The app settings define how the connector reaches OX App Suite and how it provisions users, groups, shared accounts, and related features. The UCR variables describe UCS-specific values that affect the connector configuration.

4.1.1. App settings#

OX_SOAP_SERVER#

Defines the OX App Suite server. Provide the protocol and the fully qualified domain name (FQDN), for example https://ox-app-suite.example.com.

OX_SOAP_SERVER tells the OX Connector app in the container where to look for the OX App Suite system. The container must resolve the FQDN.

For secure HTTPS connections, the container needs to validate the certificate. If the OX App Suite instance uses a self-signed certificate or a certificate that the OX Connector container can’t validate, the container needs the root certificate for validation. For information about how to add self-signed certificates, see Import additional CA certificates on UCS.

Required

Type

Initial value

Yes

String

https://$hostname.$domainname
OX_IMAP_SERVER#

Defines the default IMAP server for new users, if not explicitly set on the user object.

Required

Type

Initial value

Yes

String

imap://$hostname.$domainname:143
OX_SMTP_SERVER#

Defines the SMTP server for new users, if not explicitly set on the user object.

Required

Type

Initial value

Yes

String

smtp://$hostname.$domainname:587
DEFAULT_CONTEXT#

Defines the default context for users. The OX Connector doesn’t create DEFAULT_CONTEXT automatically. Before the OX Connector provisions the first user, ensure that the default context exists.

To create a context, see Usage.

Required

Type

Initial value

Yes

Integer

10
OX_LANGUAGE#

Defines the default language for new users.

Required

Type

Initial value

Yes

String

de_DE
LOCAL_TIMEZONE#

Defines the default time zone for new users.

Required

Type

Initial value

Yes

String

Europe/Berlin
OX_MASTER_ADMIN#

Defines the username for the OX App Suite administrator account, also called the OX Admin user. This user can create, modify, and delete contexts. The user must already exist. The administrator defines the username for the OX Admin user during the installation of OX App Suite.

Required

Type

Initial value

Yes

String

oxadminmaster
OX_MASTER_PASSWORD#

Defines the password for the OX Admin user.

Required

Type

Initial value

No

Password

N/A
OX_IMAP_LOGIN#

Defines the value that OX App Suite uses to access the user’s inbox. If this value is empty, OX App Suite sets it to the user’s email address.

Required

Type

Initial value

No

String

N/A

If you use single sign-on (SSO), append an asterisk and the mail server master user to this variable. For Dovecot, set OX_IMAP_LOGIN to '{}*dovecotadmin'.

The OX Connector interprets the curly braces as a template. Empty braces use primaryMailAddress. To use another user attribute, enter the attribute name in the braces, for example {username}.

OX_FUNCTIONAL_ACCOUNT_LOGIN_TEMPLATE#

Defines the value that OX App Suite uses to access the functional account inbox. If this value is empty, the OX Connector sets it to a concatenation of the functional account LDAP entry UUID and the LDAP UID of the user.

This template can include the functional account entry UUID (fa_entry_uuid), the functional account email address (fa_email_address), and any Univention Directory Manager (UDM) property of the OX user, including the user’s entry_uuid and dn. Enclose every UDM property used in this template in {{ }}, for example {{fa_entry_uuid}}{{username}}. You can optionally separate multiple values with other text.

Required

Type

Initial value

No

String

N/A

If you use the OX App Suite app from Univention App Center, you can leave this app setting empty. An empty value is equivalent to {{fa_entry_uuid}}{{username}}.

If an existing OX Connector installation used only the functional account entry UUID, set this app setting to {{fa_entry_uuid}}.

Listing 4.1 shows valid template values.

Listing 4.1 Valid functional account login template values#
"{{fa_entry_uuid}}::{{entry_uuid}}"
"{{username}}+{{fa_entry_uuid}}+{{dn}}"
"{{fa_email_address}}*dovecotadmin"
{{fa_entry_uuid}}::{{entry_uuid}}

Concatenates the functional account entry UUID and the user UUID, separated by two colons.

{{username}}+{{fa_entry_uuid}}+{{dn}}

Concatenates the username, the functional account entry UUID, and the user DN, separated by plus signs.

{{fa_email_address}}*dovecotadmin

Concatenates the functional account email address and the string *dovecotadmin.

If you use single sign-on, append an asterisk and the mail server master user to this variable. For Dovecot, set OX_FUNCTIONAL_ACCOUNT_LOGIN_TEMPLATE to '{{fa_email_address}}*dovecotadmin'. Listing 4.2 shows the resulting login value for the functional account.

Listing 4.2 Resulting functional account login value with SSO#
myfunctional_account@maildomain.de*dovecotadmin
OX_USER_IDENTIFIER#

Defines the UDM user property that OX App Suite uses as the unique user identifier. If this app setting isn’t set, the OX Connector uses the username property by default.

For Nubus for Kubernetes, see openXchange.mappings.userIdentifier.

Required

Type

Initial value

No

String

N/A

Caution

Use only a mandatory UDM user property that contains one non-empty value. If you specify a UDM user property that contains an empty value or a list of values, the OX Connector enters an error state. To resolve the error, set a valid property.

OX_GROUP_IDENTIFIER#

Defines the UDM group property that OX App Suite uses as the unique group identifier. If this app setting isn’t set, the OX Connector uses the name property by default.

For Nubus for Kubernetes, see openXchange.mappings.groupIdentifier.

Required

Type

Initial value

No

String

N/A

Caution

Use only a mandatory UDM group property that contains one non-empty value. If you specify a UDM group property that contains an empty value or a list of values, the OX Connector enters an error state. To resolve the error, set a valid property.

OX_SHARED_ACCOUNT_IDENTIFIER#

Defines the UDM shared account property that OX App Suite uses as the unique shared account identifier. If this app setting isn’t set, the OX Connector uses the name property by default.

For Nubus for Kubernetes, see openXchange.mappings.sharedAccountIdentifier.

Required

Type

Initial value

No

String

N/A

Caution

Use only a mandatory UDM shared account property that contains one non-empty value. If you specify a UDM shared account property that contains an empty value or a list of values, the OX Connector enters an error state. To resolve the error, set a valid property.

OX_CONNECTOR_LOG_LEVEL#

Defines the log level for the OX Connector app. If this app setting isn’t set, the OX Connector uses INFO by default.

Required

Type

Initial value

No

String

INFO
OX_ENABLE_DEPUTY_PERMISSIONS#

Enables the provisioning of OX deputy permissions. Administrators can then set, modify, or delete deputy permissions for users in the Management UI.

For example, administrators can grant user01 the roles Viewer, Editor, and Author for the calendar and mail modules for user02. Also, user01 can send email on behalf of user02.

The default value is False. To enable the feature, set the app setting OX_ENABLE_DEPUTY_PERMISSIONS to True.

To show the feature in the Management UI, you must enable the UMC representation for the extended attribute after the app installation or after the configuration. Run the command in Listing 4.3 on the Primary Directory Node or a Backup Directory Node.

Listing 4.3 Activate the UMC representation of the enabled deputy permission feature.#
$ univention-directory-manager \
   settings/extended_attribute modify \
   --dn "cn=oxDeputyPermissionGivenTo,cn=open-xchange,cn=custom attributes,cn=univention,$(ucr get ldap/base)" \
   --set disableUDMWeb="0"

Required

Type

Initial value

No

Boolean

False

Important

The Deputy Permissions feature requires OX App Suite version 8 or later.

Users can modify their deputy permissions in OX App Suite. Provisioning through the OX Connector app in Nubus for UCS overwrites these settings.

See also

Deputy permissions: Technical Documentation

for more information about OX deputy permissions.

OX_CONNECTOR_STOP_ON_ERROR#

Changes how the OX Connector app handles synchronization errors. Set one of the following values:

True

Stop on any error. The app retries the failed action until it succeeds or an administrator resolves the error manually.

False

Continue with other queued actions. The app moves the failed action to the morgue. The failed action no longer interferes with the connector run, and an administrator can examine it later.

For information about managing provisioning tasks in Nubus for UCS, see Manage provisioning tasks.

Required

Type

Initial value

No

Boolean

True

4.1.2. UCR variables#

ox/context/id#

The app setting DEFAULT_CONTEXT sets the value of the UCR variable ox/context/id.

When you install the OX Connector app, it creates the extended attribute oxContext and uses the value from ox/context/id as the initial value for the extended attribute oxContext.

When an administrator creates a user account that the OX Connector app synchronizes, UDM sets the OX context for the user account to the value of the extended attribute oxContext.

Caution

The UCR variable ox/context/id isn’t for manual use.

Changing the variable doesn’t change the OX context on existing user accounts.

Changing the value of the app setting DEFAULT_CONTEXT changes neither ox/context/id nor the extended attribute oxContext.

4.1.3. User attribute mapping#

Since version 2.2.9, you can change the mapping between Open-Xchange and UDM properties. Use the change_attribute_mapping.py script from the app. The script creates a JSON file with the Open-Xchange property mapping and provisioning data.

Don’t modify the file manually. Use only the script. The script stores the JSON file at /var/lib/univention-appcenter/apps/ox-connector/data/AttributeMapping.json.

If the file doesn’t exist, the OX Connector app uses the default mapping. The default mapping comes from the following file inside the container of the app:

/usr/lib/python3.9/site-packages/univention/ox/provisioning/default_user_mapping.py.

The script supports these actions:

modify#

Performs operations that change the current mapping.

restore_default#

Restores the default mapping.

dump#

Writes the current JSON mapping to the console.

The modify action supports these options:

modify --set#

Changes the UDM property used to provision an Open-Xchange property. Listing 4.4 shows how to map the Open-Xchange property userfield01 to the UDM property description.

Listing 4.4 Set the mapping of an Open-Xchange property to a UDM property#
$ python3 /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py \
   modify \
   --set userfield01 description

You can use the modify --set argument multiple times in the same invocation. Listing 4.5 shows how to map multiple Open-Xchange properties to multiple UDM properties.

Listing 4.5 Set multiple Open-Xchange properties to multiple UDM properties#
$ python3 /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py \
   modify \
   --set userfield01 description \
   --set given_name custom_attribute
modify --unset#

Removes the Open-Xchange property from the mapping if the property isn’t marked as required. You can use this option to remove properties from synchronization.

Listing 4.6 Unset the OX property userfield01.#
$ python3 /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py \
   modify \
   --unset userfield01
modify --set_alternatives#

Sets alternative UDM properties for synchronization when the primary UDM property is None. Listing 4.7 shows how to set the example attributes CustomAttributeUserMail and CustomAttributeUserMail2 as alternatives to the Open-Xchange property email1.

Listing 4.7 Set example attributes as alternatives to an Open-Xchange property#
$ python3 /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py \
   modify \
   --set_alternatives email1 CustomAttributeUserMail CustomAttributeUserMail2
modify --unset_alternatives#

Removes the current alternatives for an OX property.

Listing 4.8 shows how to remove the alternative attributes for the OX property email1.

Listing 4.8 Unset the alternative attributes for the OX property email1#
$ python3 /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py \
   modify \
   --unset_alternatives email1

You can migrate an existing attribute mapping from the OX App Suite app in Univention App Center. To migrate the mapping, do the following:

  1. On the Nubus for UCS system that runs OX App Suite, run the command in Listing 4.9.

    Listing 4.9 Create the migration command for an existing attribute mapping#
    $ python3 <<EOF
from univention.config_registry import ConfigRegistry
ucr = ConfigRegistry()
ucr.load()

changed_mapping_single = {
  'displayname': 'display_name',
  'givenmame': 'given_name',
  'surname': 'sur_name',
  'categories': 'employee_type',
  'quota': 'max_quota',
  }

changed_mapping_multi = {
  'telephone_business': ['telephone_business1', 'telephone_business2'],
  'telephone_home': ['telephone_home1', 'telephone_home2'],
}


ucr_ldap2ox = ucr.get('ox/listener/user/ldap/attributes/mapping/ldap2ox', '').strip()
ucr_ldap2oxmulti = ucr.get('ox/listener/user/ldap/attributes/mapping/ldap2oxmulti', '').strip()
command = []
if ucr_ldap2ox:
  for entry in ucr_ldap2ox.split():
    value, key = entry.split(':', 1)
    if value is None:
      command.append(f"--unset {changed_mapping_single.get(key, key)}")
    else:
      command.append(f"--set {changed_mapping_single.get(key, key)} {value}")

if ucr_ldap2oxmulti:
  ldap2oxmulti = {}
  for entry in ucr_ldap2oxmulti.split():
    value, key = entry.split(':', 1)
    if value is None:
      for v in changed_mapping_multi.get(key, [key]):
        command.append(f"--unset {v}")
    else:
      for v in changed_mapping_multi.get(key, [key]):
        command.append(f"--set {v} {value}")

if command:
  print("Run the following command on the ox-connector server to update attribute mapping:")
  print("python3 /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py modify " + " ".join(command))
else:
  print("Nothing to do.")
EOF

  2. Copy the generated command from the output.

  3. On the Nubus for UCS system where the OX Connector app runs, run the generated command.

  4. Verify the migration result. Run the command in Listing 4.10 and check that the expected Open-Xchange properties map to the expected UDM properties.

    Listing 4.10 Verify the migrated attribute mapping#
    $ python3 \
   /var/lib/univention-appcenter/apps/ox-connector/data/resources/change_attribute_mapping.py \
   dump
On this page