LDAP

LDAP in TIM Flow

The LDAP integration in TIM Flow covers two functions that can be used independently or together:

Synchronisation — Groups and users are imported from the LDAP directory into TIM Flow on a schedule. The system keeps the group and user structure up to date automatically, including names, email addresses, departments, and other attributes.
Authentication — When a user logs in, their credentials are verified directly against the LDAP server rather than against a local password stored in TIM Flow.

Both functions share the same server connection configuration but are activated and managed separately. It is possible, for example, to use synchronisation without enabling LDAP authentication, or to enable LDAP authentication for a tenant without running synchronisation.

ATTENTION! These settings and methods should only be applied with caution.

Basic server configuration

In order to enable the system to connect to an LDAP server, the following file must be configured:

jboss\standalone\configuration\tim-ldap.properties

These settings apply to all tenants. Tenant-specific overrides are described in the next section.

############################### ### === Connection-Data === ### ############################### basedn=DC=myldapendpoint,DC=com host=ldaps://myladpendpoint.com port=636 username= password= authentication=simple timeout=60000 # === Group-Details === # #All places where TIM Groups could be found #groupbase.2=ou=groups #This search defines how a group must look like group.search=(member=*) #All usual group properties can here be mapped to AD-Properties group.name=cn group.member=member group.searchScaleoutLevel=0 # === User-Details === # #All places where users could be found #This search defines how a user must look like user.search=(objectClass=user) user.search.explicit= #All usual user properties can here be mapped to AD-Properties #user.name=cn user.mail=userPrincipalName user.firstname=givenName user.lastname=sn user.name=samaccountname user.supervisor=manager #user.password=cn #user.telephone= #user.department= #user.costcenter= #user.companyId= #user.companyName= #user.personnelNumber= #user.country= #user.departmentChief= #user.defaultRepresentative= # === Technical-Details === # contextfactory=com.sun.jndi.ldap.LdapCtxFactory lookup.search=(&(objectCategory\=Person)(objectClass\=*)) lookup.searchBase= lookup.searchAttributes=sAMAccountName,givenName,sn lookup.returnAttributes=sAMAccountName,givenName,sn lookup.searchPrefixWildcard=true lookup.searchMinLength=0 lookup.returnLimit=100

The sAMAccountName attribute is often used as the login name but is limited to 20 characters. For organisations where login names may be longer, userPrincipalName is the recommended alternative as it has no length restriction.

User attribute reference

The following table lists all user attributes that can be mapped from LDAP. Only the attributes included in the configuration file will be synchronised — attributes that are not needed can simply be left out.

Property	What it maps to in TIM Flow	Notes

Property	What it maps to in TIM Flow	Notes
user.name	Login name (username)	Required. Use `userPrincipalName` for names longer than 20 characters.
user.mail	Email address	Required. The user cannot log in without an email address.
user.firstname	First name
user.lastname	Last name
user.telephone	Telephone number
user.supervisor	Supervisor / manager	Expected to be a full DN in the LDAP directory. Resolved to the corresponding TIM Flow user during sync.
user.department	Department	Optional.
user.costcenter	Cost centre	Optional.
user.companyId	Company ID	Optional. Attribute name varies by directory.
user.personnelNumber	Personnel number	Optional. Attribute name varies by directory.
user.country	Country	Optional. Typically `co` or `c` in Active Directory.
user.departmentChief	Department chief	Optional. Expected to be a full DN, resolved to the corresponding TIM Flow user.
user.defaultRepresentative	Default representative	Optional. Expected to be a full DN, resolved to the corresponding TIM Flow user.

Configuring multiple LDAP endpoints

It is possible to configure different LDAP servers for different tenants. For example:

Tenant A uses LDAP endpoint 1 for synchronisation and authentication
Tenant B uses LDAP endpoint 2 for synchronisation and authentication
Tenant C uses LDAP endpoint 1 for synchronisation and authentication

This is achieved by adding tenant-specific overrides to tim-ldap.properties, replacing [TENANT_NAME] with the actual tenant name:

basedn-[TENANT_NAME]=... 
host-[TENANT_NAME]=...

All other settings in tim-ldap.properties remain shared and apply as defaults for tenants that do not have their own override.

Testing the connection

Before activating authentication or synchronisation, the connection to the LDAP server can be tested directly from the tenant profile in the administration area. The following settings must be filled in on the tenant profile first:

Attribute	Description

