November 27, 2017
TABLE OF CONTENTS
There are several identity protocols that are commonly supported by Identity Providers today — OAuth2, OAuth2 Token Exchange, OIDC, SAML2 Browser Profile, WS-Trust, WS-Federation, etc. The OAuth2 and OIDC protocols are relative newcomers. The other protocols have been around longer — and, tend to be more universally supported, especially in the enterprise space. One of the oldest SSO protocols (still in common use) is the OASIS WS-Federation specification. In this post, we are going to explore the WS-Federation Passive Profile.
One tends to see WS-Federation in the Microsoft world, Active Directory Federation Services (ADFS) and Azure Active Directory;though it is supported by many Identity Provider vendors. Configuring ADFS tends to be easier with WS-Federation rather than the other options (at least in the earlier versions) — that’s probably why it is seen so often there. In other corners of the industry, SAML2 has been more common over the past decade. Of course, in the last several years, OAuth2 and OIDC usage has gained significantly.
WS-Federation, per the v1.0 spec, “defines mechanisms that are used to enable identity, account, attribute, authentication, and authorization federation across different trust realms” that was created by BEA, IBM, Microsoft, RSA Security and VeriSign. It has since been codified as an OASIS standard. The current generation, v1.2, was published in May, 2009. WS-Federation v1.1 was released in December, 2006. WS-Federation v1.0 was released in July, 2003 (published on soapxml.org a microsoft domain that preceded OASIS and W3C, which have since published many of the WS-* specs). In the v1.0 spec, the Passive Requestor Profile (could only find a copy on ibm.com) and Active Requestor Profiles (again, only found an IBM copy) were split out as separate specifications. In 2005, a Web SSO Interoperability Profile was published for WS-Federation v1.0 and its associated specifications.
This protocol builds on top of WS-Security, WS-Trust, WS-SecurityPolicy, and other WS-* specs (along with numerous supporting specifications) to build a federated identity protocol. WS-Federation grew out of Web Services Security (WS-Security) paradigm and a desire to utilize the same paradigm with web applications (passive requestors). WS-Federation bridges the gap between WS-Security (which is geared towards active requestors like SOAP Web Services) and web browsers and web servers.
Originally, the active vs. passive requestor terminology described whether the client could build proper SOAP messages described in the WS-Trust and WS-Security specifications. A passive requestor didn’t have native support for building the SOAP messages; an active requestor did have that support. Having a standardized mechanism for mapping WS-Security & WS-Trust functionality onto “passive” requestors (namely, web browsers) was enormously helpful. However, the active requestors (that could already build SOAP messages without issue) didn’t have the need for a higher-level spec that could be accomplished by WS-Trust and WS-Security directly. So, in the later version of the WS-Federation spec, the active requestor profile has been removed. Today, active requestors describe anything that can be addressed directly by the WS-Trust specification.
The WS-Security specification provides the basic mechanisms for securing SOAP messages. This standard provides for the following to SOAP messages:
WS-Federation v1.2 uses WS-Security v1.0.
An example of WS-Security being used with a SAML2 assertion can be found here.
The WS-SecurityPolicy specification extends the WS-Policy spec functionality to describe the constructs laid out in WS-Security. From the WS-SecurityPolicy v1.2 spec, “WS-Policy defines a framework for allowing web services to express their constraints and requirements. Such constraints and requirements are expressed as policy assertions.” These assertions “define a set of security policy assertions for use with the WS-Policy framework with respect to security features provided in WS-Security, WS-Trust and WS-SecureConversation.” Basically, WS-Policy and WS-SecurityPolicy provide a mechanism that allows a SOAP Web Service to describe its security requirements.
The OASIS organization published a specification with numerous examples of WS-SecurityPolicy policies in the WS-SecurityPolicy Example Specification.
The WS-Trust spec builds on the WS-Security base by:
WS-Trust clients can make the following types of calls:
An example of a typical WS-Trust request and response can be found here.
The following diagram (reused from an earlier blog post dealing with WS-Trust) shows a typical WS-Trust interaction with an STS.
The WS-Federation spec describes the following actors in the Passive Requestor Profile.
Requestor: a web client, typically a web browser, that is interacting with the Resource and IdPs.
Resource: A protected web endpoint that relies upon the IdPs for authentication and authorization of the Requester.
Resource IdP/STS: The IdP/STS that the Resource trusts. The spec uses the WS-Trust terminology of Security Token Service (STS). To provide continuity with the articles I’ve been writing, I’m using Identity Provider/Security Token Service (IdP/STS). These are essentially the same.
Requestor’s IdP/STS: The IdP/STS that owns the Requestor’s credentials. Has a trust relationship with the Resource IdP/STS.
Relying Party(RP): A web application, service, or other web endpoint that consumes security tokens issued by an IdP/STS. The Resource is a Relying Party.
Any actor playing the requester part that is not able to construct a SOAP message is referred to as a passive requester. This profile describes how to map the WS-Trust and WS-Security constructs to something that the passive requester can easily work with. The profile describes both sign-on and sign-off.
Per the spec, this profile describes how WS-Federation “is applied to Web requestors such as Web browsers that cannot directly make Web Service requests.” Web Browsers (and other web clients) participating in WS-Federation protocols cannot generally build or parse the underlying WS-Security and WS-Trust messages. This spec “describes the mechanisms for requesting, exchanging, and issuing security tokens within the context of a web requestor.” (again, from the spec). These web requestors (like browsers) use different message formats than the underlying specs, but achieve the same result — the messages are just now in a format that the web requestor can easily deal with.
There is no easy way to directly issue SOAP requests from web requestors — that’s the fundamental problem with using WS-Security and WS-Trust as the basis of a web application federation solution. The message exchange must be grafted onto HTTP 1.1 GET operations, POST operations, HTTP redirects, cookies and other HTTP-spec features — but still “conform as closely as possible to the WS-Trust and WS-Security protocols for token acquisition”, per the spec.
A typical web requestor will do the following during the message exchange (this represents the most complex federation scenario with the federation relationship existing between two IdPs):
In some cases the requestor’s IP/STS has the needed information cached (ie, the user has an active authenticated session with the requestor’s IP/STS) to be able to issue a token. Likewise, if the resource’s IdP/STS has an active authenticated session for the user, then there is no need to redirect the user to the requestor’s IP/STS.
The sequence diagram below shows the interaction between the actors when the resource has its own IdP/STS.
The diagram below shows the actors described in the sequence diagram above.
Federation relationship between two IdPs
The next sequence diagram shows the actor interaction when there is only a requestor IdP/STS (one IdP/STS). This sequence diagram represents the following steps:
The actors in the sequence diagram above have the following relationships.
Federation relationship between requestor’s IdP and Resource
The WS-Federation HTTP request to the requestor IdP/STS has the following format (examples from the spec):
GET *resourceSTS*?*parameters *HTTP/1.1
POST *resourceSTS*?*parameters *HTTP/1.1
The parameters are:
wtrealm: The URI of the requesting realm. This serves the same purpose as the AppliesTo field in the WS-Trust spec. This parameter is required.
wfresh: indicates the freshness requirements (the maximum authentication age in minutes). This serves the same purpose as the Freshness field in the WS-Trust spec. An IdP/STS should not issue a token with a longer age. This parameter is optional.
wauth: The required authentication level. This parameter is equivalent to the wst:AuthenticationType element in the WS-Trust spec and uses the same URIs. This parameter is optional.
wreq: Specifies a wst:RequestSecurityToken element or full WS-Trust message is used. If not specified, then assume the IdP/STS knows what token format should be returned. This parameter is optional.
The GET request is the more common.
Additional parameters are described here.
As an example, an ADFS 2.0 WS-Federation request looks similar to:
The response to this request will usually be a redirect to a login workflow that is outside the scope of the WS-Federation spec.
At the completion of the login workflow, the user is redirected back to the WS-Federation endpoint with an implementation specific authentication session tracking cookie (for the IdP).
The wresult field contains a wst:RequestSecurityTokenResponse element as specified in the WS-Trust spec. The RSTR contains the security token that the resource needs to build a security context. The WS-Federation spec requires that SAML assertions be supported as the security token, but other token formats are allowed (as long as the IdP/STS and Resource support it). The ADFS & Azure Active Directory (AAD) WS-Federation always use SAML v1.1 assertions as the security token — other implementations will likely have a different default token.
Section 13.6 of the WS-Federation specs outlines the minimum requirements that implementations must meet for sign-on.
Support for sign out is optional; though, most enterprise-grade implementations are going to provide support. Ramifications of supporting and processing signout messages are dependent upon the type of application. An example from the spec states, “the implication of sign-out on currently active transactions is undefined and is resource-specific.” A federated sign-out will clean up any remaining state (or tokens) that exist within the federation actors that is no longer needed; it serves as a hint that actors can remove any state information that describes the user’s session.
The clearing of the user’s session is performed asynchronously and the messages that trigger it may have unexpected delays in arrival, arrive multiple times (so signout processing must be idempotent), or may not arrive at all. The sign-out messages are unreliable; correct and secure operation of the system must be ensured with or without the signout messages actually arriving. The spec describes this as “messages serve as hints only.”
Sign out can be initiated from any one of four different places including:
For the first three locations, the Requestor must be redirected to the Requester IdP/STS (that authenticated the end user). The Requester IdP/STS must send clean-up messages to all Resource IdP/STSs and Resources that it has issued security tokens for the user’s current session.
There are two phases: sign-out and clean-up. Each phase has its own message format.
The sign-out message looks like:
wa: Action to be performed (must be “wsignout1.0”). This parameter is required.
wreply: The URL to redirect the user to after signout. This parameter is optional.
The clean-up message format looks like:
Unlike the SOAP-based sign out message format described in Section 4 of the WS-Federation spec, the Passive Requestor (web requestor) doesn’t dictate how the the authenticated user is specified in the signout message. It is assumed that the IdP/STS will will implement its own mechanism for tracking user sessions that will inform it of which user the session belongs to — it will typically be a cookie.
Home Realm Discovery is the process of identifying to which security realm the user belongs. The Home Realm Discovery is a web-based service that uses a proprietary (non-spec defined means) to determine the requestor’s home realm without user interaction.
In the sign-on sequence diagrams earlier in this post, you saw the point where the IdP/STS redirects to this service.
The spec mentions several approaches to determining a user’s realm including a fixed realm, requestor IP-based, prompt the user, discovery service, and shared cookie. The first three mechanisms are common enough and generally understood. The spec discusses the discovery service and places some structure around its operation. The shared cookie approach is not described in the WS-Federation spec, but is another one of those things that has been done before. There are security implications to this approach that may be frowned upon in some contexts.
If a Home Realm Discovery Service is used (part of the IdP/STS, generally), the sign-on sequence diagrams earlier in this post show the point where the IdP/STS redirects to this service. Support for this service is optional, but some type of mechanism to determine the user’s home realm is required.
The WS-Federation spec defines a mechanism (Section 5 and Section 13.2.5) for retrieving more information about a user — the Attribute Service. This is the equivalent of the SAML2 Artifact Profile functionality or OIDC UserInfo endpoint.
The WS-Federation spec defines what the request and response URL messages look like, but it does not specify what the XML message containing the attributes that are returned looks like. It does provide high-level guidance for the XML attribute document format; it also suggests that the WS-Trust protocol and message formats could be used for this service. Furthermore, the spec doesn’t define how privacy and security requirements for this service should be implemented — this is obviously a critically important component of this service.
Support for this service is optional, but any enterprise-grade implementation would offer the functionality in some form.
The Pseudonym Service is a special type of Attribute Service which can expose “alternate identity information” (and tokens to support this) for principals (authenticated users). This works as a mapping service between identities in different realms — maybe John Smith who is known as john.smith internally is exposed as email@example.com to a SaaS solution.
Support for this service is optional, but any enterprise-grade implementation would offer the functionality.
The details we’ve covered here represent the most common uses of WS-Federation. Although, the original WS-Federation spec described both an active and passive profile, the most recent version of the spec only describes the passive profile because the active requestors simply use WS-Trust directly.
Robert C. Broeckelmann Jr.
Meet our Experts
You're doing big things, and big things come with big challenges. We're here to help.