Using PingFederate to bypass Microsoft Home Realm discovery page

The solution will send the tenant information to Microsoft Azure to avoid the “Home Realm Discovery Page”. In our case, we were able to utilize the flexibility of PingFederate as a token mediator between the application and the Identity Provider. For this blog article, the final token delivered to the application is immaterial but could be OpenToken, SAML or something else. As it pertains to this article, we will focus on the authentication portion of the transaction where the user is requested to provide realm information.

Primer

In a SP-initiated SAML transaction flow, the Service Provider can either redirect the user to an endpoint on the Identity Provider to begin the sequence between the two providers, or make a SAML Request to the Identity Provider as a POST or REDIRECT bind. The latter approach is well defined per the OASIS SAML specification, which includes details on properly formulating a XML messaging document containing an AuthnRequest. In PingFederate, the AuthnRequest form was not configurable beyond the standard IdP Connection configuration until PingFederate version 8.1. As of this writing, PingFederate is one of very few SSO providers that have this capability.

Microsoft Authentication

By default, the first time a user authenticates to Microsoft Azure AD in a browser session (based on session cookies), Microsoft presents a “Home Realm Discovery Page” asking for users to identify their account in order to source their Identity Provider, by either typing in their user principal name or selecting a cached account from a previous logon. This is a somewhat confusing page as users who expect a true single sign-on experience wonder why they are being prompted for” authentication.”

While there are ways to bypass this logon for IdP-initiated and other protocol types, for SP-initiated SAML, Azure AD doesn’t have this built-in capability. However, there is a method to bypass the Home Realm Discovery page if the SP is capable of sending a “Scoping” element with certain parameters inside the AuthnRequest. Many SP providers do not support this capability and PingFederate does not OOTB, but it now has the capability to support customization of the AuthnRequest via OGNL expressions. Further, PingFederate can tap into the SDK to utilize Java and custom libraries to perform extensive customization.

PingFederate Solution

In order to create the custom AuthnRequest with OGNL, the Expression Manager must be enabled in the PingFederate config store. This change occurs outside the PingFederate console in the file system. To enable OGNL capability in the Admin console, perform the following steps.

1. Edit the file org.sourceid.common.ExpressionManager.xml located in pingfederateserverdefaultdataconfig-store

2. Set the “evaluateExpressions” parameter to “true.”

3. Restart the PingFederate Runtime Engines.

Now that OGNL expressions are available, advanced configuration options will be visible on the SSO Service URLs page of the IdP Connection as well as the ability to create more sophisticated SP Connection attribute contract fulfillment if desired.

Upon logging into the PingFederate Admin console, create or edit an existing IdP Connection In the Protocol Settings/SSO Service URLs sub section, an Advanced Customization link is now available.

To create the custom AuthnRequest, click “Show Advanced Customizations.” Select the Message Type “AuthnRequestDocument” and type an OGNL expression similar to the following.

In the above expression, the AuthnRequest document is modified to add a new Scoping element with an IdP List indicating the specific IdP Entry to add.

The original AuthnRequest looked similar to the following.

Now, with the addition of the OGNL expression, there is also a Scoping element with an IdP Entry pertaining to the Identity Provider we are requesting for authentication.

When Microsoft Azure AD receives this request through browser SSO, Microsoft will see that the request is pertaining to a specific Identity Provider per the tenant identifier (ProviderID) and tenant Name. Since Microsoft will now have the IdP tenant information directly from the Service Provider, it will not need to make a request to the user for the Identity Provider and will bypass the Home Realm Discovery page.