Howto:How to configure the Phones LDAP client

From innovaphone wiki
Jump to navigation Jump to search

The IP200 (also the IP110 ,IP202 and IP230 etc.) features a powerful telephone number directory.

It will perform number-to-name resolution for incoming calls and name-to-number resolution for outgoing calls (using the IP200 built-in alphanumeric keyboard).

The directory can access up to 3 sources for lookup: the internal (flash-based) list, the PBX user list and an external LDAP server.

This article describes how to configure the IP200’s LDAP interface for various application scenarios.

It is meant as a complement to the existing standard product documentation, so please refer to this for general configuration issues.


Applies To

This information applies to

  • IP110
  • IP200
  • IP202
  • IP230
  • IP240
  • IP240-1000
  • IP72
  • IP2x2
  • mypbxi
  • mypbxa

and all other phones with innovaphone user interface.

More Information

Quick start

This topic is for people with good understanding of LDAP and with little time for reading, who simply want to see immediate results in the IP200.

Needed: IP address of target LDAP server, distinguished Name and password of LDAP user entry with read access to the directory, distinguished Name as starting point for LDAP searches (base DN).

  • Open the IP200’s applet, proceed to directory/LDAP from external Server
  • Check Enable External LDAP server access
  • Enter the target server’s IP address
  • Leave port empty (default 389 is used)
  • Enter the Distinguished Name and Password or leave both fields empty, if an anonymous search is to be performed.
  • As LDAP Mode select basic
  • Disable Sort by 1st LDAP Name attribute
  • As Base enter the base DN
  • For Object Filter try with either inetorgperson or user or organizationalperson
  • Leave all remaining fields empty, save and activate the new configuration
  • On the IP200’s alphabetic keypad hit an arbitrary letter-key and verify whether results are shown in the display. The letter should be the first letter of a person’s surname known to be present in the directory.

If nothing happens, you’ll need to work yourself through the remainder of this article.

LDAP

LDAP stands for Lightweight Directory Access Protocol; a small-footprint descendant of ITU’s older X.500 series, respectively DAP (directory access protocol). Originally developed by a group at the University of Michigan LDAP is now the de-facto standard for accessing information held within so-called Directory Servers. The protocol standardization is harboured by the IETF and specified by several RFCs. RFC 2251 is the least to name, it covers LDAPv3 - the current culmination which is implemented in innovaphone products.

The protocol is made up of operations like: Bind, Search, Add, Delete,…. The operations in turn are realized through messages. The two most notable operations are listed below.

All of those can be taking place between a client and a server, immediately after a TCP connection (port 389) has been established towards the server end.

  • Bind Operation: This Operation is handling authentication issues. It is accomplished once throughout a session. While LDAP itself is offering a wealth of authentication methods the innovaphone products currently just support clear-text authentication.

The Messages are: Bind Request and Bind Result

  • Search Operation: A client is sending a so-called LDAP Search Filter within a Search Request. This filter details what is being searched for.

The Messages are: A single Search Request, zero or more Search Result Entry messages and a completing Search Result Done.

LDAP query modes

The IP200 term LDAP mode refers to what is known in the LDAP world as LDAP control. The most important to know is that searches can fail if the server does not support the selected mode. See “LDAP Mode not supported by remote Server” below for more details on that.

The next thing to keep in mind is that the paged results and virtual list view will not be used (even if configured), if both an external LDAP server and the PBX user list are queried.

To benefit from these modes, there are 2 options:

  • Disable e.g. the LDAP access to the IP-PBX permanently (in the applet)
  • In the telephones user interface, enter the menu Search (Extern), (Suche (Extern)). This will query only the external LDAP server and thus use the configured mode (if available).

Here is how the 3 available modes work:

  • Basic: No further functionality, search results can only be narrowed by entering more letters like in an advance list.
  • Paged Results: The down-arrow key should work. From the point a search result has been received and the telephone display shows the content, a user can scroll down further. Upward scrolling is not possible.
  • Virtual List View: Both scrolling directions, upwards and downwards should work after a search result came back.