Attribute	Description
Authentication	Can stay empty
LDAP-Host	Host name or IP address of the LDAP server
LDAP-Port	Port the LDAP server responds on (standard: 389)
Factory Initial	Must contain the value `com.sun.jndi.ldap.LdapCtxFactory`
Kind of authentication	Can be `simple` or `digest-md5` (standard: `simple`)
DNS Prefix	Can stay empty
DNS Suffix	The DNS suffix of the organisation must be entered here (e.g. `@company.com`)

Once these settings are saved, click the Test LDAP connection button and enter an LDAP username and password to verify the connection.

The password is displayed in clear text during the connection test.

LDAP Authentication

LDAP authentication means that the system forwards login requests to the LDAP server to verify whether the user has the right to log in. When this is activated for a tenant, every login attempt is checked against the LDAP directory instead of a local password.

The following requirements apply to all users logging in via LDAP:

The user must already exist in TIM Flow. LDAP authentication does not create user accounts — this is handled by the LDAP Sync.
An email address must be set in the user's profile.
Login is not permitted if the user's password is marked as requiring a change in the Active Directory.

When the LDAP server is unavailable

When LDAP authentication is enabled for a tenant, the system requires a live connection to the LDAP server for every login. If the LDAP server is unreachable — due to a network issue, scheduled maintenance, or a configuration error — all users who rely on LDAP authentication will be unable to log in. There is no automatic fallback to a local password.

ATTENTION! Before enabling LDAP authentication for a tenant, always ensure that at least one administrator account is configured to use local authentication instead. This provides access to the system if the LDAP server becomes unavailable.

Excluding individual users from LDAP authentication

Even when a tenant is configured for LDAP authentication, individual users can be set to use a local TIM Flow password instead. This is useful for:

Administrator accounts that require access even if the LDAP server is unavailable
Service accounts used by integrations or automated processes that do not exist in the LDAP directory
Users whose LDAP account is temporarily locked but who still require access to the system

In the user's profile, enable the option Ignore LDAP Authentication. Once set, that user will always log in with their local TIM Flow password, regardless of the tenant's authentication settings.

A local password must be set. Users created entirely through LDAP synchronisation may not have a local password assigned. One must be set manually before this option takes effect.

Only authentication is affected. The user's attributes will still be updated by the LDAP synchronisation as normal. Only the login check is changed.

LDAP Sync

Overview

The LDAP Sync creates users in TIM Flow and keeps their attributes up to date from the LDAP directory. How LDAP attributes are linked to user attributes in TIM Flow is configured in tim-ldap.properties.

Sync Timers

Two sync timers are available. Both perform the full synchronisation, all features including nested groups, field protection, membership cleanup, and user lifecycle management work with either timer. The choice depends on how you want to map your LDAP directory to TIM Flow.

Important: All system users must be in the group system-member. If this is not the case, administrators may lose the ability to open smart forms, as the member right is required for this.

Choosing a sync timer

Select the timer that matches how your LDAP directory is organised and what you want to achieve in TIM Flow:

Timer	What it syncs	Use when

Timer	What it syncs	Use when
CreateUsersFromLdapGroup	One specific LDAP group. You provide the exact base DN of the group and a role to assign to all users imported from it. Users are added to a corresponding group in TIM Flow.	You want to import a single, named LDAP group and explicitly control which role its members receive in TIM Flow.
CreateUsersAndGroupFromBaseGroup	All groups found under a base DN. The timer searches the directory from the base DN downward and imports every group it finds. Groups are created in TIM Flow using the LDAP group names. Roles are derived from the LDAP group structure rather than set as a fixed parameter.	You want to mirror an entire section of your LDAP directory into TIM Flow — all groups and their memberships — without having to list each group individually.

Additional option: member limit

When using CreateUsersAndGroupFromBaseGroup, a member limit parameter can be configured on the timer. Any LDAP group with more members than this limit will be skipped during that sync run. This is useful if the directory contains distribution lists or very large groups that should not be imported into TIM Flow.

Prerequisite for Deactivate and Delete mode: If ldapUserExpiredAction is set to Deactivate or Delete, a notify-on-error group with a valid email address must be configured for the tenant before either timer will run. Both timers enforce this requirement equally.

Synchronising users from nested LDAP groups

In some directory structures, LDAP groups contain other groups as members rather than individual users directly. Users who belong only to a sub-group would otherwise not be picked up during synchronisation and would be missing from the corresponding group in TIM Flow.

This feature allows the synchronisation to follow these group-within-group relationships automatically, collecting all users regardless of how deeply they sit in the hierarchy.

How to activate

Add the following entry to tim-ldap.properties:

# Controls how many levels of nested groups are followed during sync. 
# 0 = disabled (default). 1 = one level deep. 2 = two levels deep, and so on. 
group.searchScaleoutLevel=1

Attribute	Description

