Using smart links for Office 365

Just a few years ago identity federation such as AD FS was the de facto standard for managing authentication in Office 365 for every large organization. It gives you better control over the process, and the convenience of seamless single sign-on (SSO) for your users. With the introduction of password sync and now pass-through authentication, an argument can be made for replacing AD FS for some Office 365 customers. Nevertheless, AD FS remains a viable, highly customizable option and offers a simple way to ensure seamless SSO for your users using smart links.

Smart links are not a new feature, but information about smart links is hard to come by. Today we’ll break down smart links and how they can improve the login process for Office 365 applications.

What are smart links and why do we need them?

Understanding how smart links work requires additional knowledge of Office 365 authentication flows. Office 365 is a software-as-a-service (SaaS) offering that services millions of customers worldwide. As with any other web application, there are a number of methods for users to log in and verify their identity. The authentication can be performed by the application itself or delegated to another party, the federated identity provider (IdP). If you’re using a third party option, it’s important the service knows where to redirect the request to. For example, a user from the Contoso organization needs to be authenticated by the Contoso IdP, a user from Fabrikam, by the Fabrikam IdP, and so on.

Smart links work through the Home Realm Discover (HRD) process. HRD enables Microsoft’s identity platform to redirect the authentication to the correct federation partner. The service looks at the domain portion of the user’s UPN attribute, checks if a federated partner exists for the domain and redirects the request to the partner’s IdP site. At some point during the authentication process, the user must type in his UPN, press a button or do some other interactive task to trigger the HRD process, thus breaking the seamless experience.

To work around this, one can use “smart links” or “deep links.” The concept is pretty basic. The authentication process is a series of HTTP requests between the involved parties confirmed with a HTTP trace in your browser. Smart links allow you to skip some of the steps by preconfiguring relevant parameters in the URL. Not only the process will be faster with fewer redirects, but because all required information is in the link, the user enjoys a seamless SSO experience.

Building blocks of a smart link

Let’s say the user opens a browser and tries to log in to an Office 365 resource such as OWA. If the user isn’t authenticated, he will be redirected to the Office 365 login page, even when using a federated identity. The URL for the login page will look something like:

https://login.microsoftonline.com/login.srf?wa=wsignin1.0&wreply=https%3a%2f%2foutlook.office.com%2fowa%2f

Next, the user enters his UPN and trigger the HRD process. Assuming a federated identity, the user will be redirected to the IdP login page:

https://sts.domain.com/adfs/ls/?username=user%40domain.com&wa=wsignin1.0&wtrealm=urn%3afederation%3aMicrosoftOnline&wctx=%26LoginOptions%3D2%26wa%3Dwsignin1.0%26wreply%3Dhttps:%252F%252Foutlook.office.com%252Fowa%252F

Once the user authenticates (a process that might be transparent to him), he will be redirected back to the Office 365 login page, and then to OWA.

Smart links allow us to take that last URL and use it to login to Office 365. All necessary information is within the URL, so there is no need for the user to type in his username or take any other actions.

Let’s break down the lengthy URLs to explain the building blocks of a smart link. First, we have the IdP URL, in our case https://sts.domain.com/adfs/ls/. The next part is the username, however this part is not mandatory. During the login process, the user can overwrite the value if presented with a credentials form, or he might be automatically logged in with his current credentials via Windows integrated authentication. You don’t need to use this parameter, or you can replace it with a generic value “anything@domain.com.”

Wa=wsignin1.0 indicates a sign-in request and wtrealm=urn%3afederation%3aMicrosoftOnline indicates a request for Office 365 (this is the identifier of the Office 365 relying party trust on your AD FS server). The context parameter wctx= includes additional information about the application the user is trying to access. In the above example, it incorporates the reply URL, which the user should be redirected after the authentication. This parameter is untouched by the AD FS server and simply replayed back with the authentication response.

It’s a good idea to provide an example of an OAuth/OIDC based smart link, which is what we’ll be using in the near future. Constructing those requires additional steps. You need the client_id (the application identifier you can obtain from Azure AD), and you need to make sure that the redirect URL matches one of the allowed values. Below is an example of an OAuth smart link that takes the user directly to OWA:

https://login.microsoftonline.com/common/oauth2/authorize?client_id=00000002-0000-0ff1-ce00-000000000000&response_mode=form_post&response_type=code+id_token&scope=openid+profile&redirect_uri=https%3a%2f%2foutlook.office365.com&domain_hint=domain.com

This table gives a short summary of smart links building blocks for the two IdPs in Office 365. Bolded vallues are mandatory and must be included in your smart links. The table is not exhaustive — additional parameters exist and can be used. Note that in the current version of the service the wctx parameter obscures most of its values via the encoded/signed estsrequest property.

