Automating Home Realm Discovery (HRD)
In most common Identity Federation scenarios, there are multiple external Identity Providers (IdP), but the relying party (RP / claims aware app) depends and trusts only one STS (Security Token Service) to provide the claims.
This STS is known as the Federation Provider (FP) or R-STS (Relying Party STS). So when you access the relying party application, it will redirect you to the R-STS (the only STS it knows) to get authenticated, now since (typically) R-STS / FP is not an Identity Provider (IdP), it will (typically) provide you a list of trusted identity providers so that you can choose the one you wanted to get authenticated with.
But in some cases, especially if you are using the application frequently and you know which IdP you wanted to get authenticated with, you would like to avoid that annoying extra step / screen where you need to choose the IdP and wish the system knew it instead of asking every time.
Well there are multiple ways of achieving the same, below are some of the options:
1. The (default) cookie based approach
The default behaviour is that, the first time you select the Identity Provider and get successfully authenticated, a persistent cookie is created that is valid for 30 days. This means you don’t need to worry about selecting the identity provider for the next 30 days, however this can have the following issues:
a. Every time you clean up / clear the cookies, you will need to set it up again
b. If you want to change to another Identity Provider, you will need to clear the cookies or for temporary purposes use an “In Private” browser session
This default behaviour can be modified, in ADFS’s web.config located (default) at C:inetpubadfsls
<persistIdentityProviderInformation enabled=“true“ lifetimeInDays=“30“ />
You can either modify the lifetime of the cookie or make it a non-persistent cookie in which case, it will ask you for home realm discovery on every new browser session (not what we want)
2. Using the WHR parameter within the queryString / URL
Another approach is to use the WHR parameter in the URL / queryString when accessing the relying party as shown below:
ADFS by default understands the WHR parameter, however, you need a paste a little code in your global.asax of the relying party for WIF to go the magic. Here is the code that will do the trick:
void WSFederationAuthenticationModule_RedirectingToIdentityProvider(object sender, RedirectingToIdentityProviderEventArgs e)
string strWhr = HttpContext.Current.Request.QueryString[“whr”];
if (strWhr != null)
e.SignInRequestMessage.HomeRealm = strWhr;
What you are doing here is basically hooking up your code to the event WIF raises just before it calls out / redirects to the FP. In the code snippet above you are checking to see if the URL contains a querystring with a WHR parameter, if so you assign the value of that parameter to the HomeRealm property of the SignInRequestMessage.
3. Hardcode the IdP’s endpoint within RP’s web.config
I would like mention here that the last two approaches we saw are useful for the end-user or the client browser to customise the behaviour, where each end user might want to choose a different identity provider for the same relying party. However, if you have a scenario where the users of your relying party can be authenticated by a particular identity provider, then you may have to resort to the technique mentioned in this section.
You might ask…, “…well, if the RP can be authenticated by one identity provider only, then why are we even providing a HRD page and choice of multiple Identity Provider?…”. Well you should be conscious of the fact that in a real production environment the Federation Provider may not be dedicated to your relying party alone, maybe it is an Org-wide FP and multiple RPs are using it to federate with various identity providers, but your scenario might demands that the FP redirects the user to a particular IdP only and not provide an option to choose from.
You can configure your relying party to automatically pass through the FP and get redirected to the designated IdP by assigning the IdP endpoint using the HomeRealm attribute of the <wsFederation> node in the <federationConfiguration> of the web.config as shown below:
<cookieHandler requireSsl=“true“ />
4. Customise the HRD page.
Finally (for ultimate flexibility) you can modify the HomeRealmDiscovery.aspx file and the associated HomeRealmDiscovery.aspx.cs file and provide your own custom logic.
Or you can leave them intact as is, and provide your own custom HRD page and point to it from the ADFS web.config by modifying the element shown below.
<homeRealmDiscovery page=“HomeRealmDiscovery.aspx“ />