Archive for the ‘ Federation ’ Category

Federated Authentication Illustrated: The story of an unwise foreign tourist


In an attempt to illustrate how federation relationship between Office 365 and on-premise directory  works, I wanted to put together a “real-life” story that doesn’t involve any IT terminilogy. Let us follow this analogy to explain what is happening during the federated authentication process. At the end of each chapter, I will add a “translation” section that will convert this vaudeville into IT language. So here it goes:

Story of an unwise foreign tourist

Narrator: It was a dark and stormy night. The place was Moscow, Russia. The Universe was… alternative…


Narrator: In a smoky Moscow bar, one man whose name was Dmitry, has just heard of a place full of marvel. That place was Little Rock, AR. Without any hesitation, Dmitry decided to fly to distant Little Rock, to see it for himself. Little did he know that he was about to embark on a worldwide journey.


User typed in his/her browser (alternativly to skip next chapter user could have typed to perform realm-discovery and avoid typing user-name twice)

Knocking at the door

– Knock Knock…

– Who’s there?

It’s Dmitry; he has arrived to the Little Rock airport. To no surprise to us, and to his complete amazement, The Port Authority of Little Rock has told him that he needs to authenticate himself. Being part of the United States, Arkansas does not issue its own passports or visas, instead they would recognize only one form of authentication, from the United States Immigration Services… commonly  known as a visa. Port Authority folks were polite about it (mind you, we ARE in an alternative universe here) and they gave Dmitry the address and directions to the centralized US Border Control office. They also told him to return to Little Rock when his papers are in order.


Since is only accepting authentication from the Office 365 authority, has redirected our user to the Office 365 login page, as it could not authenticate him/her.


Foreign Authority

Narrator: We should note that most foreign countries in our alternative universe have their difficulties with trusting each other. Borders are guarded vigorously. Bureaucracy is erected to protect them. Russia and The United States, in this case, are not an exception. However, both do recognize the fact that their citizens do need to visit the bordering country from time to time. Therefore, they have signed an agreement. That agreement defined that Russian citizens can use Russian-issued passports to identify themselves at the US Border Control office. Each issued passport shall have a unique citizen identifier, and a unique citizen name. The US Border Control shall send all Russian citizens without passports back to the predefined address in Russia.

Dmitry: I am Dmitry from Russia. Here is the paper from Little Rock folks telling me to come here.

US Border Control: Your Russian passport, please.

Dmitry: I don’t have one

US Border Control: According to our agreement with Russia, you must fly back and ask for your passport there. Here is the address in Russia you must visit. Return when you have your passport. Good-bye.


By virtue of the user typing his/her login (RegEx looking at the “right side” from the @ sign of user name OR looking at the URL header such as<%FederatedNamespace%>) Office 365 discovered that the requestor is from a federated namespace, and therefore Office 365 doesn’t have the user’s credentials. It must redirect the user’s browser to a known/predefined on-premise Security Token Service end-point, which will authenticate the user and issue a predefined ticket containing an immutable ID (the unique citizen identifier in the story) and UPN (unique name in the story).

I am who I am! Aren’t I?

Narrator: Dmitry’s flew back to Russia and arrived at the local passport agency office as directed by the US Border control.

Dmitry: I have been sent by the US Border Control office, telling me that I need a passport. Can I have one, please?

Russian Passport Agency: That’s great! Who are you, exactly?

Dmitry: I am Dmitry. Here is my birth certificate. It plainly says that I am Dmitry.

Russian Passport Agency: We have verified your claim with our back-end registry. You are who you say you are. Here’s your passport, we have stamped your federal ID number and your unique name into it. Go back to the US.


The user has landed on the on-premises federation-server user-authentication page (The “Russian Passport Agency” in this story) and has entered his credentials. NOTE: The ADFS will accept the user’s sAMAccountName (the birth certificate in this story) and the password combination OR user’s UPN and the password combination. Once the user is authenticated, ADFS issues a token containing the user’s UPN and unique identifier (default unique identifier is AD GUID in base64 encoded string). It is important to stress and understand that UPN value is not required by the ADFS’s login-page/dialog box to actually authenticate the on-prem user, however it is required to be enclosed into the issued claim that is sent back to a requesting federated party (Office 365 in this case). Once again, the user can actually authenticate with sAMAccountName, yet his/her UPN value will be sent back to Office 365 instead of sAMAccountName as defined during ADFS configuration.


Take Two

Narrator: Armed with a newly minted Russian passport, Dmitry arrives at the US Border Control (again).

Dmitry: I am Dmitry from Russia. Here is the paper from the Little Rock folks telling me to come here for a visa

US Border Control: Your Russian passport, please

Dmitry: Here it is, shiny and new.

US Border Control: Your documents are good. Welcome. Here’s your visa. Now you can fly to Little Rock


Now that user’s browser contains a valid token, the user can be authorized to access Office 365 resources, and therefore redirected yet again to his/her destination with a resource token consumable by Office 365 resources, such as Exchange Online, Lync and SharePoint/SkyDrive Pro.

Final Approach:

Narrator: Armed with his US visa, Dmitry arrives back in Little Rock.

Dmitry: I demand to see Little Rock

Port Authority of Little Rock: Do you have a visa?

Dmitry: Here’s the US Border Control issued visa.

Port of Authority: Excellent! Welcome!


By having a resource token, the user can access target federated resource; in our case it is Exchange Online mailbox.