Storing telephone numbers in your LDAP directory

There are virtually endless variations to store telephone numbers in directories. Just to name a few +49 (7031) 73009-0, +497031730090, (07031) 730090, 0049 (0) 7031 73009-0...

Most LDAP servers do not apply magic when searching for telephony numbers, that is, they treat them as plain text. So if you have +49 (7031) 73009-0 in your directory and you search for +497031730090 via LDAP, there will be no match. It is thus critical to store telephone numbers in a proper format.

Here is how the IP200 is setting up the LDAP search request for resolution of an incoming number (CLI):

  • Based on the phones location information, the incoming number is expanded to a full E.164 number. This is - assumed the CLI is 0070317300999 and the phone location is set to country code 49, area code 7031, national line prefix 0, international line prefix 00, trunk access prefix 0 and trunk subscriber number 73009 – normalized to +4970317300999. (For more information on the location settings, please refer to the IP200’s administrator manual)
  • An LDAP search expression is created which will search for 3 patterns
  1. The raw number as received in the call (please note that this will include the trunk access prefix): 0070317300999
  2. A pattern which will search for the normalized number with some decoration: +49*7*0*3*1*7*300999
  3. A pattern which will search for the normalized number with full decoration: +49*7*0*3*1*7*3*0*0*9*9*9

This expression will find all reasonable notations for a normalized number in the LDAP server.

As a side note: when the directory searches the local flash directory, it will only use pattern 1 above.

Multiple numbers for a single contact

The way the IP200 constructs its search pattern actually forbids storing multiple numbers in a single attribute. In order to work around this a server must either allow for multiple instantiation of the respective telephone number attribute (e.g. telephoneNumber). Each instance of the attribute would contain a single number. Or the server maintains several telephone attributes with different names.

For instance the Active Directory™ does both. If a new user is configured to the system, a dialogue with lots of tab-dialogues and user properties can be edited. The number that can be entered on the General page will later settle in the attribute telephoneNumber. More instances of this attribute will be created, if you clicked on Other.. right next to it. The Telephones page will allow you to configure a home phone number, a mobile phone number and so on. These latter numbers will result in additional attributes like homePhone, mobile and so on. On the IP200, the effect is that a single user shows up multiple times in the telephone display, once for each telephone number found in the directory.

For more information regarding the attributes used for searching, see the IP200’s administrator manual.

LDAP Servers

Active Directory™

Supported LDAP Modes: basic and paged results.

To access the database, you will need a DN of a Windows™ domain user with read access to the directory.

The IP200 will use this DN, together with the users password to authenticate itself against the Active Directory.

Distinguished Name and Password: It is assumed you are logged in to Windows domain with administrator privileges on one of your domain controllers.

Open a command prompt and enter:

ldifde.exe -s 127.0.0.1 -f user.ldf

[ See below for information regarding ldifde.exe ]

As a result user.ldf will contain the entire user database as stored within the Active Directory.

Open the file with a text editor and search for the user, whose credentials you want to configure in the ip200 (you may want to create a pseudo user with limited rights for this).

Look for the users line beginning with dn:. The content behind is what we’re looking for.

Here is an excerpt for a user named test:

dn: CN=test,CN=Users,DC=inno-bln,DC=com
changetype: add
memberOf: CN=Administrators,CN=Builtin,DC=inno-bln,DC=com
accountExpires: 9223372036854775807
adminCount: 1
badPasswordTime: 0
badPwdCount: 0
codePage: 0
cn: test
countryCode: 0
displayName: test
dSCorePropagationData: 20010725142708.0Z
dSCorePropagationData: 16010101000001.0Z
mail: test@inno-bln.com

As Distinguished Name we’re configuring CN=test,CN=Users,DC=inno-bln,DC=com in the IP200.

The password cannot be learned from the file.

You can select paged results as LDAP mode (see above for details on LDAP modes).

As Base you should enter what you configured as domain during the Active Directory installation.

