IMPORTANT ANNOUNCEMENT FOR OUR READERS!
AskPFEPlat is in the process of a transformation to the new Core Infrastructure and Security TechCommunity, and will be moving by the end of March 2019 to our new home at https://aka.ms/CISTechComm (hosted at https://techcommunity.microsoft.com). Please bear with us while we are still under construction!
We will continue bringing you the same great content, from the same great contributors, on our new platform. Until then, you can access our new content on either https://aka.ms/askpfeplat as you do today, or at our new site https://aka.ms/CISTechComm. Please feel free to update your bookmarks accordingly!
Why are we doing this? Simple really; we are looking to expand our team internally in order to provide you even more great content, as well as take on a more proactive role in the future with our readers (more to come on that later)! Since our team encompasses many more roles than Premier Field Engineers these days, we felt it was also time we reflected that initial expansion.
If you have never visited the TechCommunity site, it can be found at https://techcommunity.microsoft.com. On the TechCommunity site, you will find numerous technical communities across many topics, which include discussion areas, along with blog content.
NOTE: In addition to the AskPFEPlat-to-Core Infrastructure and Security transformation, Premier Field Engineers from all technology areas will be working together to expand the TechCommunity site even further, joining together in the technology agnostic Premier Field Engineering TechCommunity (along with Core Infrastructure and Security), which can be found at https://aka.ms/PFETechComm!
As always, thank you for continuing to read the Core Infrastructure and Security (AskPFEPlat) blog, and we look forward to providing you more great content well into the future!
David Gregory back again for another blog on federation and sign-in protocols. Explaining federation so that people can truly understand it isn’t easy. There are a lot of moving parts, various technologies, and sea of acronyms that many times don’t make sense. When I first started learning about federation, I was drowning in these acronyms that I didn’t know anything about. It wasn’t until I started figuring out what they meant and started piecing them together that my understanding of federation finally started to crystalize. I’ve been working really hard to write this stuff and “unfold” this topic in a way that makes sense and really lands with you guys.
The first two terms I started to hear when I picked up federation were WS-Fed and SAML. Being an Active Directory guy, I initially assumed that SAML was somehow related to the SAM database. Ha. Fortunately, those days are past and I want to take all my experiences from the field with customers and distill them down into relatively easy concepts that even my mother could understand. Ok, that’s probably a stretch but you get my drift. J
In my earlier post from back in August, I talked about the various scenarios that ADFS fits into – Web SSO, Federated SSO, and Active/Passive Requestors. That was a pretty high-level overview.
Now, we’re going to go a little deeper into WS-Fed, SAML, and OAuth which are the things that tie these disparate systems and applications together.
Before we get technical, let’s kick this off with something completely non-technical. As engineers, we have very keen minds about breaking things down into components and processes. This helps us understand things so we can troubleshoot, or build complex systems. When you go to the airport to board a flight, what is your sign-in protocol, authentication protocol, and token type? These three components will be focus of this entire blog. Here is how I would define them:
- What is the Sign-in protocol? I go to the one of those check-in kiosks, then print my boarding pass, then go through TSA line, then go to the boarding gate, and finally board the plane. It is expected that I interact with the airport in this fashion and performs these actions in sequence, otherwise, I will not get on my plane.
- What is the Authentication protocol? While my boarding pass is part of this, I have to provide my ID or passport to prove who I am.
- What is the Token Type? My boarding pass is my token to get on the plane.
Now when we talk about WS-Fed or SAML, always ask yourself those same questions: What is the sign-in protocol, what is the authentication protocol, and what is the token type. Asking these questions will make the difference whether you understand these concepts or not.
Something to mention before you proceed – Don’t try to over analyze the technical details below by picking apart the values of each URL parameter and trying to understand what they mean yet. As we start to get deeper into each of these sign-in protocols in subsequent blogs, picking these apart will make more sense. For now, just try to understand the differences between the terminology and the sign-in protocols.
WS-Fed is a sign-in protocol, which in plain English means that when the application you’re trying to gain access to redirects you to the ADFS server, it has to be done in specific way (WS-Fed) for the process to continue. Let’s give some easy examples in line with my example above.
I go to https://claimsweb.cloudready.ms/. It determines that I’m not authenticated and redirects me over to my ADFS server for authentication but the parameters it sent in the URL conform to the WS-Fed sign-in protocol:
Let’s break-out these parameters:
- Wa=signin1.0: This tells the ADFS server to invoke a login for the user.
- Wtrealm: This tells ADFS what application I was trying to get to. This has to match the identifier of one of the relying party trusts listed in ADFS.
- Wctx: This is some session data that the application wants sent back to it after the user authenticates.
- wct: This is the exact time I tried to gain access to the application.
As soon as I see URL parameters like WA, WTRealm, etc, I immediately know that this is the WS-Fed sign-in protocol. Consequently, to hand the user off to the ADFS server properly, the application has to send all of these URL parameters. The URL parameters don’t have to be in this exact order but they must all be present so ADFS knows what to do.
Now, when I get prompted for credentials, what is the authentication protocol: Forms-based.
And lastly, after typing in my credentials, what is my token type that ADFS gives me to send back to the original application: When the WS-Fed sign-in protocol is used, ADFS will always issue a SAML 1.1 token back to your browser, which you then automatically POST back to the application.
Summary: This application is WS-Fed sign-in protocol compliant as is ADFS. I used forms-based login as my authentication protocol, and was issued a SAML 1.1 token type.
SAML is a sign-in protocol and a token type. Tricky, huh. 🙂 In regards to sign-in protocols, SAML and WS-Fed achieve the same thing but handle it very differently. Let’s give another example.
I go to https://shib.cloudready.ms. It determines that I’m not authenticated and redirects me over to my ADFS server for authentication but the parameters it sent in the URL conform to the SAML sign-in protocol:
Let’s break-out these parameters:
- SAMLRequest: This is actually a Base64 encoded XML document. You can actually paste this value minus SAMLRequest= into here to decode it and view it in plain text @ https://idp.ssocircle.com/sso/toolbox/samlDecode.jsp
- RelayState: Session data that the application wants sent back to it after I authenticate against ADFS.
- SigAlg: Which signature algorithm was used to sign the request.
- Signature: The digital signature of the request above.
With URL parameters like SAMLRequest, Relaystate, SigAlg, and Signature, this thing has the SAML sign-in protocol written all over it.
This time, when I login into https://shib.cloudready.ms, I’m not prompted for credentials at all so I must have used my Windows Integrated credentials. One way to check to see whether I used Kerberos is to run “klist tickets”:
Yep, my authentication protocol definitely was Kerberos.
ADFS will always issue a SAML 2.0 token for an application that is configured with the SAML sign-in protocol.
Summary: This application is SAML sign-in protocol compliant as is ADFS. I used Kerberos as my authentication protocol, and was issued a SAML 2.0 token type.
While there is some debate about OAuth being a sign-in protocol or an authentication protocol and while it definitely is evolving, within the realm of ADFS 2012 R2, OAuth is another sign-in protocol.
I open up a modern application on my Windows 8.1 tablet and when I do, the applications submits the following URL to the ADFS server:
Let’s break down these parameters:
- response_type: tells that ADFS server that I want to perform OAuth and get an authorization code in return.
- client_id: The ID of the application I’m trying to get to.
- Resource: the URL/URI of the application I’m trying to get to.
- redirect_uri: Tells ADFS who to POST the auth code back to
Based on these URL parameters, this is definitely the OAuth sign-in protocol. Upon the ADFS server receiving this request, it prompts with forms-based authentication asking me for credentials. There is a component built into Windows 8.x called the Windows Authentication Broker (WAB) that renders the forms-based sign-in you see below. In this case, the application never saw my username and password because the WAB handles it on behalf of the application.
Once I authenticate, the ADFS server responds with an authorization code. BTW, this is a one-time use code. You’ll never see this code, but the application will store this to later get an access token, which it can then use to get the necessary user data the application requires.
This highlighted section is an auth code that the application can then use on subsequent requests to get an access token on my behalf.
Now the application needs to get some application data on my behalf so it can populate the application appropriately. It takes this above code and performs a POST to the following URL:
- code=<Above Authorization Code>
Note: I didn’t include the Access Code above for brevity.
And guess what it receives it return, an access token:
Components of Access Token separated by a period (.)
- Encoded JWT
- Digital Signature of JWT
If I Base64 decode the highlighted section above, I can see the JSON Web Token (JWT) in its full glory:
Summary: Now, that was pretty technical, but what does it highlight? We used the OAuth sign-in protocol, forms-based authentication was our authentication protocol, and our token type was JSON Web Token (JWT)
Are you picking up on a theme here? These three examples highlight why we like to call these scenarios “The Flow” when speaking about federation. It’s because the sign-in protocol will dictate the overall “Flow” of the scenario – How we should interact with the ADFS server, what parameters it requires, what exactly we are expecting in return.
Besides picking apart URL parameters or trying to capture them with Fiddler, how do you know whether your federated applications are configured for WS-Fed, SAML, or OAuth? Well, there are a couple of ways.
If you output the configuration of each relying party trust (application), it will tell you whether WS-Fed or SAML are enabled for this application:
Get-ADFSRelyingPartyTrust –Name <Friendly Name>
For example, Get-ADFSRelyingPartyTrust –Name “Microsoft Office 365 Identity Platform”
You’ll notice that this relaying party application has both WS-Fed and SAML enabled but what is the effective sign-in protocol?
Relying Party Trust Endpoints Tab
The configuration of the endpoints on the actual relying party trust dictate whether the WS-FED or SAML will be used when interacting with this application:
This one only has a WS-Federation Endpoint configuration, which means it can only use WS-FED sign-in protocol:
Here is another one that has a SAML endpoint configured, which means it can only use the SAML sign-in protocol:
Well, what about OAuth then? You’ll notice that this relying party application doesn’t have any endpoints, what gives?
Well, to view and configure OAuth on a relying party application, you have to go back to PowerShell:
Mixing and Matching?
While in theory you can mix and match sign-in protocols, authentication protocols, and tokens types, in practice you wouldn’t want to do this. Of these three, the one you might see change depending on the circumstances is the authentication protocol. I.E. – Outside the firewall forms-based, inside the firewall Kerberos, or perhaps a specific application wants ADFS to enforce certificate-based authentication.
WS-Fed is actually token agnostic but ADFS was written so that WS-Fed will always reply with a SAML 1.1 token.
So here is the breakdown:
- WS-Fed Sign-In Protocol = SAML 1.1 Token
- SAML Sign-In Protocol = SAML 2.0 Token
- Authentication Type = Forms-Based, Kerberos, NTLM, Certificate, MFA, etc.
Which One Should I Use?
For WS-Fed or SAML, it really boils down to the web application that you want to onboard to ADFS. Each vendor may support different sign-in protocols but if the application is based on Windows Identity Foundation (WIF) or is a Microsoft-supported web application (SharePoint, Azure, Dynamics CRM), it will more than likely be WS-Fed. Most other SaaS providers and/or web applications will support the SAML sign-in protocol. ADFS 2012 R2 currently only supports the OAuth authorization code profile, which should only be used for Modern/Metro/IOS/Android applications.
Why does any of this matter?
Because after you stand-up ADFS, people will start knocking on your door telling you how they want to federate with some cloud-based application and one of your first questions to them should be:
Is the application claims aware and does it support either WS-FED, SAML, or OAuth?
This is a perfect segue into my next blog, which is what questions should you be asking when installing and configuring ADFS or configuring federated applications. Stay Tuned.
Dave “Ghost Protocol” Gregory