Tag Archives: Home Realm Discovery

AD FS 2.0 Rollup 2 and WHR – We Has Resolution (Part 2)

In the previous post we covered WS-Federation whr changes in AD FS 2.0 Rollup 2.  With this fix in place and enablewhrpersistence set in our web.config,  let’s look at scenarios on how the configuration can be used to manipulate home realm discovery in greater detail. 

Our mythical ‘Foo’ organization consists of an existing AD FS 2.0 proxy/farm setup and two claims providers configured:

  1. default AD provider
  2. third-party claims provider providing strong/two-factor authentication (2FA) to Foo users

Foo has recently engaged in a number of collaboration projects with three other companies: Fee, Fie and Foe. Wishing to further cement these relationships, Foo has elected to setup federation trusts with each of them, and provide access to their local WS-Federation web applications.  The Foo Security Officer, however, has decided that other home realms should not be visible within AD FS in the drop-down box of the home realm discovery page.  All RP-initiated requests via the AD FS proxy must go to their third-party two-factor authentication (2FA) claims provider.  This requirement, however, conflicts with the need to service federated logon for other organizations.

Given the above constraint, we have a number of options:

  • Use an additional farm;
  • Customize the home-realm discovery pages and logon experience on the existing farm to support the desired user experience for third-parties;
  • Customize the relying party(s) to route the whr request;
  • Use out-of-the-box features.

Not being much of a code monkey, let’s look at options out-of-the-box. With the new configuration, there are now five claims providers Foo has to deal with.

  1. Active Directory Claims Provider (0)
  2. 2FA Claims Provider (1)
  3. The Fee Organization Claims Provider (2)
  4. The Fie Organization Claims Provider (3)
  5. The Foe Organization Claims Provider (4)

Foo AD FS Proxy Customization

For external access, as per security requirements, only the 2FA claims provider should be visible directly from the proxy, making it the default selection for external access. This is arranged  on the AD FS Proxy side by modifying the homerealmdiscovery.aspx.cs file and then removing the claims providers, as eligible entries, from the Page_Init section of the file. We need to process their removal in reverse order, starting with the last claims provider in the list, then the next to last etc., until we have the desired CP . For example, with five claims providers, the following changes are made:


We’re left with claims provider (1) in this example, the 2FA provider. Note the order may vary according to order created.

Once this has been done, the following line also needs to be added :

SelectHomeRealm( PassiveIdentityProvidersDropDownList.SelectedItem.Value );

This will default logon to the 2FA provider claims provider at the AD FS proxy. 

Foo AD FS Farm Customization

For users with managed clients/corporate PCs in the Foo organization, we need to ensure that realm discovery is also handled in the right manner. 2FA is not a requirement internally, but SSO via the Windows logon token is desirable. While we covered this in a previous post, it’s worth repeating here. On the AD FS Farm, the Page_Init section of the homerealmdiscovery.aspx.cs file needs to be set so that it defaults realm selection to the Active Directory claims provider.

SelectHomeRealm ( PassiveIdentityProvidersDropDownList.SelectedItem.Value );

If this is not set, then all claims providers are visible on the home realm discovery page, something which we don’t want to trouble internal users with on the corporate network. 

With persistence enabled on the home realm discovery page (of the Proxy), a user may fall foul of cookie handling if he/she works from home, logs on and then returns to work, only to discover that the cookie has persisted and the browser points them to the 2FA provider.  We can temper the cookie behaviour of the AD FS proxy by disabling persistence within the web.config on the AD FS farm.

<persistIdentityProviderInformation enabled=”false”/>

Connecting Organizations

For users from other organizations connecting to Foo; e.g. Fee, Fie and Foe, we rely on smart links from AD FS instances in these organizations to route the request and for the home realm cookie to be written correctly via the whr parameter. Note that these claims providers could also use non-Microsoft identity providers/issuers, such as a Juniper SA (SAML) or a PointSharp WS-Federation Identity Provider, such as . 

While useful, smartlinks are not without limitations.  Firstly, we’re assuming the relying party is a WS-Federation based web application.  If the relying party is a SAML 2.0 web application then the WS-this approach is not applicable. The solution described here does not work and a different type of customization is required. More on this in a future post. The second limitation concerns users from claims provider realms bookmarking Foo (federated) web applications. Should the home realm cookie expire, accessing a bookmarked RP web application will fail as it routes them to the 2FA provider. While Rollup 2 made persistence via whr possible, we need to workaround this shortcoming. We could set the lifetimeInDays value of the cookie in the homerealmdiscovery.aspx.cs of the Foo Proxy to such a high value that this would not be an issue.  Sadly, this is not entirely foolproof either. Browser configuration for users in partner organizations, e.g. Delete browsing history on exit,  may influence whether the realm cookies are retained or not.  Whatever setting is opted for by the resource organization (Foo) is something that will need to be communicated with partner organizations.

AD FS 2.0 Rollup 2 and WHR – We Has Resolution!

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.