Usually something of the form: dc=mycompany,dc=com. If in doubt, you can use ldp.exe to determine the base DN.

Connect to your domain controller and look for the attribute defaultNamingContext respectively namingContexts.

If the IP200 shall search for Active Directory users, enter user as object filter. If it shall search for contacts only, use contact. To search both, enter (|(objectclass=user)(objectclass=contact)). The latter is an “Or” filter string. Using the field “objectcategory” in the filter prefix can be more efficient for the server than using “objectclass” (the default value), since the former is indexed on the Active Directory server by default, whereas the latter is not indexed by default.

The Attribute 1..3 settings can be left empty, the internal default should suffice.

However, if e.g. Surnames (sn) aren’t properly maintained in the Active Directory you eventually will have to fall back to a common attribute.

In this case try with cn as Attribute 1, leave the other fields empty.

Leave Phone 1 .. 4 empty.

Leave Mail empty.

iPlanet Directory Server 5.0

[ iPlanet currently seems to be known as Sun Java System Directory Server 5.2 ]

The product is the successor of Netscape’s Directory Server 4.12, so some or all of the recommendations may apply to this product too.

Supported LDAP Modes: basic and virtual list view.

To access the database, you will need a DN of an iPlanet user with read access to the directory. The IP200 will use this DN, together with the users password to authenticate itself against the iPlanet. It is suggested to create a dummy user with restricted privileges for this. You will need to use the value of the entrydn configuration attribute (from the iPlanet property editor) as distinguished name in the IP200 configuration.

It is recommended to select basic as LDAP mode (see above for details on LDAP modes). If you intend to use virtual list view, be sure to read the next chapter carefully. We found this mode to be slow on the iPlanet.

As Base you will need to configure the value entrydn property of the iPlanet sub tree containing the objects to be searched. This will be something of the form: ou=tree,dc=domain,dc=tld. If in doubt, use iPlanet’s property editor to determine proper value.

All users are stored as objects of type inetOrgPerson. So simply enter inetOrgPerson as object filter.

The Attribute 1..3 settings can be left empty, the internal default should suffice. You may want to experiment with either cn or sn for Attribute 1 for better results.

Leave Phone 1 .. 4 empty unless you add telephone numbers to different numbers in the iPlanet management console. If so, you need to specify the respective attribute names as Phone 1 .. 4, starting with telephoneNumber.

Leave Mail empty.

Using virtual list views with iPlanet

To use virtual list views on an iPlanet server, there must be a browsing index for the sub tree used as base dn. This can be created using the iPlanet management console. However, performance can be slow. The remainder of this chapter aims at helping get the best performance out of the iPlanet.

To take advantage of the created index for virtual list view queries, the query must match exactly the index created. To assure best performance, it is critical thus to configure the IP200’s LDAP search expression so that it in fact will trigger the index. When an index is created, the iPlanet server internally creates two new directory entries. One is of objectclass vlvSearch and the other of objectclass vlvIndex. You will need to find some attributes of these nodes. The simplest way to get at this information is to have a look at the file ..\bin\slapd-xxx\config\dse.ldif. You will need to find the data related to the newly created index.

Here is an example:

dn: cn=by MCC ou=People  dc=inno-bln dc=com,cn=MCC ou=People  dc=inno-bln dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
objectClass: top
objectClass: vlvIndex
cn: by MCC ou=People  dc=inno-bln dc=com
vlvSort: cn,givenname,o,ou,sn
creatorsName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
modifiersName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
createTimestamp: 20011114120401Z
modifyTimestamp: 20011114120401Z

and

dn: cn=MCC ou=People  dc=inno-bln dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
objectClass: top
objectClass: vlvSearch
cn: MCC ou=People  dc=inno-bln dc=com
vlvBase: ou=People,dc=inno-bln,dc=com
vlvScope: 1
vlvFilter: (|(objectclass=*)(objectclass=ldapsubentry))
creatorsName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
modifiersName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
createTimestamp: 20011114120400Z
modifyTimestamp: 20011114120400Z
numSubordinates: 1

