Using Azure AD to land users on their custom login page from within your app

[Alex Simons (AZURE)]

First published on CloudBlogs on Feb, 11 2015

[This post was updated on 3/3/2015 to include details about SAML-P apps]

Howdy folks!

One of the question we're hearing regularly from our developer community is "How can I optimize the sign in experience to my app so that end-users immediately land on the sign-in page for their organization?"

It's relatively straight forward to do this, so I've asked Ariel Gordon, the PM in my team who owns our custom login pages, to walk you through how this works.

Regards,

Alex Simons (Twitter: @Alex_A_Simons )

Director of Program Management

Microsoft Identity and Security Division

---------------------

Hi everyone,

When you build SaaS apps that trust Azure AD for authentication, it's easy to land your users on a customized Azure AD login page or directly on their federated STS page, like ADFS.

You're probably already experienced Azure AD's "two sign-in pages" experience: you visit a website (say, SharePoint Online), get redirected to Azure AD's sign-in page, enter your username and get redirected again to another sign in page where you enter your password. This typically happens to users in large organizations that have federated their on-premises infrastructure to Azure AD. A variation of this experience happens for organizations that use Azure AD's cloud-hosted sign-in pages and have configured Company Branding : in this case, the sign-in page starts by showing generic branding, then fades in the organization's branding after users enter their username.

This is the most common sign-in experience with web apps that are accessed at a generic URL such as https://mail.office365.com. It also happen with pretty much every rich-client apps, such as the latest Microsoft Office apps on iOS and Android. That's because, in both cases, Azure AD doesn't know the user's tenant (or identity provider) when it's asked to sign users in, and therefore needs to perform "Home Realm Discovery".

How does Home Realm Discovery work?

In the cases above, apps direct users to Azure AD's common endpoint, and Azure AD shows a generic sign-in page. This page waits for users to enter their username then, as soon as the focus moves away from the username field, it makes a server call to look up the configuration for the user's domain. In case of a federated domain, the login page then initiates a redirect to the federation server, such as ADFS. Users then enter their credentials on the federation server's own login page which displays their organization's branding.

When we introduced Company Branding last year, we mimicked this UX behavior: the Azure AD sign-in page starts off with generic branding then looks up the organization's branding elements after the server call is made. In both cases (federation and company branding) the goal is to ensure that users enter their credentials on a page that reflects their organization's brand.

When does it make sense to bypass Home Realm Discovery?

If your application targets users in a single organization, there's no need to use Azure AD's Home Realm Discovery and you can "accelerate" users to their organization's sign-in page. To do this, your application needs to pass a domain hint to Azure AD, effectively stating "I've already established that the user who's about to sign in is from <this organization>."

When Azure AD receives such a hint, it performs Home Realm Discovery on the domain name hint before rendering a single pixel. If the domain is federated, Azure AD immediately redirects users to the federation server. If the domain is managed, it checks whether Company Branding has been configured for the domain and displays it when found.

How to do this?

The implementation depends on the protocol you use to talk to Azure AD.

• For web applications that use the Open ID Connect protocol , simply add the following query string parameter to the sign-in URL: &domain_hint=contoso.com, where contoso.com is the realm of the users who are expecting to sign in.
• For web applications that use the WS-Federation protocol, use &whr=contoso.com instead.
• For native applications built with our ADAL libraries, you need to pass the domain hint in the AquireToken construct. Check out Vittorio's blog post for more details. His post also provides guidance if you're using our OWIN middleware.For web applications that use the SAML Protocol , you need to send the hint as part of the SAML AuthN request.

SAML AuthN requests differ from WS-Fed or OIDC in that the request parameters aren’t transmitted over query string. Instead they need to be specified in a request XML document that is base64 encoded to create the SAML AuthN request. To include the hint, you should use the Scoping XML node, and include a single entry IDPEntry under the IDPList (at this time, only the first IDPEntry node is used by Azure AD). Here’s an example of what the request would look like with “contoso.com” as the domain name hint:

<samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="iddeb9381bc15e4fd6a253b97205d47c6f" Version="2.0" IssueInstant="2015-02-26T18:57:06.4772751Z" IsPassive="false" AssertionConsumerServiceURL="https://www.authnauthz.com/saml/inboundauthnresponse" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">

<saml:Issuer>https://www.authnauthz.com</saml:Issuer>

<samlp:Scoping>

<samlp:IDPList>

<samlp:IDPEntry ProviderID="https://contoso.com" Name=”contoso.com”/>

</samlp:IDPList>

</samlp:Scoping>

</samlp:AuthnRequest>

What about multi-tenant apps?

You should only send a domain hint if you expect 100% of users to be using credentials from a single organization. If you app is multi-tenanted or supports "guests" users from another tenant, do not do this, especially with a federated tenant, because anyone who tries to sign in to your app will be redirected to the federation server's sign in page which typically doesn't offer a way for external users to "work their way back" to Azure AD.

If you're building a web app that's open to users in multiple organizations, the simplest option is to rely on Azure AD's Home Ream Discovery UX. This allows you to give the same sign-in URL to all users (e.g. https://www.yourapp.com ). Every user will go through Home Realm Discovery once, then they can get a user tile that makes it easier to sign in on subsequent visits.

You can also decide to provide different sign-in URLs (or sign-in buttons) for different organizations, such as https://contoso.yourapp.com or https://yourapp.com/contoso.com . You should wire up these URLs to forward the corresponding domain hint to Azure AD, and it will accelerate users to their organization's sign-in page.

You can also do both! For example, Office 365 OWA can be accessed at either https://outlook.office365.com (sign-in page shows generic Office 365 branding) or https://outlook.com/contoso.com (sign-in page immediately shows Contoso branding, or redirects to Contoso's federation server). It's just a matter of preference.

Is there a way to show company branding for apps that are open to external users?

Yes! By popular request, we've just released this update to Azure AD's sign in service. Say you're building a web app for Contoso that can be accessed by both Contoso employees and external users. When you invoke Azure AD's tenant-full endpoint, the sign-in page will now show the Contoso branding by default. (You know you're hit the tenant-full endpoint because the sign in URL looks like https://login.microsoftonline.com/contoso.com/oauth2/authorize instead of https://login.microsoftonline.com/common/oauth2/authorize ). And on this page, if a user enters a Fabrikam username, Azure AD will switch the branding to Fabrikam (or redirect to Fabrikam's federation server if the domain is federated). Of course, this assumes that Company Branding were configured for Contoso/Fabrikam.

As always, we're looking forward to your feedback.

Thanks

Ariel