Friday, November 2, 2012

Lync OAuth Protocol and Confgiuration

What is Server-to-Server/ OAuthentication Protocol?

OAuth2 is an open standard for authorization used by Microsoft Office 2013 Servers.
It allows users to access their private resources (e.g. Lync Contact List, IM Archiving) stored on Servers without having to hand out their credentials, typically supplying username and password tokens instead. Each token grants access to a specific service for specific resources and for a defined duration

OAuth2 standard-based server-to-server trust across all Office 2013 servers
Lync, Exchange, Microsoft Office SharePoint®, Active Directory

In Lync scenarios enabled for:
Unified Contacts, IM Archiving, OWA meeting scheduling

Hybrid Model:

On-Premise Model:

Certificate: token issuer certificate (OAuthTokenIssuer)
must be request able on PKI -

every Web Server Certificate that includes the name of the SIP Domain in the Subject Field can be used as OAuthTokenIssuer Certificate

Configuration Steps for On-Premise Setup:

Start and request a certificate from internal/ external PKI and import the certificate into the computers certificate store.

First Step:
Get-CsCertificate -Type OAuthTokenIssuer
Import-CsCertificate –Identity global –Type OAuthTokenIssuer –Path C:\Certificates\ServerToServerAuth.pfx  –Password "

If a Certificate exists for (e.g. the default certificate) it can be used:$x = (Get-CsCertificate -Type Default).Thumbprint
Set-CsCertificate –Identity global -Type OAuthTokenIssuer -Thumbprint $x

Next you need to activate the PartnerApplication and make the new OAuth Protrol work:
Therefor you copy this script and run save it as ConfigureOAuthScrip.PS1

Script Start---------------------------------------------------------------------------------------------
if ((Get-CsPartnerApplication app -ErrorAction SilentlyContinue) -ne $Null)
       Remove-CsPartnerApplication app

$exch = Get-CsPartnerApplication -ErrorAction SilentlyContinue
if ($exch -eq $null)
      New-CsPartnerApplication -Identity -MetadataUrl -ApplicationTrustLevel Full
       if ($exch.ApplicationIdentifier –ne “00000002-0000-0ff1-ce00-000000000000”)
New-CsPartnerApplication -Identity -MetadataUrl -ApplicationTrustLevel Full
             Set-CsPartnerApplication -Identity -ApplicationTrustLevel Full
$shp = Get-CsPartnerApplication microsoft.sharepoint -ErrorAction SilentlyContinue
if ($shp -eq $null)
      New-CsPartnerApplication -Identity microsoft.sharepoint -MetadataUrl -ApplicationTrustLevel Full
       if ($shp.ApplicationIdentifier –ne “00000003-0000-0ff1-ce00-000000000000”)
             Remove-CsPartnerApplication microsoft.sharepoint
             New-CsPartnerApplication -Identity microsoft.sharepoint -MetadataUrl -ApplicationTrustLevel Full
             Set-CsPartnerApplication -Identity microsoft.sharepoint -ApplicationTrustLevel Full

Set-CsOAuthConfiguration -ServiceName 00000004-0000-0ff1-ce00-000000000000

Script End---------------------------------------------------------------------------------------------------

If your REALM should be different from the Organization Name (EXCHANGE) you need to specify incl. the REALM Parameter:
Set-CsOAuthConfiguration -ServiceName 00000004-0000-0ff1-ce00-000000000000 –Realm ""

Next Step:
Define the MetadataURL:
Lync 2013 Preview:
Lync 2013 RTM:

When you run this script from above, you might receive an error message similar to the following:
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."

This error message typically means one of two things:
1) that one of the URLs specified in the script is invalid (that is, one of your metadata URLs is not actually a metadata URL); or,
2) that of the metadata URLs could not be contacted. If this happens, verify that the URLs are correct and are accessible, and the re-run the script

Last Step:
Verification of configured PartnerApplication settings and verifiy the correct configuration:

Identity              :
AuthToken             : Microsoft.Rtc.Management.WritableConfig.
Name                  :
Realm                 :
ApplicationTrustLevel : Full
Enabled               : True

If you have any questions, please let me know, I will do my best supporting you.


  1. Hi,

    We have lync 2013, sharepoint 2013 and exchange 2010 on premise. Will Oauth work with exchange 2010 and is it supported?


    1. Hi Paul,
      not, OAuth is only supported and even implemented with Office 2013 Server products

  2. Hi Thomas, does the OAuth cert subject name need to match the sip domain exactly, or just include it? For instance, if my sip domain is, would a subject name of be OK to use?

    1. Hi Johnny,
      I have written a wiki article on TechNet:
      This explains it more in detail.

      Generally, the OAuth required like all other certificate the SN/CN as the default SIP domain and a SAN entry which repeats the default SIP domain.
      additional SIP domains must be added to the SAN.

    2. Thanks so much! One more question... if using this in a hybrid environment with O365 for Exchange, would the certificate have to be from a trusted 3rd party CA such as entrust?

    3. Absolute sure, it must be from an trusted certificate provider.