Based on this information, we can fine-tune the IP200’s configuration as follows. As Base you will need to specify the value of the vlvBase attribute. In our example, we would need to configure ou=People,dc=inno-bln,dc=com. Please note the value 1 for the vlvScope attribute above. This means the server does not recurse down from the base to look for potential search hits.

Instead of inetOrgPerson you need to specify the value of the vlvFilter as object filter.

In our example, we would need to configure (|(objectclass=*)(objectclass=ldapsubentry)). This will restrict the search to what is covered by the index.

However, we still need to request the proper search order for the index to be used. This defined by the value of the vlvSort attribute.

In our example, we would need to configure cn,givenname,o,ou,sn as sort order. Unfortunately, this cannot be configured via the phone’s applet. Instead, you need to change the respective line in the IP200’s configuration file.

You will need to append the /ldap-sort sortmode option to the config file line:

config change PHONEDIR0  

In our example, it would look like

config change PHONEDIR0 /ldap-sort cn,givenname,o,ou,sn  other options

Please note that in iPlanet, vlv entries can have an ACL associated. If you get Insufficient Access Rights replies, you may need to inspect the access rights.

MS Exchange 5.5

Microsoft™’s Exchange 5.5 incorporates an LDAP server, known as the Directory Store (DS).

There are a few limitations, with one being really annoying: The DS does not expose everything to LDAP the Exchange 5.5 might know. In particular, the public folders used to store contact records are not accessible via LDAP. The only data that can be queried is the global address list. We thus recommend using ESTOS MetaDirectory to access Exchange contact data.

LDAP Modes supported: basic and paged results

Distinguished Name and Password: our tests were done without any authentication, i.e. with empty user information and with an empty password.

Base: use the exchange domain as base.

Use ldp.exe to examine the rootDSE and retrieve the value of the namingContext attribute.

This is usually something of the form:

o=myexchangedomain
Object Filter: we recommend using a filter, which restricts results to objects, which actually have a telephone number. 
This will remove confusing entries like distribution lists and the like: (&(objectclass=organizationalperson)(telephonenumber=*))
Attribute 1..3: Enter: cn for Attribute 1
Phone 1 .. 4: Leave empty.
Mail: Leave empty.

OpenLDAP 2.07 or later

Distinguished Name and Password: enter cn=useraccount-you-want-to-use,dc=host,dc=tld as Distinguished Name and configure the respective secret as password.

LDAP Mode: basic.
Base: use dc=host,dc=tld, as in the distinguished name above.
Object Filter: use inetorgperson.
Attribute 1..3: leave empty.
Phone 1 .. 4: leave empty
Mail: leave empty

Lotus Domino R5

Very much like Exchange 5.5 the Domino Server does not speak LDAP natively. And like OpenLDAP: not a single LDAP control is supported. Also, certain Domino fields need to be configured for read-access.

For the anonymous search requests to work, the field OfficePhoneNumber had to be configured explicitly. Without this hand-crafting, the LDAP attribute telephoneNumber never made its way towards the ip200. In the Lotus Notes Server Configuration, you will need to make sure the attributes FirstName, FullName, LastName, MailDomain and OfficePhoneNumber are listed under Anonymous users can query: in the LDAP property tab with at least Read access.

LDAP Modes supported: basic

Distinguished Name and Password: the tests done using anonymous LDAP search requests, i.e. with an empty user information and password.

Base: please consult your local Domino Administrator for the desired organization name – it will be something of the form o=myorganization.

Experience with a Domino R6 did show, that the Base had to be left empty.

That is, the Domino did not offer any naming context, except an empty one.

Object Filter: user inetOrgPerson or leave empty (inetorgperson is default).
Attribute 1..3: Can be left empty, since the default will suffice (sn,givenName,Company).
Phone 1 .. 4: leave empty.
Mail: leave empty.

Cisco call manager

The Cisco Call Manager (CM) also incorporates an LDAP server, that’s meant to be queried by Cisco’s’ IP phones.

