ACS as a Federation Provider - A little bit deeper into the sample (Home Realm Discovery)

Updates: fixed typos. Clarified how Home Realm Discovery works in this example.

In the previous post, I introduced the basic scenario of using ACS as a federation provider for Adatum (in addition to the one they already have). In this post, I’ll show you more details on how this works, based on the sample we are building that will ship with the guide.

Step 1 - Rick from Litware browses a-Order hosted by Adatum

The first time Rick browses a-Order he is “unauthenticated” therefore a-Order simply redirects Rick to the issuer it trusts for getting security tokens. That is Adatum’s own issuer. The issuer doesn’t know where Rick is coming from (it could use some heuristics, but in this simple example, it doesn’t), so it just asks the user “where are you coming from so I can redirect you to the a place I trust to get you authenticated? ”.

This is the "Home Realm Screen” and it is meant to capture precisely the user (Rick’s) home realm (the place where he can get authenticated). Notice that we now have 3 options:

1. Adatum. This will redirect the user to Adatum’s Identity Provider. This is of course useless to Rick because he doesn’t
2. A list of organizations Adatum does business with (Litware)
3. An e-mail address fro which the a-Order can infer the security domain.

Step 2 – Rick selects “Litware” from the listbox

By doing this, Rick will continue his journey to get a token for a-Order. He’s redirected to Litware’s IP. Adatum’s FP knows about this because internally it will keep a list of the other issuers it trusts. “Litware” in the listbox maps to the actual URL of Litware issuer. This is the screen on the left below. After successful authentication, Rick is directed back to the FP with a freshly minted Litware token. The FP inspects the token, does some transformations (adds/removes claims) and issues a new (Adatum) token which is finally sent to a-Order.

a-Order opens the token (thanks to WIF) and runs its logic (display pending orders). That’s the screen on the right:

a-Order magnificent UI renders the name of the user and the name of the “original issuer” of the token on the top right corner of the screen.

ACS enters the scene

Now, what happens if the user fills in the last option of  the Home Realm page? (the e-mail). In this case, our sample does exactly the same thing only with some extra logic.

Step 1- Mary browses a-Order and then completes the textbox with her Gmail mail address

In our current implementation Adatum’s FP Home Realm page will assume that if you complete the e-mail textbox, you want to authenticate with Google or LiveID and will simply redirect you to ACS. ACS is the other “Federation Provider” in the chain in between Adatum’s issuer and Google or LiveID.  It actually does something else: it specifies the whr parameter. This is simply based on the e-mail domain. So, if I type “something@gmail.com” it assumes the issuer I’m interested in using for authentication is Google’s:

Step 2 – Mary authenticates in Google

Because ACS is getting this hint from the Adatum’s FP, it forwards the request with no further stops to Google (the screen above).

Question for the reader #1: what would happen if Adatum’s FP didn’t specify the whr parameter when it redirected Rick to ACS?

Notice how Google is informing us of the requestor of the token (our account in ACS), and provides the usual login screen. After successful login, it actually requests the user for an additional approval to disclose some information about him/her. (the e-mail in this case)

Step 3 – Going back to a-Order

What happens next is exactly what I described before. Unfortunately we don’t see all the magic that happens inside ACS. But essentially, it took care of bridging all the relationship with Google, it translated the token received from Google (not SAML) and then issued a (SAML) token that Adatum’s FP and a-Order could understand:

There are absolutely no changes in a-Order code to handle this. There’re no dependencies on Google’s API or anything special. All thanks to ACS and claims based identity. All we did was add ACS as a trusted issuer of Adatum’s FP, added a Home realm page to Adatum’s FP and then configured the token transformation rules.

In fact, from a programming perspective you simply get a ClaimsPrincipal with the usual properties, regardless of where the token is coming from:

It just works!

Question for the reader #2: Google didn’t provide the “Role” claim you see above. And most certainly didn’t provide the “Organization” claim either. Who did then? Where are they coming from?