Examples of smart links

Now that we understand the building block of a smart link, we should be able to construct them directly without observing the HTTP traces. For example, a simple link that takes the user to his/her Office 365 landing page looks like this:

https://sts.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline

In the above example, we hit the AD FS server with a direct  sign-in request, indicating that it’s for Office 365 RPT. The username is not mandatory (see the previous section).

You can also use a smart link that takes the user directly into SharePoint Online. Here’s an example:

https://sts.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline&wctx=%26LoginOptions%3D1%26wa%3Dwsignin1.0%26wreply%3Dhttps:%252F%252Ftenant.sharepoint.com%252Fsitename

So far, we have used examples that are hitting the AD FS server directly. This is the so-called IdP initiated sign-on scenario. Another type of smart link is one that uses the Office 365 login URL, the Service Provider initiated scenario. When using this type of links, the request hits the Office 365 endpoint first. To bypass the need for the user to interact with the UI controls on that page, we can use HRD “hints”. This is made possible via the whr= parameter, which basically tells the server which organization you belong to. Here are few examples of SP-initiated smart links:

https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr=domain.com&wreply=https://outlook.office365.com/owa/

which will take you directly to OWA, or one that works for the Word Online app:

https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr=domain.com&wreply=https://office.live.com/start/Word.aspx?auth=2

Note that in the case of SP-initiated sign-on, we don’t need to provide the RPT identifier (the wtrealm parameter). Another difference compared to IdP-initiated smart links is the easier syntax for the wreply parameter, as we don’t need to use HTTP encoding anymore. On the other hand, there will be few additional redirects when using SP-initiated smart links.

Some of the Office 365 workloads accept direct input for domain hints, which you can use to bypass the HRD process. Examples can be found in the table below, one can use them as a form of smart link. This is not valid for all workloads though, and with smart links you have better customizability.

Additional examples and a smart link generation tool can be found in this Office 365 smart link SSO link generator article. For SharePoint Online one can also consider the auto-acceleration feature in SharePoint. 

How to deploy smart links

As evident from the above examples, smart links are certainly not short links and you cannot realistically expect end users to work with them in that form. A simple solution is to use GPO to configure the smart link(s) as start page(s) in the browser. Another similar solution is to deploy them as Favorites, which is probably the preferred method when you have multiple smart links to use.

If you want to be able to quickly type-in a smart link, configuring a redirect on your LB instance is an elegant solution. For example, webmail.domain.com can issue a 301 redirect to the OWA smart link we constructed above. Similarly, you can configure such redirect via the URL rewrite module of IIS or even do the same via an Azure hosted webservice. It’s recommended to avoid CNAME based redirects, as the potential certificate warning will break the seamless SSO experience.

Here’s probably the correct place to mention another benefit you can get with using smart links, namely the persistent SSO experience. Most of you are probably aware that the tokens used by the different Office 365 service have a rather short validity window. The “Keep me signed in” checkbox present on the login page can be used to extend the validity window, however people often don’t realize this or simply forget to click the checkbox. Some articles out there incorrectly state that smart links are incompatible with the KMSI option as they are bypassing the login page. This is not true, the KMSI option is simply another parameter (LoginOptions) passed in the URL:

https://sts.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline&wctx=%26LoginOptions%3D1%26wa%3Dwsignin1.0%26wreply%3Dhttps:%252F%252Ftenant.sharepoint.com

or if using the SP-initiated format:

https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr=domain.com&wreply=https://tenant.sharepoint.com&LoginOptions=1

Constructing and deploying smart links ensures that your users enjoy a consistent SSO experience. Once you start using the link above as a start page, not only they will see a lot less authentication prompts, but most issues with mapped SPO drives should magically disappear!

There are other methods of ensuring persistent SSO, so smart links are certainly not a must-have solution. Nevertheless, smart links offer a simple way to make sure the KMSI checkbox is ticked with every login.

Additional notes and summary

Smart links facilitate seamless sign-on or consistent SSO experience for your Office 365 services. Even with the advent of the features such as pass-through authentication, smart links remain relevant. If anything, one can argue that there is even greater need for them now that we have modern authentication and every request is served on the passive endpoint.

Another great source of information are the AD FS whitepapers from Microsoft.

One area where smart links can’t help is the case of multi-factor authentication. As emphasized above, the idea behind smart links is to eliminate user interaction, so if you have deployed a solution that requires the user to insert a smart card or enter a code as a form of second-factor authentication, using smart links will not have the desired result.

Smart links can be used for more than just Office 365 authentication. If your organization uses AD FS or any other federated authentication solution, chances are you can improve the sign-in experience of your users by deploying smart links for use with other applications as well.