LDAP Integration(external services)
LDAP Integration
Asterisk supports the ability to connect to an existing Lightweight Directory Access Protocol (LDAP) server to load information into your Asterisk server using the Asterisk Realtime Architecture (ARA). The advantage of integrating Asterisk and LDAP will become immediately obvious when you start centralizing your authentication mechanisms to the LDAP server and using it for several applications: you significantly cut down the administrative overhead of managing your users by placing all their information in a central location.
There are both commercial and open source LDAP servers available, the most popular commercial solution likely being the one implemented by Microsoft Windows servers. A popular open source LDAP server is OpenLDAP. We will not delve into the configuration of the LDAP server here, but we will show you the schema required to connect Asterisk to your server and to use it to provide SIP connections and voicemail service to your existing user base.
Configuring OpenLDAP
While a discussion of the installation and configuration of an LDAP server is beyond the scope of this topic, it is certainly applicable to show you how we expanded our initial LDAP schema to include the information required for Asterisk integration. Our initial installation followed instructions from the Ubuntu documentation page. We only needed to follow the instructions up to and including the backend.example.com.ldif import; the next step after importing the backend configuration is installing the Asterisk-related schemas.
If you’re following along, with the backend imported, change into your Asterisk source directory. Then copy the asterisk.ldap-schema file into the /etc/ldap/schema directory:
$ cd ~/src/asterisk-complete/asterisk/11/contrib/scripts/
$ sudo cp asterisk.ldap-schema /etc/ldap/schema/asterisk.schema
With the schema file copied in, restart the OpenLDAP server:
$ sudo /etc/init.d/slapd restart
Now we’re ready to import the contents of asterisk.ldif into our OpenLDAP server. The asterisk.ldif file is located in the /contrib/scripts folder of the Asterisk source directory:
$ sudo ldapadd -Y EXTERNAL -H ldapi:/// -f asterisk.ldif
We can now continue with the online instructions and import the frontend.exam ple.com.ldif file. Within that file is an initial user, which we can omit for now as we’re going to modify the user import portion to include an objectClass for Asterisk (i.e., in the example file, the section of text that starts with uid=john can be deleted).
We’ll create a user and add the configuration values that will let the user register his phone (which will likely be a softphone, since the hardphone on the user’s desk will, in most cases, be configured from a central location) via SIP by using his username and password, just as he would normally log in to check email and such.
The configuration file we’ll create next will get imported with the ldapadd command and will be added into the people object unit within the shifteight.org space. Be sure to change the values to match those of the user you wish to set up in LDAP and to substitute
dc=shifteight,dc=org with your own location.
Before we create our file, though, we need to convert the password into an MD5 hash. Asterisk will not authenticate phones using plain-text passwords when connecting via LDAP. We can convert the password using the md5sum command:
$ echo “my_secret_password” | md5sum
a7be810a28ca1fc0668effb4ea982e58 –
We’ll insert the returned value (without the hyphen) into the following file within the userPassword field, prefixed with {md5} :
$ cat > astuser.ldif
dn: uid=rbryant,ou=people,dc=shifteight,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: AsteriskSIPUser
uid: rbryant
sn: Bryant
givenName: Russell
cn: RussellBryant
displayName: Russell Bryant
uidNumber: 1001
gidNumber: 10001
userPassword: {md5}a7be810a28ca1fc0668effb4ea982e58
gecos: Russell Bryant
loginShell: /bin/bash
homeDirectory: /home/russell
shadowExpire: -1
shadowFlag: 0
shadowWarning: 7
shadowMin: 8
shadowMax: 999999
shadowLastChange: 10877
mail: russell.bryant@shifteight.org
postalCode: 31000
l: Huntsville
o: shifteight
title: Asterisk User
postalAddress:
initials: RB
AstAccountCallerID: Russell Bryant
AstAccountContext: LocalSets
AstAccountDTMFMode: rfc2833
AstAccountMailbox: 101@shifteight
AstAccountNAT: yes
AstAccountQualify: yes
AstAccountType: friend
AstAccountDisallowedCodec: all
AstAccountAllowedCodec: ulaw
AstAccountMusicOnHold: default
Ctrl+D
With the file created, we can add the user to our LDAP server:
$ sudo ldapadd -x -D cn=admin,dc=shifteight,dc=org -f astusers.ldif -W
Enter LDAP Password:
adding new entry “uid=rbryant,ou=people,dc=shifteight,dc=org”
Our user has now been imported into LDAP. The next step is to configure Asterisk to connect to the LDAP server and allow users to authenticate and register their phones.
Compiling LDAP Support into Asterisk
With our OpenLDAP server configured and the schema imported, we need to install the dependencies for Asterisk and compile the res_config_ldap module. This module is the key that will allow us to configure Asterisk realtime for accessing our peers via LDAP.
Once we’ve installed the dependency, we need to rerun the ./configure script inside the Asterisk source directory, then verify that the res_config_ldap module is selected. Then we can run make install to compile and install the new module.
Ubuntu dependencies
On Ubuntu, we need to install the openldap-dev package to provide the dependency for the res_config_ldap module:
$ sudo apt-get install openldap-dev
RHEL dependencies
On RHEL, we need to install the openldap-devel package to provide the dependency for the res_config_ldap module:
$ sudo yum install openldap-devel
Configuring Asterisk for LDAP Support
Now that we’ve configured our LDAP server and installed the res_config_ldap module, we need to configure Asterisk to support loading of peers from LDAP. To do this, we need to configure the res_ldap.conf file to connect to the LDAP server, and the extconfig.conf file to tell Asterisk what information to get from the LDAP server and how. Once that is done, we can configure any remaining module configuration files, such as sip.conf, iax.conf, voicemail.conf, and so on, where appropriate. In our example, we’ll be configuring Asterisk to load our SIP peers from realtime using the LDAP server as our database.
Configuring res_ldap.conf
The res_ldap.conf.sample file is a good place to start because it contains a good set of templates. At the top of the file, though, under the [_general] section, we need to configure how Asterisk is going to connect to our LDAP server. Our first option is url , which will determine how to connect to the server. We have defined a connection as ldap://172.16.0.103:389 , which will connect to the LDAP server at IP address 172.16.0.103 on port 389 . If you have a secure connection to your LDAP server, you can replace ldap:// with ldaps:// . Additionally, we have set protocol=3 to state that we’re connecting with protocol version 3, which in most (if not all) cases will be correct.
The last three options, basedn , user , and pass , are used for authenticating to our LDAP server. We need to specify:
• The basedn ( dc=shifteight,dc=org ), which is essentially our domain name
• The user name we’re going to authenticate to the LDAP server as ( admin )
• The password for the user to authenticate with ( canada )
If we put it all together, we end up with something like the following:
[_general]
url=ldap://172.16.0.103:389
protocol=3
basedn=dc=shifteight,dc=org
user=cn=admin,dc=shifteight,dc=org
pass=canada
Beyond this, in the rest of the sample configuration file we’ll see lots of templates we can use for mapping the information in Asterisk onto our LDAP schema. Let’s take a look at the first lines of the [sip] template that we’ll be using to map the information of our SIP peers into the LDAP database:
[sip]
name = cn
amaflags = AstAccountAMAFlags
callgroup = AstAccountCallGroup
callerid = AstAccountCallerID
…
lastms = AstAccountLastQualifyMilliseconds
useragent = AstAccountUserAgent
additionalFilter=(objectClass=AsteriskSIPUser)
On the left side, we have the field name Asterisk will be looking up, and on the right is the mapping to the LDAP schema for the request. Our first set of fields is mapping the name field to the cn field on the LDAP server. If you look back at the data we imported in “Configuring OpenLDAP” , you’ll see that we have created a user and assigned the value of RussellBryant to the cn field. So, in this case, we’re mapping the authentication name (the name field) from the SIP user to the value of the cn field in the LDAP server ( RussellBryant ).
This goes for the rest of the values all the way down, with some fields (i.e., useragent , lastms , ipaddr ) simply needing to exist so Asterisk can write information (e.g., registration information) to the LDAP server.
Configuring extconfig.conf
Our next step is to tell Asterisk what information to load via realtime and what technology to use. Using the extconfig.conf file, we have the option of loading several modules dynamically (and we can also load files statically). For more information about Asterisk
realtime, see “Using Realtime”.
For our example, we’re going to configure the sipusers and sippeers dynamic realtime objects to load our SIP peers from LDAP. In the following example, we have a line like this:
ldap,”ou=people,dc=shifteight,dc=org”,sip
We’ve specified three arguments. The first is ldap , which is the technology we’re going to use to connect to our realtime object. There are other technologies available, such as odbc , pgsql , curl , and so on. Our second argument, enclosed in double quotes, specifies which database we’re connecting to. In the case of LDAP, we’re connecting to the object unit people within the domain shifteight.org . Lastly, our third argument, sip , defines which template we’re using (as defined in res_ldap.conf) to map the realtime data to the LDAP database.
To define the use of sipusers and sippeers from the LDAP server, we would enable these lines in extconfig.conf:
sipusers => ldap,”ou=people,dc=shifteight,dc=org”,sip
sippeers => ldap,”ou=people,dc=shifteight,dc=org”,sip
Configuring sip.conf for realtime
These steps are optional for configuring SIP for realtime, although you will likely expect things to work in the manner we’re going to describe. In the sip.conf file, we will enable a few realtime options that will cache information into memory as it is loaded from the database. By doing this, we’ll allow Asterisk to place calls to devices by simply looking at the information stored in memory. Not only does caching make realtime potentially more efficient, but things like device-state updates simply can’t work unless the devices are cached in memory.
To enable peer caching in Asterisk, use the rtcachefriends option in sip.conf:
rtcachefriends=yes
There are additional realtime options as well, such as rtsavesysname , rtupdate , rtautoclear , and ignoreregexpire . These are all explained in the sip.conf.sample file located within your Asterisk source.
