LDAP Synchronization

Description

This module installs LDAP/Active Directory synchronisation software

Release notes

Module configuration interface

Module configuration parameters

The LDAP module requires several parameters to be configured:

• LDAP Host: The hostname or IP address of your Active Directory server. Your Active Directory server should be reachable from the Escaux UCS.
• User: A valid user having read access on Active Directory. See below for more details.
• Password: the user's password in clear-text
• Windows domain: the user's domain
• Base DN: The root node to start the search. Check your LDAP server. This is typically the DN representing your company, possibly including a OU component as well.
• Company domain name: This is used to suffix the usernames in LDAP to form a username suitable for the SMP. E.g. A user named 'joe' in LDAP may be translated to 'joe@mycompany.com' in the SMP. Make sure to use this feature if you can have different "joe"s on your SMP, located in different SOPs or clusters: 'joe@company1.com', 'joe@company2.com' etc.
• Default callflow: When records are created in the internal directory, the first time they must be assigned a callflow, e.g. 'User.Office'. Since version 1.10.0 of the module and the SyncLDAP task, this value can also be fetched from the ldap directory. Records that don't have the ldap attribute will use the default callflow defined here.
• Filter: An LDAP filter to select which users should be read from LDAP. See your LDAP server's documentation for the syntax.
• The following parameters specify which LDAP attributes should be used to obtain the data.
  • Extension
  • DDIs (previously External Number)
  • Username
  • E-mail address
  • Mobile number
  • Language (MANDATORY): points to an attribute containing the ISO language code, e.g. "en", "nl", "fr"
  • Office
  • Department
  • Callflow : If this parameter is filled in, callflows are always synchronized from LDAP. See more information about this in the Further Information section below.
  • Caller ID : set P_CallerIDNumber of created extension (Template-User) to either a constant ('+32471...' the number of customer's reception for ex.) either a value from 'attr/regexp/repl' mechanism. To use the attribute without replacement, you can't just pass it's name as it will be considered as a constant, so use the workaround 'attribute/(.*)/_'. If Caller ID field left empty -> CallerID = DDI number (the first if ' & ' expression, see below) created for the entry

Optionally, the data can be manipulated in order to, for example, strip or add digits to phone numbers. If only the name of an LDAP attribute is given, no translation is done but if the pattern 'attribute/regexp/replacement' is used, then the value read from LDAP will be matched against a regular expression:

- If it doesn't match, the record is not used.

- If it does match, the part between the parenthesis is taken and put inplace of the underscore in the replacement string.

For example 'telephoneNumber/^32.....(...)$/1_' will read the 'telephoneNumber' attribute, check that it starts well with '32' followed by exactly 8 digits and finally extract the 3 last digits and prefixe them with the number '1'.

You can use several groups '(...)' in the regex. See it as '_' in the replacement part will be substituted by the concatenation of matching groups. Here are some example regarding phone numbers where we can encounter special characters, from which we'll extract the _x_'s :

• xxxx xxx xxxx (spaces) with "attr/(....) (..) (....)/_"
• 0 xxxxxxxxxx (extra leading 0) with "attr/0(..........)/_"
• 32 xxxxxxxxx (without +) with "attr/32(.........)/_"
• 0 xxx.xx.xx.xx (dot) with "attr/0(...)\.(..)\.(..)\.(..)/_"
• 0 xxx-xx-xx-xx (hyphen) with "attr/0(...)-(..)-(..)-(..)/_"
• 0 xxx / xx.xx.xx (slash and dots) with "attr/0(...).(..)\.(..)\.(..)/_"

Maybe the customer has some mix of formats and you want to capture all, but be careful to 'earliest matching logic' applied by perl :

• WRONG : "telexNumber/(....) (..) (....)|0(..........)|32(.........)|0(...)\.(..)\.(..)\.(..)|0(...)-(..)-(..)-(..)/_"
• OK : "telexNumber/^0(...)\.(..)\.(..)\.(..)$|^0(...)-(..)-(..)-(..)$|^(....) (..) (....)$|^0(..........)$|^32(.........)$/_"

EXPLANATION : Let, for example, the value of attribute telexNumber be 0471-53-69-98 for an entry. ‘0(..........)’ will capture it first as it finds “10 characters after a ‘0'“, so returning the value ‘471-53-69-'. To solve it place the most 'specific’ matching '0(...)-(..)-(..)-(..)’ first in the chain and mark implicitly the length of match with ^regex$

For DDIs field (>= 1.17.5), the syntax is extended to allow the creation of 2 distinct DDIs entries using the ' & ' separator. For example 'telephoneNumber/^32(........)$/_ & mobile/^32(........)/99_' will lead to the API method list() returning 2 ddis for each LDAP entry (from the 2 distinct attributes telephoneNumber and mobile). It is allowed, in each member of the expression '... & ...', to have composed expressions to capture several patterns, using '|' just like in other fields.

• Note that, by default, if the above fields are not filled, the extension will be set to the "Phone number" attribute of the active directory user.
• The First Name and Last Name attributes are always synced from the standard LDAP attributes "givenName" and "sn" respectively, they cannot be manipulated.
• Sync Users: allows to disable the creation of user accounts in the SMP, i.e. only create extensions and external numbers.
• SASL Authentication: Do authentication by using SASL (MD5) to prevent passwords from being stored and sent in clear-text.
• Data encoding (default: utf8): Select the data encoding of the LDAP server. You can set this to latin1 or utf8 (the default).
• StartTLS: Set to yes to encrypt all connections towards the LDAP server with TLSv1. The connection is initiated with the StartTLS mechanisms described in RFC4511 and RFC4513. Note that the StartTLS root CA certificate parameter is required when this is set to yes. The name of the LDAP host parameter and the name presented in the LDAP server certificate (Subject name or Subject alternative names) must match.
• StartTLS root CA certificate: The contents of this parameter is required when StartTLS is enabled. It needs to be a PEM formatted certificate (including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- statements). Make sure that this is the topmost certificate in the certificate chain (aka, the root CA certificate). Your LDAP server should present the whole certificate chain while initiating the connection.
• Windows bind method: This defines the bind method that is used to authenticate users in active directory. The default is to use the old style DOMAIN_NAME\samAccountName bind method. Optionally it's possible to use UPN authentication which will use the userPrincipalName attribute when binding to active directory.

User field

If the user field does contain the "=" character, it won't be changed. If the user field does not contain the "=" character, it will be modified to allow to bind to OpenLDAP. The prefix cn= will be added (in front of the field's value) and the base DN will be added after the field's value.

For example, if the field contains TestUser and the base DN contains dc=example,dc=com the username used to bind to the LDAP server will be cn=TestUser,dc=example,dc=com

Further Information

After installing this module, you can initiate the LDAP synchonization process by using the SyncLDAP task.

Further information about the LDAP functionality in general can be found in the LDAP Sync admin guide.

Synchronizing callflows

If the callflow parameter is filled in, the callflow will be synchronized at every synchronization. If it is not filled in, the old behaviour is retained. In this case the default callflow be set once at extension creation.

For dynamic profiles, always make sure a default status is properly set for the profile. Regardless of the value synced from ldap, the first apply changes after synchronization, it will push the default status to the SOP. Subsequent synchronizations will leave the profile/status untouched, unless the profile was changed.