LDAP Integration for sipXconfig

From SIPfoundry sipx, The Open Source SIP PBX for Linux - Calivia

Starting with development release 3.5, sipXconfig supports integration with LDAP-enabled directory services. This allows administrators to centrally manage user information including credentials across several applications and including sipX.

This page provides implementation details, usage scenarios and instructions on how to use this feature.

1 Configuring the LDAP Server in sipXconfig
2 Usage Scenarios
3 LDAP Field Mapping
4 Synchronization Schedule
5 Error Reporting
6 Assumptions & Limitations
7 Further Reading
8 LDAP Clients that can be used to manipulate LDAP directories

[edit] Configuring the LDAP Server in sipXconfig

sipXconfig allows the administrator to configure a single LDAP server. The following parameters are required:

LDAP server address in the form of an IP address, the DNS name and optionally the port number
Distinguished name of a directory sub-tree that contains user information: sipXconfig supports various user-tree organizations as long as all user-trees can be accessed from a single root
LDAP attributes to sipXconfig field mapping: See Field Mapping section below
User's group name: This is the group that will contain all users imported from the LDAP server
Optionally LDAP credentials: sipXconfig needs read-only access to the LDAP directory. If such access requires authorization, the administrator has to configure appropriate credentials

[edit] Usage Scenarios

Scenario	Description
Initial Import	During installation of sipXconfig the administrator configures the LDAP server from which sipX will import data. The initial import is initiated on demand from the sipXconfig UI. Users are imported and the administrator can proceed to configure the remaining part of the system.


Switching a running system to LDAP	In a running sipX system sipXconfig already contains a list of users. The easiest way for the administrator to initiate synchronization with an LDAP server is to create a new user group that contains all the users that will be synchronized with the LDAP server. The administrator then configures the LDAP server address and triggers an import. All users in the specified group are updated, new users are added, and users that are in the group but not in LDAP server are removed.


Scheduled Import	Automatically scheduled import is performed periodically. Newly added LDAP entries are imported as new sipXconfig users. If any entries were deleted since the last import, sipXconfig will delete those users. If any entries were modified, sipXconfig user data is modified accordingly.


Triggered Import	A 3rd party application is used to perform LDAP updates. The SOAP API is used to trigger LDAP import each time the LDAP directory is changed.

[edit] LDAP Field Mapping

sipXconfig Field	LDAP Attribute	Description
user id	uid	A unique user identification. The administrator can use the user's extension (e.g. 1245) as a user id or more readable identifiers, similar to the user part of an e-mail address (e.g. johndoe, john.doe etc.). A single attribute should be mapped to this field. Changing the value of LDAP attribute mapped to the user id field will be interpreted by sipXconfig as removal followed by an addition of a new user. This is the only mandatory mapping.


firstname	gn	User's first (given) name. This is an optional mapping.


lastname	sn	User's last name. This is an optional mapping.


aliases	telephoneNumber	Multiple attributes (possibly multi-value attributes) can be mapped to this field. Since sipXconfig requires that all aliases are unique, it will drop any values that are not unique. If non-numeric user ids are configured, administrators may want to add conventional phone (extension) number as one of the aliases. This is an optional mapping.


Voicemail PIN		Secret used by users to access voice mail. Also used by sipXconfig user portal to access call forwarding, PIN change and other user related functionality. This is an optional mapping. If this field is not mapped, sipXconfig will allow administrators to configure the initial value of PIN. After deployment users will be asked to change PIN using Telephone UI or sipXconfig UI. Subsequent imports will preserve the value of this field.


SIP password		The password used by phones to register with sipX. The administrator has the option to: a) map this field to the LDAP attribute; b) set the initial value for all the fields; or c) let sipXconfig randomly generate a value. The last strategy works best if phones, as well as users, are managed by sipXconfig. In this case phones will be automatically configured with randomly generated passwords providing strong security. If the SIP password was randomly generated or preset by the administrator its value will be preserved during subsequent LDAP imports.


Group		Multi-value attribute containing user group name. This is an optional mapping. In addition to groups created by this attribute mapping, sipXconfig will require that administrators provide the name of the group that would contain all imported users.

[edit] Synchronization Schedule

sipXconfig supports on demand synchronization triggered through the sipXconfig UI or the sipXconfig SOAP API. Additionally, the administrator has an option to configure a synchronization schedule. Weekly, daily and hourly schedules are supported (every Friday, every weekday, Every day, every hour time etc.).

[edit] Error Reporting

sipXconfig implements a “best effort” import strategy. All entries that contain enough "well formatted" data are imported, incomplete or invalid entries will be skipped. sipXconfig leverages its error reporting mechanism to inform about problems encountered during LDAP import. The list of successfully imported entries will be available through the UI (Job Status page). The list of entries that failed to import will be available through the UI and in the sipXconfig.log file.

[edit] Assumptions & Limitations

A single LDAP server is supported: Since sipXconfig works equally well with an LDAP enabled directory server, an LDAP gateway or an LDAP proxy, advanced users should be able to configure more sophisticated topologies.
User information is kept in a single sub-tree of an LDAP directory: sipXconfig searches a single sub-tree only trying to locate all entries that fulfill requirements specified by the administrator during the LDAP support configuration.
Discrepancies between LDAP data and sipXconfig data: LDAP has priority. The sipXconfig database will be updated with information kept in the directory, sipXconfig will never push users' data to LDAP based directory.
Only user data is retrieved from LDAP: If the administrator intends to configure phones with sipXconfig, the phone information has to be independently provided through the user interface, the SOAP API or via file import.
All imported users are placed in a single sipXconfig group (configured by the administrator). If necessary the adminstrator can configure group membership after an initial import. sipXconfig group structure will be preserved during subsequent synchronizations with the LDAP server.
There is only limited support for retrieving group information. Administrators can map LDAP attributes, values of which will contain user group names; sipXconfig will not support retrieving group information from the tree structure.

[edit] Further Reading

Windows Server LDAP Access

[edit] LDAP Clients that can be used to manipulate LDAP directories

Moving to LDAP also allows leveraging tools for user and identity data entry and management. LDAP tools are stable, well developed, available for many platforms also in open source.