What is a smart link?

Traditionally when a customer sets up single sign-on (identity federation) to Office 365, the authentication mechanism used for web browser applications uses the WS-federation passive profile.  More details on this mechanism can be found in the blog post "How identity federation works".  Core to this mechanism is a process called "home realm discovery", whereby the end user needs to provide information to the Office 365 login server, so that the login server can determine if it should authenticate the user, or redirect the user to the on-premise identity provider (the authoritative authentication provider) for that user.  In the federation case, this redirect constructs a URL that:

1. Sends the browser to the authoritative AD FS 2.0 server passive login endpoint
2. Encodes where any SAML token issued by the AD FS 2.0 server needs to be posted (i.e. to the Office 365 identity platform)
3. Encodes the relying party service that the user was trying to reach (like the URL for Exchange Online or the Office 365 portal)

This URL is commonly termed a smart link or also an identity provider initiated sign in link. 

Why should I care about smart links?

Organizations can deploy smart links internally (by creating a vanity URL that maps to the smart link) that provide:

1. An easier to remember vanity URL for your organization's users to use when going to Office 365 services, reducing support calls to your IT helpdesk. These vanity URLs can also be written to user's IE favorites as part of a global policy setting.
2. An improved end user experience when accessing Office 365 services, which increases end user customer satisfaction:
   1. Faster authentication to the Office 365 service (two fewer redirects)
   2. Users will not have to go through the home realm discovery service

This post describes how an organization can create and deploy smart links for their users.

How to deploy smart links for my organization

Once you understand how to construct a smart link for the target Office 365 service, you can deploy a 302 redirection service on your on-premise web servers.  This assumes that you have already set up Single Sign-On (Identity Federation) for Office 365 and have verified that it is working correctly.

Creating a smart link

The simplest way to create a smart link is to turn on an HTTP tracing tool and authenticate to the desired service.  In the future, Office 365 may provide a service for administrators to that automatically constructs the smart link.  Until that time, please follow the manual instructions below.

1. Open IE and turn on HTTP tracing
2. Perform a federated authentication to the service that you want a smart link for by going to the service (like https://portal.microsoftonline.com/) and signing in.
3. From the HTTP trace tool, find the last line of data that has your AD FS 2.0 address (in the form of https://<your_AD_FS_2.0_Server_public_URL>/adfs/ls) in the list of URLs
4. Copy and paste this line into Microsoft Notepad or a similar editor. You should see something similar to the following (using Contoso and the Office 365 portal as examples):
   1. https://sts.contoso.com/adfs/ls/?cbcxt=&vv=&username=johndoe%40contoso.com&mkt=&lc=1033&wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline&wctx=MEST%3D0%26LoginOptions%3D2%26wa%3Dwsignin1.0%26rpsnv%3D2%26ct%3D1292977249%26rver%3D6.1.6206.0%26wp%3DMCMBI%26wreply%3Dhttps:%252F%252Fportal.microsoftonline.com%252FDefault.aspx%26lc%3D1033%26id%3D271345%26bk%3D1292977249
   2. You'll need to edit this by removing everything up to the "wa" querystring parameter and also remove the last QS parameter "bk".  See "For reference:  Smart Link URL template" for more details on the format of the smart link.
   3. https://sts.contoso.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline&wctx=MEST%3D0%26LoginOptions%3D2%26wa%3Dwsignin1.0%26rpsnv%3D2%26ct%3D1292977249%26rver%3D6.1.6206.0%26wp%3DMCMBI%26wreply%3Dhttps:%252F%252Fportal.microsoftonline.com%252FDefault.aspx%26lc%3D1033%26id%3D271345
5. Your edited URL forms the smart link that you will use to create a vanity URL for users to reach the Office 365 portal in the most seamless single sign on fashion, by following the steps in "Deploying a smart link".

Deploying and verifying the smart link

Once you've created your smart link, you'll need to deploy it by creating a vanity URL for your organization's users to use.  In the example above we created a smart link for the Office 365 portal (https://portal.microsoftonline.com/).   Now we'll create a vanity URL that will redirect (302[1]) to the smart link above.

1. Create a new A record in your domain registrar (like portal.contoso.com) and point this to the IP address of your IIS server that will host your redirection service
2. Create a new web site (portal.contoso.com) on your IIS server
3. Create a 302 redirection service, and paste the smart link into the target address
4. Test that portal.contoso.com resolves to the correct IP address inside and outside your corporate network.
5. Open IE and type http://portal.contoso.com/ and you should get seamless single sign-on directly to the Office 365 portal.

For reference: Smart link URL template

[AD_FS_2.0_WebLoginURL]?wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline&wctx=[Custom_Value]

Values for HTTP Message

Query-string Parameter Semantics

Creating the value for the Wctx parameter is non-trivial, which is why it is recommended that you use the approach described in "Creating a smart link".

[1] We're using a 302 redirection service rather than a DNS CNAME record, because otherwise the user will get a certificate pop-up that the site requested does not match the name on the certificate of the site visited.