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 utilizing it for several applications: you significantly cut down the administrative overhead of managing your users by placing all their information into a central location.
There are both commercial and open source LDAP servers available, the most popular commercial solution likely being that implemented by Microsoft Windows servers. A popular open source LDAP server is OpenLDAP (http://www.openldap.org). 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.
While a discussion of the installation and configuration
of an LDAP server is beyond the scope of this chapter, 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
located at https://help.ubuntu.com/10.04/serverguide/C/openldap-server.html.
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/1.8/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 restartNow
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.ldifWe can now continue with the
instructions at https://help.ubuntu.com/10.04/serverguide/C/openldap-server.html
and import the frontend.example.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’re going to create a user and add the configuration values that will allow the user to 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" | md5suma7be810a28ca1fc0668effb4ea982e58 -
We’ll insert the returned value (without the hyphen) into the
following file within the userPassword field, prefixed with {md5}:
$cat > astuser.ldifdn: 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: defaultCtrl+D
The one field we should
explicitly mention here is the userPassword field. We require that the
value in the LDAP server contain the password we’re going to
authenticate from the phone with to be in the format of an MD5 hash.
In versions prior to Asterisk 1.8.0, the prefix of {md5} in front of the hash was required.
While it is no longer necessary, it is still recommended.
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 -WEnter 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.
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.
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.
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:
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. Lets 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 the section called “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, etc.) simply needing to exist so
Asterisk can write information (e.g., registration information) to the
LDAP server.
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 the section called “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.
Additionally, you can specify
a fourth argument, which is the priority. If you define multiple
realtime objects, such as when defining queues or sippeers, you can utilize the priority argument to control
failover if a particular storage engine becomes unavailable.
Priorities must start at 1 and
increment sequentially.
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
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.
A peer is only loaded into memory upon registration of the device or placing a call to the device. If you run the command sip reload on the console, the peers will be cleared from memory as well, so you may need to adjust your registration times if that could cause issues in your system.
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.