Although Dmitry’s journey was not straightforward, he arrived at his final destination with the help of a well-defined sequence described by protocols and agreements. If only he would have been smarter, and knew the process he had to follow, he might have saved some time for himself, but that is another chapter for a later time.


The described “choreography” pertains only to the “Passive Requestor Profile” that is primarily used by web-browsers. Rich clients such as Outlook, and clients such as mobile devices, employing ActiveSync, are using other types of profiles (active requestor profile); while Lync is using Metadata Exchange (MEX) protocol. Both of these methods are a little “smarter” than the passive requestor profile sequence and therefore allow for a richer user experience and consequently more features.


Office 365 Road Warrior’s guide to quick and dirty ADFS web-auth page customization

Beautiful it is not, the out-of-the-box ADFS logon page that is. Unless you are late 90s minimalist and don’t care for any kind of web adornments. (I am thinking of an example of white background page with minimum number of controls… Hmm)
Anyhow, every time I am deploying ADFS to authenticate to Office 365 I am being ask to tweak a few things. This posting, is an abridged collection of webpage quick “tweaks” that I’ve accumulated throughout last couple of years. I want to note that this is by no means “pretty” looking tweaks. I don’t go for pretty here. The key words here are: quick and useful. You should talk with your web-designer to get yourself fabulously looking ADFS logon page; However if you are looking for quick and dirty tricks you can deploy in a few minutes without signing SOW, keep reading.


This collection of “beatifications” will satisfy few common requests that I’ve heard from many system admins. Let’s start with obvious and easiest one:

Adding Logo to your ADFS SignIn page:

This is the most basic and most common of all requests. To brand your page with company logo, you will need to:
Place your logo image file (jpg, png or gif) into the root of the ADFS web-site [by default] C:\inetpub\adfs\ls\ In the web.config file (located in the same location) remove comments (like htis one: <!--) around and modify the file name referenced in the web.config to reflect name of your logo file

<add key=”logo” value=”logo.png” />

While you are in the web.config file

Adding legal disclaimer:

Take a look at the legal disclaimer section of the web.config. Uncommenting that section will provide you with out-of-the-box functionality requiring users to acknowledge terms of use/legal agreement before proceeding with authentication.

Removing <%EndPointName%> URL from from SignIn page:

Your published federation end-point might not be something you would like to expose to your end-users. might look cool to a system admin, but it will likely to confuse your end-user and could complicate troubleshooting for your helpdesk folks. To remove that URL “label” form your ADFS logon page you’ll need to do following:
We’ll be modifying master.cs page to comment out line STSLabel.Text = FriendlyName;

This is how it should look like:

using System;
using System.Web.UI;

public partial class MyMasterPage : Microsoft.IdentityServer.Web.UI.MasterPage
protected void Page_Load( object sender, EventArgs e )
PageTitleLabel.Text = Page.Title;
//STSLabel.Text = FriendlyName;

Adding server name:

While installing multiple ADFS nodes/proxy servers behind network load-balancers you might want to display name of the server user is currently connected to. It might not be important to the end-user, but might help you with troubleshooting effort.

in FormsSignIs.aspx :
Insert following above this line </asp:Content>:

<asp:Label Text="DisplayYourServerNameHere" runat="server" />

Don’t forget to do IISRESET after your changes are done

Changing Log-Out “landing” page experience

As a result of federation authentication redirection “ping-pong” your users will land onto default Office 365 login page after they have click log-off button. The reason for it is pretty simple:
a) User askes to log-off in the UI of Office 365
b) O365 knows that user is coming from federated environment and redirects user to the on-prem ADFS server to process that request
c) You on-prem ADFS server receives the request and knows that it came from the Office 365 federated partner. It processes user request to log-off and
d) Faithfully forwarding user back to the originator of the request – the office365
e) Since user is no longer authenticated or technically “known” to Office 365, it present user with default login page in attemt to authenticate him/her
It’s hard to dispute machine logic here, yet in some cases this is not desirable behavior, especially if you are trying to create “walled” experience for your users, such as promoting use of the web-portal(s) to login/access your Office 365 resources, or communicating specific redirection URLs to your user community. Therefore to modify default log-out behavior I’ve came up with this tweak:

a) Locate your default OOTB ADFS sing-out page (default location should be: C:\inetpub\adfs\ls\SignOut.aspx)
b) Edit it with your favorite text editor and insert following JaveScript snippet right above/before the closing tag </asp:Content>. (Which is at the very end of the document) Don’t forget to actually insert your URL into the script

<script type="text/javascript">
window.location = 'http://YourLandingPage';web

c) In command-prompt run IISRESET

JavaScript is very touchy about quotes, single quotes, spaces etc. Cut/Paste from this page might come through with HTML artifacts. Verify your text before inserting into your logout page, and (of course) keep a backup of your original page version.

Modifying “hint” label [domain\username] next to the textbox user name textbox

I have wrote an article explaining the UPN vs. email story. This is somewhat extending on previous story and show you how to change default label on ADFS logon page prompting user to login with UPN. Note that this “tweak” is targeting English language page. Being politically correct and properly written web-site, the default landing page for ADFS is coming with dozens of localizations. Please locate corresponding language resource to make change for every language you wish to support.

In <%drive%>:\inetpub\adfs\ls\App_GlobalResources\CommonResources.en.resx

locate following line:

<data name="UsernameExample" xml:space="preserve">

Note: Do not make a copy/backup of *.resx file into the same folder. If you need to make a copy of original file, move it outside of \App_GlobalResources folder

Happy tweaking!