Note that it’ll be likely to run on a different port than 389.

LDAP Mode: use basic.

Distinguished Name and Password: please query your CM Administrator for the desired information – it will be something like cn=Directory Manager,o=cisco.com accompanied by a password.

Base: Please query your CM Administrator for the desired information – it will be something like: ou=users,o=cisco.com

Object Filter: leave empty (inetorgperson is default).
Attribute 1..3: Can be left empty, since the default will suffice (sn,givenName,Company).
Phone 1 .. 4: Leave empty
Mail: Leave empty

Estos MetaDirectory

MetaDirectory is an LDAP server and also a data consolidation tool. That is, it will retrieve contact data from various sources and replicate it into a single LDAP database for search and retrieval. This is a very powerful tool.

Please find more information here:

innovaphone PBX

An IP200 will by default query its own PBX for directory data. There is no special configuration required to do this (except that it must be enabled in the config applet). However, in complex multi-PBX scenarios it may be necessary to query a different PBX for directory data (e.g. a master PBX in a location scenario).

Here is how to configure an innovaphone PBX as external LDAP server:

  • Server: IP address of the PBX
  • Port: 389
  • User Name and Password: use what is configured as valid LDAP server access in the PBX under Config/LDAP Server. Read-only access is sufficient.
  • Search Base: use cn=pbx0
  • LDAP Mode: use virtual list view.
  • Object Filter: use (objectclass=*)
  • Name Attributes : use cn as attribute
  • Number Attributes :use e164 as attribute
  • H323 ID Attr :use h323 as attribute, if you have objects to call with no number
  • Mail: use h323

Troubleshooting

Ldifde.exe is a standard command-line LDAP client. It is part of the Windows 2000 server software. The program allows exporting and importing the contents of an Active Directory into/from so-called LDIF files.

The LDIF data format is standardized by an RFC and has the benefit to be readable with a text editor. We’re using ldifde to read out some information that in turn is required for the configuration of the telephone.

Ldp.exe is an unsupported Microsoft Win32 application that can be installed from the support\tools folder of the Windows 2000 server CD. Actually it is a fairly well featured LDAP client. Despite of poor documentation it is very valuable in handling the first LDAP configuration questions.

Ldp.exe may be helpful in reading a servers rootDSE, browsing a servers directory, determining potential LDAP Search Bases and so on. To see a servers rootDSE simply select Connection/connect within ldp.exe. The application then automatically queries the server for the rootDSE and presents it in the right pane window. The rootDSEs namingContexts attribute lists some possible values for the base DN.

Once connected you can authenticate to a server by choosing Connection/Bind.

The default (no Advanced, Domain not checked) conducts a clear-text or SIMPLE authentication (what the ip200 is doing).

In contrast to MS Internet Explorer the Netscape Browser may serve as a fairly well featured LDAP client. Beyond Netscape Messenger’s LDAP capabilities the Browser does support the LDAP-URL specified in RFC1959. The only constraint is the necessity for anonymous read access. The browser even does not give any error message if the LDAP Bind operation fails.

Here’s how you can read an LDAP server’s rootDSE:

ldap://server/??base

Every object underneath a hypothetical DN o=myorg:

ldap://server/o=myorg??sub

To obtain meaningful traces from the IP200, you will need to switch on the /trace and /ldap-trace options of the IP200’s PHONEDIR0 config line.

Make sure to append these traces to your current configuration, such that it looks something like

config change PHONEDIR0 /trace /ldap-trace further-options

Common Problems

0:1607:171:3 - ldir(S): LDAP BIND failed=> 49,"Invalid Credentials"

Either the distinguished name/password for the server login is wrong or the server does not support clear text authentication.

0:1153:561:4 - ldir(S): LDAP SEARCH failed=> 12,"A Critical Extension (LDAP Control) Is Unavailable"

The server does not support a search control you are using.

Make sure the Sort by 1st LDAP name attribute is unchecked and there is no /ldap-sort option in the config file.

If this does not help, try basic as LDAP mode.

Related Articles