Configuration of LDAP Directories to be Synchronized

Optional Attributes

The defaultRoles Attribute

The defaultRoles attribute is used to set whether a newly created user will automatically be assigned to the roles of the Stages “default“ user. To enable that behavior, the parameter has to be set to “true“. This feature is disabled by default.

The defaultRolesUsername Attribute

If the attribute defaultRoles is set to “true”, the defaultRolesUsername attribute can be used to specify a different user than the Stages “default” user for automated role assignments. If set, a newly created user (i.e. first time import) is assigned to the same roles as the user specified by this attribute (rather than to the Stages “default” user’s roles). By default this attribute is set to the Stages “default” user.

The homeProject Attribute

In Stages every user is assigned to a specific workspace. The homeProject attribute can be used to state a workspace to which every newly created user will be assigned to. The workspace/project can either be specified directly by name, e.g. “WorkspaceA“,or with full path info, e.g. “Company|Workspaces|WorkspaceA“. If the homeProject attribute value is invalid or not set at all every newly created user will automatically be assigned to the root project.

The ident Attribute

The ident attribute can be used to identify different parts of a single LDAP server that needs to be queried with multiple queries. Otherwise the value of the url attribute will be used for that purpose. The ident attribute is supposed to be a unique key of a ldap-provider section.

The pageSize Attribute

Often, LDAP servers are configured to limit the maximum number of results for a single query. Clients are required to fetch the results in chunks to reduce the overall load on the server.

Using the pageSize attribute it is possible to configure the maximum chunk size the LDAP server supports. The control extension (RFC 2696) used for that purpose may not be supported by your LDAP server.

The recursiveSearch Attribute

This parameter determines if subfolders of the LDAP directory specified with the url attribute should also be searched for user entries. The parameter value has to be set to “true“ in order to enable that functionality. By default that behavior is disabled.

The referrals Attribute

In a LDAP directory referrals can be used to integrate entries located in different namespaces or even on different servers. A referral therefore contains one or more URLs of objects, which are usually LDAP URLs. The LDAP URL contains the server’s host/port and an object’s distinguished name. A referral is returned to the client, e.g. it is not followed automatically.

The referrals attribute can be used to configure the handling of LDAP referrals. Possible behavior and values are “follow“ or “ignore“. By default, Stages will follow referrals.

The searchFilter Attribute

This attribute is used to determine the users to be synchronized into the Stages user database. LDAP server entries that don’t match the filter expression are ignored for synchronization.

The syntax used to build up the filter expression is specified in RFC 2254. Some examples are provided below:

Filter ExpressionMeaning
(objectClass=*)All objects
(sn=sm*)All entries with a surname that starts with “sm”
(&(sn=smith)(objectClass=user)(email=*))All entries that are users having the surname “smith” and an email address.
(&(objectClass=user)(!age<18)((sn=smith)(sn=wright)))All entries that are users having surname set to “smith” or “wright” and are older than 18

NOTE: In the Config.xml file the character “&“ has to be escaped via “&“. Otherwise errors parsing the configuration file could occur.

There is a special memberOf keyword available on many LDAP directory servers. In the case of Microsoft Active Directory, groups are represented via entries of object class “group“ by default. The distinguished names of the group members are set in the member attributes of the group entry. On the other hand, the distinguished name of every group a user is part of is automatically set in a memberOfattribute of the user entry.

The following search filter example shows how to filter users according to a certain group membership using the memberOf attribute:

searchFilter=“(memberOf=CN=SampleGroup,DC=pkit,DC=methodpark,DC=de)“

If the memberOf attribute is not available on your LDAP directory server, it is possible to retrieve the members of a certain group by querying the member attribute of a group entry.

The following search filter example shows how to query the users of a group without using the memberOfattribute:

searchFilter=“distinguishedName=CN=SomeGroup,DC=er,DC=methodpark,DC=de”

The filter specifies that the distinguished name of the (group) entry has to be “CN=SomeGroup,DC=er,DC=methodpark,DC=de“. In order to state the attribute name, which contains the distinguished name of the group members, the attribute groupMemberAttribute has to be set, e.g. to “member“ in the case of Active Directory.

A complete example for retrieving group members without using the memberOfattribute is listed below.

searchFilter=“distinguishedName=CN=SomeGroup,DC=er,DC=methodpark,DC=de”
groupMemberAttribute=“member“

The ondemandFilter Attribute

This attribute is required for user auto-creation and/or on-demand synchronization mode. It allows the Stages system to query the LDAP server for specific users by their Stages login name. The attribute value a query filter like the searchFilter attribute, except that it is meant for unique queries.

The ondemandFilter must contain the placeholder character “%” that will be replaced by the username when queries on the LDAP repository are made.

Example: ondemandFilter=“(sAMAccountName=%,cn=Users,dc=methodpark,dc=com)”

The matchUsersMode Attribute

The matchUserMode attribute specifies how LDAP user entries are matched to Stages users when no mapping can be performed using the special _KEY attribute.

Possible values for the matchUserMode attribute are:

  • username
  • fullname
  • email

If no explicit value is set for that attribute then the username will be used for that purpose.

The adoptUsers attribute

Stages distinguishes between local user accounts and LDAP user accounts in its user database. The adoptUsers attribute can be used to convert a local user account to an LDAP account if the user can be identified via the matchUserMode attribute. To enable the user account conversion the adoptUser attribute has to be set to “true“. The conversion is disabled by default.

The generateDN attribute

If the directory server does not provide a distinguished name attribute for its entries, the generateDn attribute can be set to “true“ to calculate the distinguished name automatically.

The defaultLicenseType attribute

The defaultLicenseType attribute specifies which license type shall be granted to a newly created LDAP user. Possible values for that attribute are:

  • QM
  • PM
  • Dev
  • none

The specified license type is only assigned if the corresponding license limit for that type is not reached. If the defaultLicenseType attribute is not specified then the value of the configuration property license.types.initialType is used for that purpose.