Delving further into the dark arts of AD FS 2.0 in this post, we look at whr and home realm discovery, together with smart links, and how these assist in claims provider trusts with other organizations (particularly in light of changes in Rollup 2).
Developing a strategy for Home-Realm Discovery (HRD) is an essential part of any AD FS configuration. In scenarios where an organization has multiple claims provider trusts, things tends to get a bit complicated,,,
ADFS 2.0 Rollup 2 contains a fix relating to use of the whr parameter. The Release Notes explain the issue to date:
The whr parameter that is specified by an application for a home realm discovery scenario overwrites the previously set home realm discovery cookie. This causes a user to be redirected to a different identity provider that the user cannot use to sign in when the user uses a different application.
You may recall that, in previous posts, we looked at ways in customizing the use of realm discovery and claims provider selection via the homerealmdiscovery.aspx.cs page. This was done to suppress claims provider selection to make life easier for our users. The link talks about such access scenarios.
In the above scenarios we looked at defaulting the AD FS Proxy to another provider (a strong authentication provider) and removing realm selection options by the use of the Select Home Realm parameter. In the back-end we set the default claims provider to be AD, thereby sending all authentication requests to Active Directory. This conveniently avoided home realm discovery by hard-coding the selection of the claims providers to the strong authentication claims provider on the AD FS Proxy and the built-in AD provider on the back end.
When add additional claims providers to the mix, e.g. federation capable partner organizations, we hit the issue described in the release notes, because suppression of the home realm selection and the whr limitation means that remote users are sent to the strong authentication provider.
To the rescue, the release notes explain:
The Update Rollup 2 for AD FS 2.0 update resolves this issue by not overwriting data in the home realm cookie when home realm information is provided through the whr parameter. To set a home realm cookie that contains the whr parameter when the home realm cookie is not present, set the following configuration in the Web.config file:
<persistIdentityProviderInformation enabled=”true” lifetimeInDays=”30″ enablewhrPersistence=”true”/>
When the setting is configured, AD FS 2.0 will create a home realm cookie with the identity provider that is specified in the whr parameter when the whr request is sent, and when there is no home realm cookie. The whr request does not overwrite the cookie when there is already an existing home realm cookie.
In other words, AD FS 2.0 creates a home realm cookie for the identity provider/issuer specified, if one doesn’t already exist and persists that cookie according to the lifetime specified in the values set in web.config.
For remote access scenarios with partner organizations and trusted claims providers, this provides a nice way to govern access through the use of IdP-Initiated smart links. For the resource partner organization, we continue to allow our logon pages being served up for our users, whilst allowing us to keep a strong authentication logon for our AD FS proxy and default AD provider in the back-end. Additionally, the practical benefits of this fix are more apparent in IdP-Initiated sign-on scenarios, when there are multiple web applications in the resource organization that need to be surfaced.
For example, we have a portal application in Organization A. The application provides an IdP Initiated smart link on its web page to an Intranet SharePoint 2010 application located at Organization B. To complicate matters, other applications are exposed through nested links in the Intranet web application, linking to other claims-aware applications such as SharePoint Teamsites and Organization B wants to make these applications available also to Organization A.
From an access point-of-view, prior to Rollup 2, this became very messy very quickly. A User in Organization A logs on to the SharePoint Intranet web application via an IdP-initated smart link and later in their session try to access the Teamsites web application. The local (resource) AD FS instance will serve up the home realm discovery page and the claims provider drop-down, because the whr parameter does not persist the home realm cookie. If we’ve also suppressed the claims provider in the selection page (on the proxy), by customizing the homerealmdiscovery.aspx.cs, we have a double whammy as the user can no longer access their home realm .. OOPS!
As of Rollup 2, this behaviour is contained because the home realm selection via the whr in the IdP-initated smart link now stores the home realm cookie.
Let’s walk through a use case:
A user in Organization A (e.g:bar.com) clicks on a smart link on their portal (https://portal.bar.com) to access an claims-aware SharePoint Intranet web application in Organization B. This link calls the AD FS instance in Organization B (e.g:foo.com) with the whr parameter set to the ADFS instance of Org A (http://sts.bar.com/adfs/services/trust) and the wtrealm parameter set to the Intranet web application (https://intranet.foo.com).
Here’s the smart link in Organization A:
When clicking on the link, the user is redirected by the Organization B AD FS instance to Organization A, where the user authenticates against their local Active Directory with their Windows token or logon via the AD FS proxy sign-in page (if they’re on the Internet). Following successful authentication, the client is sent back to the Organization B STS, claims are processed, before being redirected to the relying party (SharePoint) for further evaluation. Assuming our claims are set correctly, the user gains access to the SharePoint Intranet web application and because we are running Rollup 2 with the change in web.config, a home realm cookie based on the whr reference is stored.
Now let’s imagine that our user, surfing around on the Organization B Intranet web site, clicks on a link on the Intranet web application which calls another onsite relying party , Teamsites. The Teamsites web application is located at the (example) URL of https://teams.foo.com. This is a different relying party and so the access and claims of the federated identity again need to be validated. Because the home realm cookie this time has been written correctly (through successful logon via the Intranet application), a relying party (RP-initiated) sign-on is now possible and the user can, assuming they are authorized, gain access to the Teamsites web application successfully without being scuppered by home realm discovery.
Prior to Rollup 2, the user would have been faced with the Home Realm Discovery selection screen, or, if we’d suppressed the claims provider, to the wrong home realm.
With the enablewhrPersistence=”true” value set in web.config, courtesy of Rollup 2, the home realm discovery page is now bypassed because the home realm details are stored in the cookie stored during the successful IdP-initated sign-on and RP-initiated sign-on now works.