Single sign-on to Outlook Web Access using PingFederate

One of the most popular Microsoft applications is Microsoft Exchange. Users connect to Exchange for email by running a client such as Outlook on their desktop, ActiveSync on their smart phones, or OWA, which does not require client installation or prior user configuration. OWA supports standards-based identity protocols, primarily WS-Federation. To eliminate any confusion in terminology between the protocol that Microsoft uses, WS-Federation, and the standard SAML terminology that Ping Identity references, the following table assist by mapping the terms used by each vendor:

[/fusion_table]

The following sequence diagram represents the general flow for SSO to OWA using PingFederate:

Preparing OWA for Claims Authentication

On the Client Access Server (CAS), where OWA is running, ensure that .NET 4.5 is installed. After installing .NET 4.5, the Claims to Windows Token Service (c2WTS) should be available in Services. The c2WTS is a feature of Windows Identity Foundation (WIF) that extracts UPN claims from non-Windows security tokens (e.g., SAML tokens), and generates impersonation-level Windows security tokens to access back-end resources such as applications or databases. This is necessary for last mile integration of applications to PingFederate.

The certificate used for signing the WS-Federation tokens by the PingFederate IdP must be shared with the OWA server prior to activating the federation. If the signing certificate is not already trusted by the OWA server (normally via an internal domain Certificate Authority), the certificate must be installed as a Trusted Root Authority in the OWA’s machine certificate store. This is especially true if the certificate is a self-signed certificate. The certificate’s Common Name (CN) should also be in the format of a FQDN. In my personal experience, using short names, such as “localhost” for testing can be problematic with certificate validation. The Microsoft Windows Identity Foundation (WIF) libraries (built into .NET 4 and later) check for valid names by examining the CN value along with the SHA-1 thumbprint.

Configuring OWA to Integrate with PingFederate Microsoft

OWA naturally assumes that external claims-based authentication will use ADFS, however, PingFederate can be substituted by defining it as the ADFSIssuer. Below are the PowerShell commands to simplify the configuration:

1. Logon to the Exchange CAS (OWA) server.
2. Open the Exchange PowerShell command window.
3. Set the AdfsAudienceUris names for OWA. These variables correspond to the SP Connector configured in PingFederate as well as the relative path for the “wtrealm” varible in the authentication request. Note that the URs include an array for user-based Outlook Web Access but also access to the Exchange Control Panel for administrators.

   $uris = @(“https:///owa/”,”https:///ecp/”)

4. Set the Organization configuration for the CAS server to use for claims-based authentication. This will include the PingFederate IdP WS-Federation endpoint (/idp/prp.wsf), the URIs from the previous step, and the SHA-1 version of the thumbprint used to sign the Assertion.

   Set-OrganizationConfig -AdfsIssuer “https:///idp/prp.wsf” -AdfsAudienceUris $uris –AdfsSignCertificateThumbprint ““

5. The next two commands will set ECP and OWA to use ADFS Authentication (PingFederate acting as the IdP) and will disable other ECP and OWA authentication methods.

   Get-EcpVirtualDirectory | Set-EcpVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

   Get-OwaVirtualDirectory | Set-OwaVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false -OAuthAuthentication $falseNote: The trailing forward slash (“/”) in the above $uris variable is very important. This MUST match the relative path that OWA will set as the ReturnURL (ru parameter) in the Authentication request.

OWA Configuration Breakdown

Using an HTTP tracer tool like Fiddler, you can see the full GET request in the HTTP header. It will look something like this.

GET https:///idp/prp.wsf?wa=wsignin1.0&wtrealm=https%3a%2f%2f%2fowa%2f&wctx=rm%3d0%26id%3dpassive%26ru%3d%252fowa%252f&wct=2016-01-21T16%3a46%3a18Z

With the encoding, this URL looks complicated, but it is simply passing parameters that PingFederate will use to select the SP Connector. Below is a summary of these parameters:

[/fusion_table]

After testing, if you receive a “BadURIorAudience” error from OWA, check the SAML Assertion for the audience value that PingFederate’s IdP is sending in the assertion. Make sure that theissuer includes the trailing forward slash (‘/’). The OWA server will use the URI from the audience to match the wtrealm name sent from the authentication request.

Another possible problem will be the thumbprint configured for Claims authentication. The thumbprint alphabetic case is irrelevant, but the thumbprint should not contain spaces. You can grab this value from PingFederate by examining the certificate in the Digital Signing and Decryption Keys and Certificates Admin interface. Also, ensure that the certificate is fully trusted by the CAS server. By placing the certificate in the computer’s Trusted Root Certification Authorities container, it will be fully trusted even if it is self-signed or if the issuing authority is not trusted by the server.

Lastly, build the PingFederate SP Connector as a WS-Federation IdP connection. If you do not see this option available when creating the connector, add the WS-Federation role to the PingFederate IdP in Server Settings. Once complete, create the SP Connector per the specifications of the OWA configuration. The most important configuration parameters are the Partner’s Entity ID (Connection ID) and the ACS endpoint where OWA will consume the assertion and translate it to claims. The SP Connector ID must match the AdfsAudienceUris parameter configured with PowerShell. In addition, the ACS endpoint should be directed to the FQDN of OWA, which also typically matches the AdfsAudienceUris parameter configured in the PowerShell command.

While the configuration is straightforward, the devil can be in the details, for example, using a trailing slash in the audience or SP Connector Partner ID can break the integration. Following these steps to configure PingFederate OWA can reduce errors, eliminate frustrations and accelerate deployment. If you have comments or questions, please contact us!