Lync Integration with Polycom SIP Phones
December 5, 2011 by Jeff Schertz · 97 Comments
Polycom has recently announced native Lync support for a wide variety of standard SIP phone devices which all run on the same Polycom Unified Communications Software (UCS) software release. This means that the large variety of SoundPoint IP, SoundStation IP, SpectraLink Wireless, and VVX Business Media Phones can all now natively register directly to Lync Server, adding a variety of choices beyond the purpose-built CX device family, including the first WiFi endpoint supported for Lync 2010 Server.
The official Polycom Lync integration documentation covers in detail how to handle provisioning of the standard SIP phones en masse as well as how to further define Lync integration settings. Additionally there is also a feature profile document which also lists the supported features and devices.
The documentation reference above is targeted primarily at the administrator experienced in industry standard SIP phone provisioning and configuration. But all of this can be a bit overwhelming to the traditional Lync administrator who has thus far only dealt with Windows softphones and Lync Phone Edition devices which have a completely different deployment process. Thus for the tire kickers and pilot testers out there this article will simmer down all of those provisioning steps into the most basic components and outline exactly how to register a single device to a Lync server.
The basic Lync Integration capabilities are introduced in the UC 4.0.1 firmware release which runs on various SoundPoint IP, SoundStation IP, SpectraLink, and Business Media Phones. Versions prior to 4.0.1 are incapable of registering to Lync and are unsupported.
Due to the scope of this topic a clear assumption is made that the SIP phone used with these configuration instructions is currently running the required software. The UC Software Provisioning Best Practices white paper is a good place to start research on the device update process if not already familiar with it.
The most basic requirement for any client or device to natively register to Lync is the ability to support TLS communications. Normally the connecting endpoint must trust the certificate authority which issued the server certificate that is used by the Lync registrar service. Typically the Windows Lync client will automatically trust the Lync server as that server’s certificate is most often issued by an internal Enterprise Windows CA. The Enterprise (versus Standalone) term is important as that indicates that the Root CA’s certificate (thus its public key) is AD-integrated by default and all domain members, servers and workstations alike will inherently trust that CA. Furthermore native Lync Phone Edition devices will automatically download this same certificate during initial provisioning processes.
Retrieving the CA Certificate Hash
In order to configure this same trust relationship with the Polycom SIP phones the CA certificate will need to be manually provided to the phone as part of the provisioning process.
Note: Be aware that this does not mean the Lync server certificate itself is used, which is a common misunderstanding. In order to manually build the trust the endpoint must trust the server certificate which was issued to the Lync server, but installing that same Lync server certificate itself into the phone does NOT satisfy the requirements. The connecting endpoint must instead trust the Certificate Authority server which originally issued that certificate to the Lync server (e.g. a Root CA server), by which provides a transitive trust to all certificates issued by that CA (including the Lync Server certificate).
So make sure that the certificate hash which is retrieved is that of the Root CA, and not the Lync server certificate itself.
This preparation is a one-time process as once the certificate data is retrieved it remains as part of the configuration data for any additional device provisioning.
The first step is to identify the certificate currently applied to the Lync Server so that the proper CA certificate is exported.
- On the Lync Server in which the phones will be configured to register to launch the Lync Server Management Shell and run the Get-CsCertificate cmdlet.
Although all usages should normally have the same certificate assigned look for the Use: Default entry to identify the certificate assigned to the SIP registrar on the Lync Server. This usage will show the Issuer as well as the certificate Subject,
With the issuer and certificate information validated then the certificate must be exported to a text file so that the raw hash text can be accessed.
- On the same Lync Server open the Microsoft Management Console (mmc.exe) add the Certificates snap-in and manage the Computer account of the Local computer.
- Expand the Personal store, then Certificate store and open the server certificate used by Lync (e.g. lync.schertz.local) and select the Certification Path tab.
- Select the root certificate at the top of the tree and click View Certificate. This will open the root certificate for the CA which issued this server certificate.
- Select the Details tab in the new window and verify the Subject Name matches the CN field from the Issuer value in the previous Get-CsCertificate output. Click the Copy to File button to launch the Certificate Export Wizard.
- In the export wizard select Base-64 encoded X.509 (.CER) as the Export File Format.
- Save the exported file (e.g. c:RootCA.cer) and keep this file handy for later, as a configuration step in the next section will require the contents of this file.
Now that the certificate information has been retrieved then the next step to configuring a standard SIP phone is to prepare an XML configuration file with all of the Lync-specific settings which will be imported directly into the phone using the web management interface.
Creating a Device Configuration File
The following text can be used to create a sample XML configuration file which can customized and then imported directly into the phone to provision all of the required Lync-specific settings. This text includes some attributes defined with the proper values, some using sample values, and some with null values which will be populated in a later step.
- Copy the text in the quote box below and save it to a new text file called lync.cfg.
<profile reg.1.address="email@example.com" msg.mwi.1.callBack="sip:firstname.lastname@example.org;opaque=app:voicemail" />
<registration voIpProt.server.1.address="lyncserver.contoso.local" sec.TLS.customCaCert.1="" sec.TLS.profileSelection.SIP="ApplicationProfile1" reg.1.auth.useLoginCredentials="1" voIpProt.SIP.mtls.enable="0" voIpProt.server.1.specialInterop="lync2010" voIpProt.server.1.transport="TLS" voIpProt.SIP.allowTransferOnProceeding="0" />
<features feature.presence.enabled="1" feature.messaging.enabled="1" msg.mwi.1.callBackMode="contact" roaming_buddies.reg="1" />
<media sec.srtp.require="1" sec.srtp.key.lifetime="2^31" sec.srtp.mki.enabled="1" sec.srtp.mki.length="1" sec.srtp.holdWithNewKey="0" sec.srtp.resumeWithNewKey="0" voice.audioProfile.G7221.24kbps.payloadType="112" voice.codecPref.G7221.24kbps="5" voice.codecPref.G7221.32kbps="0" video.iFrame.delay="2"></media>
As editing raw XML can be a little tricky and the above text is clearly not fun to read through it is suggested to use an XML editor, like Microsoft’s XML Notepad 2007 to manipulate the content once it is saved as a text file.
- Open the lync.cfg configuration file in an XML Editor and expand the root branch to view each child branch and all of the individual elements.
This template is divided into a few branches which are totally irrelevant to it’s actual operation. Only the attribute names and values themselves are parsed by the device when the configuration file is read-in, so if this sample template is compared to any other cfg files that comes from Polycom or other sources then the branch names (e.g. profile, features) may be completely different. It is important to understand the structure of the file is not important and the branch order and naming in this sample was simply created to group the static settings apart from the user-specific and organization-specific settings. By using this template only the first 4 parameters need to be modified to work with any Lync environment.
Updating the Configuration File
The first group of settings under the Profile branch are user-specific and would be the only values changed when importing into multiple phones in the same environment.
- Change the reg.1.address attribute to include the primary SIP address of the desired Lync user (e.g. email@example.com). This setting defines the Lync identity of the specific phone that the configuration file is imported into.
- Update the msg.mwi.1.callBack attribute to use the same SIP address as above, retaining the request of the URI as shown. This setting is used by the device to retrieve the user’s voicemail from Exchange UM.
The second grouping of settings under Registration contains the only other settings which must be modified and these would be global across all devices in the environment so they only need to be configured once. These include providing the CA certificate hash as well as the Lync registrar name. Afterward the template file can be duplicated and only the previous two user specific values would need to be updated for use with a different device.
- Open the RootCA.cer file (exported in the first section of this article) with Notepad and then copy the entire contents of the file to the clipboard (including the BEGIN and END lines).
- Paste the clipboard contents directly into the sec.TLS.customCaCert.1 attribute in the configuration file making sure not to add any unwanted spaces, carriage returns or characters.
- Update the voIpProt.server.1.address attribute to use the Lync registrar FQDN for the specific environment. This can be a Standard Edition or Enterprise Edition Front End server or a Director server. (Native registration directly to an Edge Server is not yet supported as ICE compatibility for media sessions will be provided in a future release of the UC software).
- Save the changes to the configuration file and store in a location
Importing the Configuration File
For this example a Polycom SoundPoint IP 650 SIP handset is used although the steps are similar for any supported device running the UC 4.0.1 software. A standard web browser is used to to remotely connect to the phone to import the configuration file.
- Retrieve the current IP address of the phone by navigating to Main Menu > Status > Network > TCP/IP Parameters.
- To access the Polycom Web Configuration Utility for the phone simply enter http://<IPaddress> in a web browser using the IP address of the phone.
- Enter the Admin device password and then navigate to the Utilities > Import & Export Configuration menu.
- In the Import Configuration section select Choose File and browse to the customized lync.cfg file and then click Import.
A response of “Configuration file imported successfully” should be reported almost immediately, followed by the phone rebooting itself automatically.
Storing User Credentials
After the device is finished rebooting the username portion of the SIP address should be displayed in the primary line soft key tag. Additionally a status message of “Login credentials failed, Offline” should be reported on the device’s display.
- From the Main Menu select Settings > Basic > Login Credentials and then enter the Active Directory user credentials for the associated Lync user originally assigned in the configuration file. The Domain field should be populated with the NetBIOS name of the AD domain in which the user account is stored in (e.g. SCHERTZ). The User field is the sAMAccountName of the desired user account (e.g. jeff).
- Press the Submit key and registration to Lync should be reattempted automatically.
- Return to the home screen and if the registration was successful then the previous status error should no longer be displayed and some of the Lync contacts will be shown in the remaining line buttons.
Lync Feature Integration
The official documentation covers each of the supported features within the 4.0.1 software release, but to demonstrate the integration here are a few of the more common tasks a typical Lync user might perform from their phone.
- To control the Lync user’s current presence state press the MyStat button to view or change the current presence state.
- To view the user’s Lync contact list select the Buddies button. The device screen capture below shows different contacts in various presence states as indicated by a text label and unique icons.
- To retrieve voice mail messages press the Messages button and then open the Message Center and select Connect to place a call to the Exchange Subscriber Access number. Also note the Missed Call notification and (not in screenshot) the illuminated MWI lamp on the handset when a new Exchange UM voicemail is pending.