Attribute	Description
group.searchScaleoutLevel	Determines how many levels of nested groups the synchronisation follows. The default value `0` disables the feature entirely. For most Active Directory setups, a value of `1` or `2` is sufficient.

What the system does

When a group is synchronised, the system checks whether any of its members are themselves groups. If so, it collects the users from those sub-groups and adds them to the parent group in TIM Flow. Sub-groups are not created as separate groups — all users are gathered into the top-level group.

Performance note: Each additional level increases the number of requests made to the LDAP server. It is recommended to start with 1 and only increase the value if users from deeper levels are still missing after the sync.

Preventing LDAP from overwriting specific fields

By default, every synchronisation run updates all mapped user fields with the current values from the LDAP directory. This means any manual changes made to a user's profile in TIM Flow — such as correcting a department name or updating a cost centre — will be overwritten the next time the sync runs.

If certain fields are intentionally managed within TIM Flow rather than in the LDAP directory, they can be protected from synchronisation updates.

How to activate

Add the following entry to tim.properties:

# Comma-separated list of fields that the LDAP sync will never overwrite. 
# Values set manually in TIM Flow will be preserved across all future sync runs. 
ldap-sync-update-blacklist=department,costcenter

The following field names are available:

Field name	What it refers to

Field name	What it refers to
namefirst	First name
namelast	Last name
email	Email address
phonenumber	Telephone number
supervisor	Supervisor / manager
department	Department
costcenter	Cost centre
companyid	Company ID
companyname	Company name
personnelnumber	Personnel number
country	Country
representative	Default representative

First-time creation is not affected. When a user is created through LDAP synchronisation for the first time, all fields are populated regardless of this setting. The protection only applies to subsequent sync runs.

Removing group memberships when a user leaves a group

When a user is moved from one LDAP group to another, the synchronisation adds them to the new TIM Flow group but would previously leave them as a member of the old one. Over time this leads to users belonging to groups they should no longer be part of.

The synchronisation now automatically removes a user's membership from any TIM Flow group they are no longer part of in LDAP. After each synchronisation run, every group in TIM Flow reflects exactly what is currently in the LDAP directory.

How to activate

No additional configuration is required. This behaviour is active automatically with both sync timers.

Manually added memberships are not affected. Only memberships created through LDAP synchronisation are subject to removal. If a user was added to a group manually by an administrator in TIM Flow, that membership is left untouched.

Automatically blocking and removing users

When a user is removed from all LDAP groups — for example because they left the organisation — their account in TIM Flow would previously remain active and unchanged. This feature allows the system to automatically block, deactivate, or delete such accounts after a configurable grace period.

How it works

The process runs in two steps automatically on every sync run, regardless of which timer is used:

Immediately after each synchronisation run: The system compares the users found in the current run against those found in the previous run. Any user who was present before but is no longer found in any LDAP group is immediately blocked in TIM Flow. If email notifications are configured, an email listing the affected users is sent to the error notification group.
Once per day at 01:00 UTC: The system checks for users who have been blocked for longer than the configured number of days. Depending on the chosen action, these users are then either left blocked, deactivated, or deleted.

How to configure

The following entries in tim.properties control this behaviour:

Attribute	Description

Attribute	Description
ldapUserExpiredAction	Determines what happens to a user after the grace period. Block (default): the user remains blocked indefinitely, no further action is taken. Deactivate: the account is deactivated — this can be reversed manually. Delete: the account is archived and can no longer be used.
ldapUserExpirationDays	The number of days that must pass after a user is blocked before the action is applied. Default: `7`.
ldap-user-expiration-deactivate-email-subject	Subject line for the notification email sent when users are blocked in Deactivate mode. Language-specific versions can be set using the suffixes `-en` and `-de`.
ldap-user-expiration-deactivate-email-text	Body text of the notification email for Deactivate mode. The placeholders `${users}` (list of affected users) and `${ldapUserExpirationDays}` are available.
ldap-user-expiration-delete-email-subject	Subject line for the notification email in Delete mode.
ldap-user-expiration-delete-email-text	Body text of the notification email for Delete mode. Same placeholders available.

Email notifications are only sent when the action is set to Deactivate or Delete, and only if at least one user was newly blocked in that run. A notify on error group must be configured for the tenant for emails to be sent. No email is sent in Block mode.

Multiple timers: If several synchronisation timers are configured for the same tenant — for example one per department — each timer only affects users it has itself previously synchronised. A user removed from one timer's scope is not blocked by another timer's run.

ATTENTION! The Delete option archives the user account. Once applied, the account cannot be restored through a subsequent LDAP synchronisation. Use this option only if permanent removal is the intended outcome.