WS-Federation
WS-Federation is an OASIS standard specification that defines mechanisms for federating security realms to enable authorized access to resources managed in one realm by entities in another, through the brokering of identity, attribute, authentication, and authorization assertions while preserving the privacy of federated claims.[1] Version 1.2 of the specification, approved as an OASIS Standard in May 2009, builds upon foundational Web services protocols including WS-Security for message-level security, WS-Trust for security token issuance and validation, and WS-Policy for expressing communication requirements.[2][1] At its core, WS-Federation facilitates the establishment of trust relationships between security realms—distinct units of security administration or trust domains—forming a federation where realms act as producers or consumers of identity and authorization data.[1] It supports two primary requestor profiles: passive requestors, such as web browsers that use HTTP redirects and form posts to interact with services, and active requestors, which are SOAP-based applications that directly exchange messages with web services.[1] Central to this framework is the Security Token Service (STS), a runtime component that issues, renews, and validates security tokens to enable single sign-on (SSO) and cross-realm authentication without requiring users to re-authenticate.[1] The protocol uses XML, SOAP, and WSDL extensibility models to integrate seamlessly with other WS-* specifications, allowing for flexible topologies such as direct trust, brokered trust, and sign-out propagation across federated environments.[1] By extending WS-Trust's token exchange mechanisms to HTTP contexts, WS-Federation addresses scenarios involving diverse token types and trust relationships, making it a key enabler for enterprise identity federation in web services architectures.[1] Although originating in the mid-2000s as part of the broader WS-* family developed by industry consortia including IBM, Microsoft, and others, it remains relevant for legacy and hybrid systems supporting federated identity management.[2]Overview
Definition and Scope
WS-Federation, or Web Services Federation, is an OASIS standard specification that defines mechanisms to enable identity, authentication, attribute, and authorization federation across different security realms in web services environments. Version 1.2 of the specification was approved as an OASIS Standard on May 1, 2009.[1][2] It allows authorized access to resources managed in one realm to be granted based on identities and attributes from another realm, using extensible models based on XML, SOAP, and WSDL.[1] This protocol supports the brokering of security tokens that encapsulate claims about a principal, facilitating secure interoperability without requiring a complete standalone security solution.[1] The scope of WS-Federation is primarily targeted at enterprise scenarios involving SOAP-based web services, where it establishes trust relationships between identity providers and service providers.[2] It enables single sign-on and attribute exchange by allowing service providers to delegate authentication to trusted identity providers, avoiding the need for direct user authentication at each provider.[1] The protocol accommodates various token formats, trust topologies, and infrastructures, including both active requestors (such as SOAP-based applications) and passive requestors (such as web browsers via HTTP redirects).[1] Central to WS-Federation's model are key concepts including the Security Token Service (STS), which is a web service that issues, renews, and validates security tokens containing claims based on verified evidence or assertions from trusted sources.[1] The relying party (RP) refers to a web application or service that relies on these tokens issued by an STS for access decisions and authorization.[1] The home realm (HR) denotes the security domain or trust realm where a user's identity is managed, typically hosting the STS that authenticates the user and issues tokens on their behalf.[1] WS-Federation builds on WS-Trust for the issuance and validation of these security tokens.[1]Purpose and Key Benefits
WS-Federation primarily aims to enable the federation of identity, attribute, authentication, and authorization information across different security realms, allowing secure access to resources in one domain for users authenticated in another without requiring direct credential sharing.[1] By defining mechanisms for token issuance, exchange, and validation, it facilitates single sign-on (SSO) in distributed systems, where a user authenticates once with a trusted identity provider and gains access to multiple services across trust boundaries.[1] This addresses key identity management challenges in enterprise environments by supporting secure token delegation and attribute-based authorization, thereby reducing redundant authentication prompts and enhancing user experience in federated setups.[3] A core benefit of WS-Federation is its emphasis on security through token-based trust models, where security tokens—such as those issued by a Security Token Service (STS)—carry claims about the user without exposing underlying credentials, minimizing risks associated with credential propagation across domains.[1] This approach promotes scalability for large-scale web services by enabling efficient handling of authentication in heterogeneous infrastructures, supporting both active clients (e.g., SOAP applications) and passive clients (e.g., web browsers) via distinct federation profiles.[3] Interoperability is another key advantage, as it builds on established WS-* standards to allow seamless integration across diverse platforms and vendors, fostering broader adoption in enterprise federated identity scenarios.[1] Additionally, WS-Federation enhances privacy and flexibility by incorporating pseudonymity through pseudonymous identifiers and just-in-time provisioning of user attributes, ensuring that only necessary information is disclosed during federation while complying with privacy constraints.[1] These features enable authenticated but anonymous interactions, protecting user identities in scenarios where full disclosure is unnecessary, and support dynamic trust brokering to adapt to varying security requirements across realms.[1] Overall, it provides a robust framework for reducing administrative overhead in identity management while maintaining high levels of security and compliance in distributed applications.[4]History
Initial Development
WS-Federation originated as a collaborative effort initiated in July 2003 by major technology companies to establish standardized mechanisms for identity federation within web services environments. The specification, titled Web Services Federation Language (WS-Federation) Version 1.0, was published on July 8, 2003, primarily authored by representatives from BEA Systems, IBM, Microsoft, RSA Security, and VeriSign, including editors Chris Kaler from Microsoft and Anthony Nadalin from IBM. This joint initiative built directly on the foundational WS-Security specification, which had been released earlier in 2002, to extend secure messaging capabilities into broader federation scenarios for authentication and authorization across disparate trust realms.[5][6] The primary motivations stemmed from the rapid growth of web services adoption in enterprise settings, particularly SOAP-based applications, where proprietary single sign-on (SSO) solutions like Microsoft's Passport highlighted the need for open, interoperable standards to enable secure cross-domain identity sharing without centralized control. These early developers aimed to reduce identity management costs, streamline user experiences through seamless SSO, and enhance security for inter-enterprise communications by allowing organizations to federate identity, authentication, and authorization data while supporting privacy features like pseudonyms and optional local identities. By addressing gaps in existing protocols, WS-Federation sought to broker trust relationships and facilitate security token exchanges in a modular manner compatible with XML, SOAP, and WSDL extensibility models.[5][6] Key early milestones included the release of the initial draft specification in 2003, which outlined both active and passive requestor profiles to support diverse client types, from SOAP services to web browsers via HTTP. A notable demonstration of interoperability occurred in September 2003, when Microsoft CEO Bill Gates and IBM Senior Vice President Steve Mills showcased WS-Federation's capabilities in a cross-vendor scenario at an event in New York City. This work laid the groundwork for incorporating security token service concepts, later refined in related standards like WS-Trust in 2005, to handle token issuance and validation more robustly. The specification's development as part of the broader IBM-Microsoft web services security roadmap underscored its role in transitioning from proprietary federation approaches to industry-wide standards.[6]Standardization and Versions
WS-Federation was submitted to the Organization for the Advancement of Structured Information Standards (OASIS) in late 2006 as version 1.1, with the OASIS Web Services Federation (WSFED) Technical Committee formed in 2007 to advance it toward standardization.[7] The specification progressed through committee drafts, culminating in approval as an OASIS Standard in May 2009, establishing WS-Federation version 1.2 as the current and most mature iteration.[2] No subsequent major versions have been released by OASIS, reflecting the protocol's stability and widespread adoption in enterprise identity federation scenarios. The version history of WS-Federation began with version 1.0, an initial draft released in July 2003 by BEA Systems, IBM, Microsoft, RSA Security, and VeriSign, which focused on foundational mechanisms for identity, authentication, and authorization federation across trust realms using Web services protocols.[5] Version 1.1 followed in December 2006, published by BEA Systems, BMC Software, CA Inc., IBM, Layer 7 Technologies, Microsoft, Novell, and VeriSign, enhancing the passive requestor profile to enable browser-based single sign-on (SSO) via HTTP redirects and POST bindings.[8] Version 1.2, approved as the OASIS Standard in May 2009 by the WSFED Technical Committee, built upon these foundations with enhancements for broader interoperability.[1] Key changes across versions emphasized incremental improvements in usability and security. In version 1.1, sign-in and sign-out mechanisms were introduced through the passive requestor profile, allowing web browsers to federate identity without SOAP messaging by using HTTP parameters likewa=wsignin1.0 for token requests and wa=wsignout1.0 for logout propagation across realms.[8] Version 1.2 refined these capabilities with enhanced security token exchange protocols, support for compound tokens that combine multiple token types (such as SAML assertions), and tighter integration with WS-Trust version 1.3 for token issuance and validation.[1] It also added refinements for attribute queries via dedicated Attribute Services and pseudonym handling through Pseudonym Services to improve privacy and selective disclosure in federated environments.[1] These updates have not been significantly altered since 2009, as the specification has achieved sufficient maturity for ongoing implementations.[2]
Technical Architecture
Core Components
WS-Federation relies on a set of core roles and entities to facilitate secure identity federation across different security realms. The Identity Provider (IdP), also referred to as an IP, serves as the entity responsible for authenticating end users (principals) and issuing security tokens that assert their identity and attributes.[1] The Relying Party (RP) is the service or application that consumes these tokens to authorize access for the authenticated principals, relying on the IdP's assertions without performing its own authentication.[1] At the heart of this model is the Security Token Service (STS), a web service that issues, validates, and manages security tokens on behalf of the IdP, often extending its functionality to handle token lifecycle operations.[1] To enable seamless interactions, WS-Federation incorporates Home Realm Discovery, a mechanism that identifies and routes requests to the appropriate IdP for a given principal, typically through user input, cookies, or a dedicated discovery service.[1] Supporting this are key message types defined in conjunction with WS-Trust: the Request Security Token (RST) message, used by RPs or intermediaries to solicit tokens from an STS, and the Request Security Token Response (RSTR) message, which delivers the issued token along with any associated proofs or metadata.[1] Token types are flexible and integrate with WS-Trust standards, commonly including SAML assertions for identity claims and X.509 certificates for cryptographic proofs, allowing RPs to specify preferred formats in requests.[9] The trust model in WS-Federation is established through relationships between security realms, supporting both bilateral trusts—direct agreements between an IdP and RP—and brokered trusts, where intermediaries facilitate token exchange across multiple parties.[1] Configuration and trust establishment occur via metadata exchange, using WS-Federation metadata documents that describe endpoints, supported token types, and signing keys to ensure interoperability and security.[1] These components collectively enable the federation process by providing the foundational structure for token-based authentication and authorization.[1]Federation Process
The federation process in WS-Federation enables secure identity delegation and single sign-on across disparate security realms by facilitating the exchange and validation of security tokens between relying parties (RPs) and identity providers (IdPs). When a user attempts to access a protected resource at an RP, if no valid token or session is present, the RP redirects the user's browser to the IdP's sign-in endpoint using an HTTP GET or POST request that includes the action parameterwa=wsignin1.0 to indicate a federation sign-in operation.[1] The request also specifies parameters such as wreply for the return URL to the RP and wtrealm to denote the target realm, allowing the IdP's Security Token Service (STS) to authenticate the user—typically via local credentials or federated means—and issue a signed security token encapsulating the user's identity and attributes.[1] Upon successful authentication, the STS redirects the user back to the RP with the token embedded in the response (via wresult), where the RP validates the token's signature and claims against its trusted STS configuration before granting access.[1]
WS-Federation supports two primary profiles for this token exchange process, tailored to different client types. The Passive Requestor Profile is designed for web browser-based interactions, leveraging HTTP redirects and form posts to transport WS-Trust-derived messages without requiring client-side SOAP support; it initiates the flow through the RP's discovery of the appropriate IdP and culminates in token delivery via browser redirection, enabling seamless single sign-on for passive clients.[1] In contrast, the Active Requestor Profile accommodates rich clients or services capable of direct SOAP communication, where the requestor issues a WS-Trust RequestSecurityToken (RST) message to the STS for token issuance or exchange, followed by validation at the RP through a similar STS inquiry, supporting scenarios like brokered authentication in enterprise applications.[1]
The sign-out process ensures coordinated logout across federated realms to invalidate sessions and tokens. It begins when the user accesses a sign-out URL at the RP or IdP, triggering a redirect to the IdP's endpoint with the parameter wa=wsignout1.0 to signal a federation sign-out; the IdP's STS then propagates the logout notification—via a one-way SignOut message including the user's sign-out basis (e.g., a session identifier)—to trusted RPs and other IdPs in parallel, prompting each to clear local session state and tokens.[1] A subsequent cleanup phase, invoked via wa=wsignoutcleanup1.0, confirms the logout and handles any residual artifacts, though the process is treated as a best-effort hint due to its unreliable, fire-and-forget nature.[1]
Error handling in the federation process relies on standardized fault mechanisms to address issues like token invalidity or trust failures without disrupting the overall flow. For instance, if a token is expired or lacks required claims, the STS or RP returns a WS-Trust fault such as fed:NeedFresherCredentials, prompting the client to re-authenticate; similarly, trust mismatches trigger faults with codes like fed:SpecificMetadata to indicate missing security details, allowing the requestor to resubmit with additional context.[1] These faults are embedded in SOAP responses or HTTP error pages, ensuring interoperability while minimizing exposure of sensitive information.[1]
Specifications
Protocol Mechanics
WS-Federation operates through a set of defined message exchanges that facilitate identity federation across security realms, primarily using HTTP-based parameters for web scenarios and SOAP for more structured interactions. The core sign-in request is initiated via an HTTP GET or POST to the security token service (STS) endpoint, employing specific parameters to convey the action and context. The required parameterwa specifies the action as wsignin1.0 for sign-in operations, while wtrealm identifies the URI of the relying party (RP) realm requesting the authentication. An optional wctx parameter carries an opaque context value from the RP, which the STS echoes back in the response to maintain session continuity.[1]
Upon successful authentication, the STS responds with an HTTP redirect or direct POST containing the wresult parameter, which encapsulates the security token in a signed XML structure, typically a WS-Trust RequestSecurityTokenResponse element. This token includes claims about the authenticated principal and is formatted to be processed by the RP. For token exchange scenarios, WS-Federation integrates directly with WS-Trust 1.3 mechanisms, where a RequestSecurityToken (RST) message requests issuance or exchange of tokens, and the response is a RequestSecurityTokenResponse (RSTR). These messages support various token types and lifetimes, enabling the delegation of authentication across realms without direct credential sharing.[1][10]
Token confirmation in WS-Federation leverages WS-Trust 1.3's methods to bind the token to the presenter securely. The bearer confirmation method treats the token as valid upon simple presentation, relying on transport security without proof-of-possession, identified by the URI http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer. Holder-of-key confirmation requires the presenter to demonstrate possession of a key associated with the token, often via an encrypted key or signature, using URIs like http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey or public key variants for enhanced security. Sender-vouches confirmation allows a third party to vouch for the token's holder, typically through an OnBehalfOf element in the RST, without direct proof from the end user.[10]
Endpoints and capabilities in WS-Federation are advertised through XML metadata documents, conforming to WS-Policy and WS-MetadataExchange patterns. For passive requestors, such as web browsers, the metadata includes elements like <wsfed:PassiveRequestorEndpoint>, which specifies the URI for sign-in requests, often wrapped in <fed:PassiveRequestorEndpoints> with an <wsa:Address> child. This allows relying parties to discover federation partners dynamically without hard-coded configurations.[1]
Security in the protocol mandates XML digital signatures on all tokens and responses using elements from WS-Security, such as <ds:Signature>, to ensure integrity and authenticity. Encryption of token content is optional but recommended for sensitive claims, applied via XML Encryption standards. Messages bind to HTTP transports for browser-based flows (e.g., via 302 redirects or form posts) or SOAP for programmatic access, with TLS required for confidentiality in both cases.[1]
Related WS-* Standards
WS-Federation relies on WS-Trust 1.3 as a core dependency for token issuance and validation through interactions with a Security Token Service (STS), utilizing operations such as Issue and Validate to facilitate secure token exchanges in federated environments.[1] This integration extends WS-Trust 1.3's Request Security Token (RST) and Request Security Token Response (RSTR) messages to include support for pseudonyms and attributes, enabling WS-Federation's passive and active profiles where passive requestors use HTTP redirects and active ones employ SOAP-based communications.[1] WS-Security provides the foundational message-level security for WS-Federation, incorporating mechanisms like XML signatures and encryption to protect federation messages and tokens during transit.[1] Complementing this, WS-SecureConversation integrates to manage session security tokens, allowing for the establishment and maintenance of secure, stateful sessions across different security realms in federated scenarios.[1] Further integrations include WS-MetadataExchange, which supports the discovery of federation endpoints through Metadata Endpoint References (MEPRs) and elements like<mex:MetadataSection>, streamlining the configuration of trust relationships.[1] WS-Policy enables the expression of security requirements, such as claim types and applicable policies for attribute and pseudonym services, with compatibility for WS-Policy versions 1.2 and 1.5 to assert federation metadata.[1]
WS-Federation 1.2 is based on WS-Trust 1.3. These standards collectively enable protocol mechanics like token exchange by providing the necessary security and discovery frameworks.[1]
Implementations and Adoption
Major Software Implementations
Active Directory Federation Services (ADFS), Microsoft's primary implementation of WS-Federation, has served as a key identity provider (IdP) and relying party (RP) since its introduction in Windows Server 2008, supporting version 1.2 with both passive and active request profiles for federated single sign-on (SSO).[11] ADFS integrates seamlessly with Active Directory and extends to hybrid cloud environments through Azure Active Directory (Azure AD), enabling secure token exchange across domains.[12] In ADFS versions from 2019 onward, enhancements include improved support for hybrid deployments, maintaining compatibility with WS-Federation while incorporating modern protocols.[11] IBM Security Verify Access (formerly IBM Security Federated Identity Manager and Tivoli Federated Identity Manager) provides robust WS-Federation support for establishing trust relationships and token brokering in enterprise environments, configurable via its Passive Profile for SSO federations. As of version 10.0.9 (January 2025), it continues to handle WS-Federation alongside other standards like WS-Trust, facilitating identity mapping and secure access across disparate systems.[13] WSO2 Identity Server implements WS-Federation through its Passive Security Token Service (STS), which issues SAML 2.0 tokens for authentication and supports federation as both IdP and RP in Java-based deployments. As of version 7.2.0 (2025), this open-source solution emphasizes interoperability, allowing configuration of WS-Federation connections for web applications and integration with Microsoft ecosystems.[14] In the Microsoft .NET ecosystem, Windows Identity Foundation (WIF) and its successors in ASP.NET Core provide framework-level support for handling WS-Federation tokens, enabling passive authentication in claims-based applications.[15] For Java environments, libraries like OpenSAML incorporate WS-Federation extensions for parsing and validating tokens, often used in custom implementations alongside SAML support.[16] As of 2025, WS-Federation remains in use within legacy enterprise systems, particularly those reliant on ADFS, though adoption has declined in favor of protocols like OAuth 2.0 and OpenID Connect for new deployments.[17]Real-World Use Cases
WS-Federation facilitates enterprise single sign-on (SSO) by enabling federated access to internal applications across corporate boundaries, allowing employees to authenticate once and access partner portals without re-authentication. For instance, organizations use it to provide seamless login for internal users to external business partner systems, reducing administrative overhead and improving user productivity.[11] In cloud-hybrid scenarios, WS-Federation integrates on-premises Active Directory Federation Services (ADFS) with SaaS providers to secure API access in SOAP-based services, such as extending authentication from local networks to Azure-hosted workloads. This setup supports hybrid applications where parts run on-premises and others in the cloud, ensuring consistent identity management without full migration.[18] For B2B federation, WS-Federation enables supply chain partners to share identity attributes for just-in-time authorization in web services, allowing secure collaboration without creating separate user accounts. Examples include direct federation between Microsoft Entra tenants and external organizations using ADFS as the identity provider for B2B scenarios.[19] WS-Federation aids legacy migration by bridging older WS-* systems to modern identity providers, maintaining token-based trust in environments like SharePoint or SOAP web services while transitioning to cloud-native solutions.[20] In practice, WS-Federation is best suited for SOAP environments due to its protocol overhead, making it less common for RESTful APIs where lighter alternatives prevail.[21]Comparisons
With SAML
WS-Federation and SAML share the goal of enabling federated identity across trust domains but differ fundamentally in design. WS-Federation leverages URL parameters, such aswa=wsignin1.0 for the action and wtrealm for the target realm, to facilitate authentication redirects, while relying on WS-Trust for issuing security tokens that often encapsulate SAML assertions.[22] In contrast, SAML employs standalone XML assertions exchanged through HTTP bindings like POST or Redirect, using Base64-encoded SAMLRequest parameters alongside RelayState to preserve context during browser-based flows.[22] This makes WS-Federation more aligned with web services architectures, whereas SAML prioritizes browser-mediated single sign-on for web applications.[23]
In terms of usage, WS-Federation is tailored for Microsoft-centric enterprise environments, particularly those involving SOAP-based web services and tools like Active Directory Federation Services (ADFS), making it a natural fit for integrating with Azure and SharePoint.[3] SAML, however, functions as a vendor-agnostic protocol for cross-domain web SSO, supporting a wider array of identity providers and service providers beyond Microsoft ecosystems. WS-Federation's integration with WS-Trust enables flexible claim-based authentication in service-oriented setups.
WS-Federation's strengths lie in its simplicity for .NET developers, enabling straightforward implementation within Microsoft stacks, though this comes at the cost of reduced interoperability outside those boundaries.[22] SAML, while more verbose due to its XML structure, excels in non-Microsoft settings, achieving higher adoption in sectors like higher education through federations such as InCommon, where it supports seamless access across academic institutions.[24] Regarding interoperability, both can transport SAML tokens—such as SAML 1.1 or 2.0 assertions—facilitating hybrid scenarios, but WS-Federation's metadata exchange follows WS-MetadataExchange specifics, differing from SAML's standardized entity descriptors.[22][23][25]