The Lync 2013 Preview Unified Contact Store (UCS)

This blog post takes a first look at the Lync 2013 Preview Unified Contact Store feature from a user perspective, answers some key high level feature questions, and gives some important tips for configuring this feature.

Note: all of the information below is applicable to the Lync Server 2013 Preview and Exchange Server 2013 Preview. It is subject to change when both of these products are released in their final form, but as far as I know it is applicable to the RTM versions.

What is The Unified Contact Store?

Much has already been written about the Unified Contact Store. In a nutshell it is a feature which allows Lync 2013 users to store their contact list in their corresponding Exchange 2013 mailbox. The Exchange ‘store’ in this case manifests itself to the user as a separate contact folder in their Exchange 2013 mailbox. One of the more insightful Microsoft references I have seen on the UCS is the MSDN introduction to the UCS from an Exchange Web Services (EWS) perspective – it provides a great overview of what the UCS can offer the enterprise, including:

  • The ability for organizations to provision an initial set of contacts for Lync users in their enterprise. There is a web service interface that can be used to add IM contacts and groups to a user’s Lync client.
  • A shared contact experience across Outlook, OWA, Lync, Mobile, and any other application that uses the UCS – including custom enterprise contact applications using the Lync client API. For example, a custom application to manage contact lists based on organizational units and departments.
  • The ability to store PEOPLE; not just contacts. This is subtle but important.  It solves the problems of one person having multiple contacts. The unit of storage is a persona. The definition of a persona is: “contacts from different sources that represent the same person are associated with one another, similar” (http://msdn.microsoft.com/en-us/library/exchange/jj190898(v=exchg.150).aspx).

The User Experience

This section provides a first look at the user experience with the Unified Contact Store. If you want to skip ahead and implement it in your lab read Jens Trier Rasmussen’s excellent instructions on NextHop and then read my Installation & Configuration Tips below as a supplement. Do read these installation tips if you are having trouble because there are some good tips to solve some potential sticky lab issues.

Before a User has been Enabled to use the Unified Contact Store (UCS)

The user experience with Lync contact lists before a user is enabled to use the UCS in the Lync Server 2013 Preview is the same as usual. For purposes of this blog post, I have a test user using the Lync 2013 Client Preview with two contacts (one internal and one external to the organization) as shown below:

image

As usual the two contacts stay within Lync and do not get populated to a Contacts folder in the test users Exchange mailbox.

We can also see that the “Contact List Provider” in the Lync 2013 Preview Client (i.e  ctrl + right-click + Configuration Information…) in the screen shot below is set to the Lync Server – this means the user is using SIP against the Lync server to access their contact list (the default behavior):

image

My test user also has the default Outlook contact folder with one external contact in it:

image

How is the Unified Contact Store (UCS) Enabled and Disabled for a User?

Use of the UCS is controlled through the UcsAllowed parameter of a new Lync Server 2013 user policy (CsUserServicesPolicy). The CsUserServicesPolicy can be applied at the Global, Site, or Service scopes (see Set-CsUserServicesPolicy for more information).

To enable the UCS for all users, we will use the following cmdlet:

Set-CsUserServicesPolicy -Identity Global -UcsAllowed:$True

If you wanted to enable UCS for just one user, you can use the Tag scope in the Lync Administrator Shell as follows:

New-CsUserServicesPolicy -Identity “UCS Enabled Users” -UcsAllowed $True
Grant-CsUserServicesPolicy -Identity “<User Name>” -PolicyName “UCS Enabled Users”

The User Experience After Being Enabled for the Unified Contact Store

After being enabled, the next time the user signs-in, they will get the new UCS setting from in-band provisioning. The first time the client gets the UCS enabled setting it will tell the Lync 2013 server to migrate his/her contacts to the a newly created ‘Lync Contacts’ folder in their Exchange 2013 Server Preview mailbox.

When the migration is complete, the Lync 2013 Preview client will then prompt the user to sign-out and back-in again to access their contacts via EWS to the Exchange 2013 Server as follows:

image

Note: I have found this can take up to 8 minutes in my lab – even with a small number of contacts.

Where are the Lync Contacts Stored in Exchange 2013?

After being enabled for UCS our test user has a new Outlook Contacts folder called “Lync Contacts” and both the external and internal sample contacts from the test users contact list in the Lync client are migrated there, as shown below:

image

I was surprised to see the internal contacts migrated over since they will likely be in the Outlook GAL. Perhaps this behavior is just in the preview release.

The Lync 2013 client configuration now shows it is using the UCS as the Contact List Provider:

image

Do Changes in my Lync 2013 Client (Preview) Synchronize with the Lync Contacts Folder?

Yes. Once a user is using the UCS as their contact list any deletions or additions to their contact lists are quickly made via EWS to the Lync Contacts folder in Exchange 2013 and reflected in their Exchange 2013 mailbox contact folder.

Can a Contact be added just to the ‘Lync Contacts’ Folder in Outlook?

No – at least in the preview build. The “Lync Contacts Folder” is read-only and you get an error if you try to add a contact to it within Outlook:

image

Although the Outlook 2013 Preview Client will allow you to edit a contacts details (in the Lync Contacts folders) those changes are not successfully saved.  I am confident this must be an issue in my lab or the preview release and the intended experience is to allow full contact management of this folder in the Outlook 2013 client when it is released.

What Happens if the UCS is Turned-off after Users have been Migrated and are Using it?

After the UCS has been enabled for one or more users and their contacts have been migrated to it, the Lync client will continue to use the UCS – even after it has been turned-off for their Lync account – until a Lync Administrator manually migrates the users contacts back to the Lync server using the Invoke-CsUcsRollback cmdlet.

We can see this in the Lync Management Shell warning when we attempt to turn-off the UCS for all users (global scope) after it has been enabled.

Set-CsUserServicesPolicy -Identity global -UcsAllowed $False

WARNING: Users who have already been migrated to the Unified Contact Store (UCS) or who are about
to be migrated to the Unified Contact Store will not be affected when you disable Unified Contact
Store; instead, those users will continue to have their contacts stored in the Unified Contact
Store. To move these users’ contacts from the Unified Contact Store to Lync Server you must run the
Invoke-CsUcsRollback cmdlet after disabling Unified Contact Store

We can see in the Lync 2013 Client configuration that even though UCS has been turned off, it is still using UCS as the Contact List Provider:

image

After the UCS has been turned-off for a Lync 2013 user and they are migrated back to using the Lync server for their contact list, the “Lync Contacts” folder in Outlook still remains and the contacts are still available in this folder.

Note: in the preview build, after using the Invoke-CsUcsRollback cmdlet I have been unsuccessful in enabling the user again to use the UCS again. I am not sure if this is expected behavior or a limitation or issue with the preview release.

There is a good MSDN article on the rollback process and all the various caveats here: Roll back Migrated Users.

Installation & Configuration Tips

Error while Creating the Lync Partner Application on the Exchange Server 2013 Preview Server

If you experience a “Load balancing failed to find a valid mailbox database” error when using the Configure-EnterprisePartnerApplication.ps1 script on the Exchange server like this one:

image

Check that you have at least one Exchange Server 2013 Preview mailbox store (database) that has the IsExcludedFromProvisioning flag set to False.  If it is $true, which mine was, the Configure-EnterprisePartnerApplication.ps1 script will not be able to find a valid mailbox database to create the Lync Enterprise-ApplicationAccount on.

You can check this flag with the Get-MailboxDatabase cmdlet, and set this to $false on one or more mail databases which will allow mailboxes to be created on it with this cmdlet:

Set-MailboxDatabase “<mailbox database name>” -IsExcludedFromProvisioning:$False

More on this error can be found here: Quick tip: Exclude a mailbox database from automatic mailbox provisioning.

Tip – Use the Verbose Flag in Test-CsExStorageConnectivity Cmdlet to Troubleshoot

Jens Trier Rasmussen mentions using the Test-CsExStorageConnectivity cmdlet on the Lync server to test the ability for the Lync Storage Service to access the Exchange Server 2013 Preview.

In my experience this cmdlet will properly test that communication path but it will just give a pass or fail result. If it fails, no additional error information is provided. You can use the –verbose parameter to get more information when this cmdlet fails.  Here is an example:

> Test-CsExStorageConnectivity -SipURI testUser@mydomain.com -Binding NetTCP -verbose
VERBOSE: Using NetTcpBinding.
VERBOSE: Try to open a connection to storage service using the specified binding. This can take
several minutes before timing out.
VERBOSE: Create message.
VERBOSE: Execute Exchange Storage Command.
VERBOSE: Processing web storage response for ExCreateItem Failure., result=ErrorEwsAutodiscover,
reason=GetUserSettings failed, smtpAddress=testUser@mydomain.com, Autodiscover
Uri=
/autodiscover/autodiscover.svc”>/autodiscover/autodiscover.svc”>/autodiscover/autodiscover.svc”>/autodiscover/autodiscover.svc”>/autodiscover/autodiscover.svc”>https://autodiscover.<domain.com>/autodiscover/autodiscover.svc, Autodiscover
WebProxy=<NULL>, activityId=00000000-0000-0000-0000-000000000000.
VERBOSE: Unhandled response Microsoft.Rtc.Internal.Storage.StoreResponse.
VERBOSE: Is command successful: False.
Test failed.

Also check the Event Log for errors.

Exchange 2013 Preview Auto-discovery Certificate Woes

No configuration would be complete without certificate issues :-) . The default certificate used for the autodiscovery end-point in Exchange is a self-signed certificate. So when you browse to the Exchange autodiscovery service (e.g. at /Autodiscover/Autodiscover.xml”>/Autodiscover/Autodiscover.xml”>/Autodiscover/Autodiscover.xml”>/Autodiscover/Autodiscover.xml”>/Autodiscover/Autodiscover.xml”>https://autodiscover.<domain FQDN>/Autodiscover/Autodiscover.xml) you are likely to see a certificate warning like this one:

image

This will cause a problem when you try setup the Lync Server 2013 Preview PartnerApplication for Exchange. The New-CsPartnerApplication will return an error like this:

New-CsPartnerApplication : Cannot bind parameter ‘MetadataUrl’ to the target. Exception setting
“MetadataUrl”: “The metadata document could not be downloaded from the URL in the MetadataUrl
parameter or downloaded data is not a valid metadata document, error: The underlying connection
was closed: Could not establish trust relationship for the SSL/TLS secure channel.”

Prerequisite – ensure you have a DNS Record for your Exchange Server 2013 Preview Autodiscover Service

Instructions on setting up Exchange autodiscover is out-of-scope for this blog post, but to get the Lync and Exchange 2013 Server integration in a lab, the immediate need is a DNS record that points to your Exchange 2013 host.  Just add an A record for autodiscover.yourdomain.com that points to the IP address of your Exchange Server 2013 Front End (or CAS). I believe you can also use a CNAME record and point to the hostname of the Exchange 2013 server.

Creating an Exchange Server 2013 Server Certificate to Support Exchange Autodiscovery

Once the Exchange autodiscover record is in-place you should be able to navigate to the autodiscover meta data at: https://autodiscover.yourdomain.com/Autodiscover/Autodiscover.xml. Note: the autodiscover metadata URL that the Lync Partner Application uses for the Exchange server OAuth token is: https://autodiscover.yourdomain.com/autodiscover/metadata/json/1.

Out-of-the-box you will likely get a certificate error because the autodiscover name is not added as a Subject Alternative Name (SAN) on the default certificate used in Exchange 2013. You will need to create and assign a new certificate from your lab Certificate Authority.

Here is one way to achieve this:

  1. On your Exchange Server 2013 Front End CAS, open the Exchange Admin Center (EAC) and Navigate to Servers | Certificates.
  2. Select the “+” sign to launch the ‘new exchange certificate’ wizard.
  3. Select the following in the wizard:
    • Create a request for a certificate from a CA
    • Friendly name: enter an arbitrary name that allows you to identify it (e.g. the exchange hostname)
    • * Request a wild-card certificate: No (not necessary for our immediate purpose)
    • Store certificate on this server: Select ‘browse’ and select the hostname of this exchange server
    • * Specify the domains: Select OWA (when accessed from intranet)
    • * Specify the domains you want to be added to this certificate: add the “domain” autodiscover.yourDomain.com
    • Specify information about your organization: fill this out as it applies to you
    • Save the certificate request to the following file:  c:\newCertReq.REQ
    • Note: * = for our immediate internal lab purposes this is appropriate. You may need to select different options for other scenarios such as exposing the Exchange Server 2013 Preview services externally.
  4. Issue the Certificate on your enterprise (or lab) Certificate Authority
    • You can do this either through online (https://ocsmvp-dc/CertSrv) or manually put the certificate request from the step above.
    • Steps to request one online from your enterprise CA:
      • Navigate to your CA’s online Certificate Services (e.g. at /CertSrv”>/CertSrv”>/CertSrv”>/CertSrv”>/CertSrv”>http://<CA_FQDN>/CertSrv)
      • Request a Certificate
      • Advanced Certificate Request
      • Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file, or submit a renewal request by using a base-64-encoded PKCS #7 file.
      • Cut-and-paste the contents from the certificate request file in the previous step.
      • Certificate Template: Web Server
      • Download the certificate in Base 64
      • Save the file to local disk (e.g. c:\certnew.cer)
  5. Complete the certificate request in EAC
    • In the Certificates tab, while focused on the pending certificate you previously created, click the “Complete” link.
    • Specify the issued certificate you saved to disk in the previous step (i.e. \\hostname\c$\certnew.cer)
    • Your new Exchange certificate should now show with a valid status but not assigned to any services.
    • Now edit the certificate and select Services
    • Click IIS to assign it to the IIS service
    • You might want to restart the local IIS services (iisreset) and wait a minute for everything to reset itself.

How do I know all of this worked? If you successfully created and assigned a new certificate you will be able to use the following Exchange Server 2013 Preview web services from another machine with no certificate errors or warnings:

  1. Use the Outlook Web App.  E.g. at https://<Your_Exchange_FQDN>/owa
  2. Use the Exchange Server 2013 Preview Exchange Administration Center (EAC).  E.g. at https://<Your_Exchange_FQDN>/ecp
  3. Browser to the Exchange Autodiscover service: https://autodiscover.yourDomain.com/Autodiscover/Autodiscover.xml

Note: there are different ways to assign this autodiscover certificate. For example, you can use the New-ExchangeCertificate cmdlet to generate the certificate request instead of the EAC.

Tip – a quick way to remotely (and any client or server) look at what certificate is being used on a particular host and port (e.g. port 443 on your Exchange server) is to download and run my Remote UC Troubleshooting Tool (RUCT). Go to the “Certificate Information” tab, enter the FQDN of the Exchange CAS server and 443 as the Port, hit “Go” (which will remotely retrieve the certificate). You can instantly see all the certificate information.  You can also click the “Install Certificate Chain in Local Machine Certificate Store”. ** Remember to “Unblock” the application before you run it (right-click Properties). If you still get a certificate error make sure that your machine trusts the root CA certificate.

Test-CsExStorageConnectivity Fails on the ExCreateItem with ErrorIncorrectExchangeServerVersion

If you try the Test-CsExStorageConnectivity cmdlet to test the ability of Lync Storage Service to remotely access the Exchange 2013 server via EWS, you will likely experience this error:

PS C:\Users\administrator.OCSMVP> Test-CsExStorageConnectivity -SipURI testuser@sipdomain.com
-Binding NetTCP -verbose
VERBOSE: Using NetTcpBinding.
VERBOSE: Try to open a connection to storage service using the specified binding. This can take
several minutes before timing out.
VERBOSE: Create message.
VERBOSE: Execute Exchange Storage Command.
VERBOSE: Processing web storage response for ExCreateItem Failure.,
result=ErrorIncorrectExchangeServerVersion, reason=GetUserSettings failed,
….
VERBOSE: Unhandled response Microsoft.Rtc.Internal.Storage.StoreResponse.
VERBOSE: Is command successful: False.
Test failed.

Check to see whether you have Event-id log errors 32054, 32053, and 32045 in the event log (under the ‘Lync Server’ application node).  Looking at the contents of these errors you will likely see an oAuth authentication failure.

This is a frustrating error because of the wrong error message returned by the Test-CsExStorageConnectivity cmdlet.  The real problem is that the Network Service account that the Lync Storage Service uses does not have access to the private key in used by the oAuth certificate. I found the solution in this Lync Server 2013 Preview Forum posting:

  1. Open MMC and add the “Certificates” Snap-in (Local Computer)
  2. Open Personal | Certificates and find the the Certificate being used for OAuth (use the Lync “Get-CsCertificate -Type OAuthTokenIssuer” cmdlet to find the serial number of the OAuth certificate).
  3. Right-click | “All Tasks” | “Manage Private Keys”
  4. Add Permissions for “Network Service” account (the defaults Full control and Read).

Note: if this was not the problem, test that you can browser to the Exchange Server 2013 autodiscover metadata URL in IE without any certificate warnings or errors (e.g. https://autodiscover.myDomain.com/autodiscover/metadata/json/1).

Tip: if you are having further problems with application pool trusts if you are trying to configure OWA integration, see “When to have a Lync Trusted Application Pool for Exchange OWA IM Integration?” by Jens Trier Rasmussen.

Error While Configuring a Lync PartnerApplication on Exchange 2013

Exchange Server 2013 Preview – Connection to Microsoft Exchange is Unavailable Error

If you are trying to remotely test your Exchange Server 2013 Preview services and getting this error when trying to configure an Outlook 2013 mail profile, make sure you configure the profile using the default “E-mail Account” option in the Add Account wizard and not the Manual Setup. It looks like there is a name resolution endpoint in the Exchange Server 2013 Preview that is not working or implemented yet.

In a lab environment the email address the Add Account wizard initially populates with will likely be a different address than what you want to use for your Exchange 2013 server, but as soon as you modify it, you can modify the name and supply the appropriate password.

Note: You would get the same error in Exchange Server 2013 Preview if you tried to create a new mailbox.

Be Sociable, Share!

12 comments to The Lync 2013 Preview Unified Contact Store (UCS)

You must be logged in to post a comment.