An organization using a directory service such as Active Directory can set up Switchvox so its phone-users can authenticate (log in) with their username and password from that directory service. LDAP/LDAPS is the protocol used for this communication with your directory service. This Switchvox feature allows administrators to have a single, centralized repository for managing and storing passwords; there is no need to keep disparate passwords in Switchvox.
A Switchvox administrator uses Setup > Extension Settings to specify the Active Directory host information where users and passwords are managed, and uses Setup > Extensions > Manage to specify the Username of the person on each phone extension.
Important information about Usernames: When a Switchvox is in LDAP mode, a Username setting is available on a SIP Phone extension’s Profile tab (it can also be set using the Import Extensions tool). Username must always be unique (locally and across Peered Switchvoxes), so it is clear which extension is associated with the user in your directory service. Each extension on Switchvox that can be logged into by a user requires a corresponding entry in your directory service.
You may also have an extension that is not associated with any user in your organization, which might be used for a common area (such as a break room or overhead speaker). Such extensions will likely not have a corresponding entry in your directory service and therefore you will not have a username to enter for these extensions. These extensions cannot be logged into by a user because they do not have a username; however, an Administrator can still log into the user portal for these extensions by clicking on the Login as this User button from the list on Setup > Extensions > Manage in /admin.
External Authentication
Selecting the LDAP User Authorization Type displays the required fields you enter to set up Switchvox to use LDAP. Local is the default user authorization type and indicates passwords are managed within Switchvox. After entering the LDAP information, we recommend you use the Test LDAP settings button to validate the settings. When the information is ready, click the Save Extension Settings button.
- User Authorization Type--Select LDAP. This displays required information fields for your directory service host.
- Server--Enter the server name. Note: the server name must begin with ldap:// or ldaps://
- Bind DN--Enter the bind DN, which is an object that Switchvox binds to inside LDAP to request and receive user authentication.
- Bind Password--Enter the password for the bind DN.
- UID Attribute--Enter the name of the field/attribute in your directory that contains the usernames Switchvox will use to authenticate the extensions. A value in this field/attribute in your directory must match exactly to a value in the Username field in a Switchvox SIP Phone Extension. (The Username field is available while Switchvox is in LDAP mode.) The field must contain values that are unique across your directory server. (We can't tell you what this field/attribute is in your directory, but possibilities include userPrincipalName, sAMAccountName (for older versions of Windows), or uid (if you're not using Active Directory).
- Base DN--Enter the point from which a server will search for users.
Example Screenshot:
Testing LDAP Settings
We strongly recommend that you test your LDAP settings with a valid username and password combination. Try using any username and password that you know should authenticate (you could use your own username and password, even if you don’t have a Switchvox extension), so you can ensure the process works. If it does not authenticate, the tool issues an error message. Remember this function only tests that you are able to authenticate with that username and password to your ldap server; it does not verify that the username matches one belonging to a SIP Phone Extension. The following are possible errors in the information:
- Could not reach the server (this could be an incorrect server address or port, or a network issue.)
- Not allowed to authenticate the user (Bind DN or Bind Password may be wrong)
- Username not found (UID Attribute may be wrong, or a Username doesn’t match)
- Username and password combination were incorrect
Also, ensure that your firewall is allowing traffic between Switchvox and your directory service. Typically, LDAP uses port 389 and LDAPS uses 636.
LDAP and SSL
Your LDAP server probably requires a secured SSL environment for HTTPS communications. If the LDAP test is failing, be sure that Switchvox and the LDAP server are both configured with the correct information. For more about SSL and HTTPS, see
HTTPS and SSL Certificates.
Saving Extension Settings in LDAP Mode
IMPORTANT: After you click Save Extension Settings, your phone-user’s passwords are cleared, and they are no longer managed, stored, or discovered within Switchvox. You can switch back to Local mode; however, if you do, each phone-user will need to use the Reset Password tool (or you can set a new password for each SIP extension).
SIP Phone Extensions: the Username Field
When Switchvox is in LDAP mode, each phone-type extension has a Username field. This should contain that person’s unique username in your directory service. This field is not available in Local mode.
Example of how the extension Profile Information looks with LDAP on:
Your directory service may refer to it as something other than Username. It might be called user or account (or something else entirely), but Switchvox refers to that unique ID for each person as Username. (How your directory service refers to this should be indicated in the UID Attribute field.)
In LDAP mode, the directory service’s username is used for authentication, not the extension number. So now a person logs into Switchvox with their directory service’s username, as opposed to their extension number.
The Username field can be changed in each phone-type extension’s Profile tab, or you can use the Import Extensions tool on Setup > Extensions > Manage. For more information about the Import Extensions tool, see SETUP-EXTENSIONS-MANAGE-IMPORT-EXTENSIONS (6.6). Here are some examples of a .csv file for importing extensions with username:
SIP Extensions File with Username
ext,fname,lname,username,email,title,location,password,voicemail_password,phone_password,digium_phone_mac_address
100,Joe,Smith,jsmith,jsmith@home.com,,,!@#$12As,1000,,0019159C0646
101,Jane,Doe,jdoe,jdoe@home.com,,,!@#$12As,1010,,0013174C5532
102,Dan,Jackson,djackson,djackson@home.com,,,!@#$12As,1020,,000fd30ba0a0
SIP Extensions Updates File to Add Username
ext,fname,lname,username,email,title,location,password,voicemail_password,phone_password,digium_phone_mac_address
100,,,jsmith,,,,,,,
101,,,jdoe,,,,,,,
102,,,djackson,,,,,,,
LDAP Channel Binding and LDAP Signing
ADV190023: Microsoft Guidance for Enabling LDAP Channel Binding and LDAP Signing
On March 10, 2020, Windows updates will add options for administrators to harden the configurations for LDAP channel binding on Active Directory domain controllers.
Hardening AD security in this way should not impact Switchox's ability to authenticate against the AD domain. But in an abundance of caution, we recommend that you apply the update, then monitor the new log events. If Switchvox does not trigger any events, then it should be safe to proceed with the steps to harden AD security using the new Windows features for enforcing LDAP signing and LDAP channel binding.
