Category: Federation & SSO

WS-Federation

Also known as: WS-Fed, Web Services Federation, WS-Federation Protocol

Simply put

WS-Federation is a standard that lets users sign in once and access applications that trust the same identity provider, even when those applications sit in different systems or organizations. It is an XML-based protocol commonly used for single sign-on, particularly with older Windows-based web applications. It works by allowing an identity provider to issue a security token that a relying application accepts as proof of the user's identity.

Formal definition

WS-Federation is an XML-based federation protocol, standardized as WS-Federation 1.2 by OASIS, that conveys identity and authentication information across security boundaries to enable web single sign-on. It builds on the WS-Security and WS-Trust specifications, which support different security token types, infrastructures, and trust topologies, and it defines mechanisms to negotiate the issuance of a security token from an identity provider (or Security Token Service) to a relying party. In most deployments it is used for browser-based SSO to applications, and it is frequently associated with legacy Windows-based web applications and Active Directory Federation Services (AD FS). WS-Federation addresses federated authentication and token issuance; authorization decisions at the relying party and identity lifecycle management are typically out of scope for the protocol itself. Note that the exact token formats, trust configuration, and profile behavior vary by implementation.

Why it matters

WS-Federation remains significant because it underpins single sign-on for a substantial base of legacy Windows-based web applications, many of which were built around Active Directory Federation Services (AD FS) and the WS-* family of specifications. For organizations that adopted Microsoft-centric identity infrastructure before newer protocols became dominant, WS-Federation is often the mechanism that continues to broker browser-based SSO across security boundaries. Understanding it is therefore essential for teams maintaining, auditing, or migrating these environments.

For security architects and IAM engineers, WS-Federation matters primarily as a protocol encountered during modernization efforts. Because it conveys identity and authentication information across networked systems by having an identity provider or Security Token Service issue a security token that a relying party trusts, misconfigured trust relationships, token handling, or Security Token Service settings can undermine the intended SSO security boundary. Since token formats and trust configuration vary by implementation, teams cannot assume uniform behavior across vendors or deployments and should validate the specific profile in use.

WS-Federation also has a defined scope that is important to respect. It addresses federated authentication and token issuance, but authorization decisions at the relying party and identity lifecycle management are typically out of scope for the protocol itself. Treating WS-Federation as a complete access-management solution rather than an authentication and token-issuance federation protocol can lead to gaps where governance, provisioning, and authorization controls are wrongly assumed to be handled by the protocol.

Who it's relevant to

Security Architects

Architects evaluating or maintaining Microsoft-centric identity infrastructure need to understand where WS-Federation fits, how its trust topologies rely on WS-Security and WS-Trust, and how it compares to newer federation options when planning modernization. Because authorization and identity lifecycle management are out of scope for the protocol, architects must ensure those concerns are addressed by other components.

IAM Engineers

Engineers operating AD FS or comparable Security Token Services work directly with WS-Federation token issuance and relying-party trust configuration. Since token formats and profile behavior vary by implementation, they must validate the specific deployment's settings rather than assume standardized behavior.

System Administrators

Administrators supporting legacy Windows-based web applications frequently encounter WS-Federation as the SSO mechanism connecting those applications to an identity provider. They are often responsible for the day-to-day trust and configuration details that keep browser-based SSO functioning.

Compliance Officers

Compliance leads auditing federated access should recognize that WS-Federation covers authentication and token issuance across security boundaries but does not itself handle authorization decisions at the relying party or identity lifecycle management, so those governance controls must be evidenced separately.

Inside WS-Fed

Identity Provider (IP/STS)

In WS-Federation, the Identity Provider typically acts as a Security Token Service (STS) that authenticates the principal and issues security tokens. Note that WS-Federation defines the federation protocol and message flows rather than the authentication mechanism itself, which depends on the STS configuration.

Relying Party (Resource/RP-STS)

The application or service that consumes a security token to make authorization decisions. The relying party trusts tokens issued by a federated STS. WS-Federation governs how the relying party redirects the principal to the IP and how the resulting token is returned, not what the relying party does internally with the token's claims.

Security Token Service (STS)

A service that issues, validates, and exchanges security tokens. WS-Federation builds on WS-Trust, which defines the STS request/response semantics. The STS is the component that performs identification and authentication and packages the result as claims in a token; authorization decisions are typically made downstream by the relying party.

Security Tokens and Claims

WS-Federation carries security tokens, commonly SAML assertions in many deployments, that contain claims about the authenticated principal. A signed token attests to integrity and issuer, which is distinct from encryption of the token payload; depending on configuration a token may be signed, encrypted, or both.

Web (Passive) Requestor Profile

The profile that enables browser-based single sign-on using HTTP redirects and query parameters (such as wa, wtrealm, and wctx in typical implementations), for clients that cannot participate directly in SOAP-based WS-Trust exchanges.

Active Requestor Profile

The profile for SOAP-capable clients that interact directly with the STS using WS-Trust messages, as opposed to the redirect-based flow used by browsers.

Metadata and Trust Configuration

Federation metadata that describes endpoints, supported token types, and signing certificates used to establish trust between the identity provider and relying parties. The exact metadata format and exchange mechanism vary by vendor and deployment.

Common questions

Answers to the questions practitioners most commonly ask about WS-Fed.

Is WS-Federation just an older or alternative version of SAML?

No. While both are XML-based federation standards used for web single sign-on, they are distinct specifications with different structures. WS-Federation is part of the WS-* (Web Services) family and defines its own request/response syntax, whereas SAML 2.0 defines its own assertion format, bindings, and profiles. In many deployments WS-Federation actually carries SAML assertions as its security tokens, but the federation protocol layer itself is separate. Treating them as interchangeable versions of the same standard is inaccurate; they are parallel approaches that can coexist and sometimes interoperate through shared token formats.

Does WS-Federation handle authorization for federated applications?

Not directly. WS-Federation is primarily concerned with the federated authentication step and the exchange of security tokens containing identity claims across trust boundaries. Any authorization decisions, determining what the authenticated principal may do, are typically made by the relying party application or a separate policy decision point based on the claims delivered in the token. WS-Federation can convey attributes and claims that an authorization process later consumes, but the federation protocol itself does not define or enforce access control models such as RBAC or ABAC.

What token formats can WS-Federation use for security tokens?

WS-Federation is designed to be token-format agnostic and relies on the broader WS-Trust and WS-Security specifications for token handling. In most deployments the security tokens are SAML assertions, but the specification does not mandate a single format. Because the framework separates the federation protocol from the token format, implementations can in principle carry other token types. Verify the specific formats supported by your identity provider and relying party, as this varies by vendor and product configuration.

How do relying parties establish trust with an identity provider in WS-Federation?

Trust is typically established out of band by exchanging metadata and configuring signing certificates so the relying party can validate tokens issued by the identity provider. The relying party validates the signature on the received security token to confirm it was issued by a trusted authority and was not altered. Note that a signed token establishes integrity and issuer authenticity but is not the same as an encrypted token; if confidentiality of claims in transit is required beyond transport-layer protection, token encryption must be configured separately where supported.

How does the sign-out flow work in WS-Federation?

WS-Federation defines a sign-out mechanism intended to coordinate session termination across the identity provider and relying parties participating in a federation. In practice, the completeness and reliability of federated sign-out depends heavily on implementation, since each participating application must correctly honor the sign-out signal and clear its own session. Behavior varies by vendor and configuration, so single logout should be tested against each relying party rather than assumed to work uniformly across a federation.

When would you choose WS-Federation over a newer protocol like OpenID Connect?

The choice usually depends on existing infrastructure and application compatibility rather than one protocol being universally superior. WS-Federation is often retained in environments with established WS-* based integrations or legacy applications and identity products that support it natively. Newer greenfield deployments frequently favor OpenID Connect, which is built on OAuth 2.0 and uses JSON and JWTs rather than the heavier XML and WS-* stack. Migration considerations, application support, and the capabilities of your identity provider should drive the decision; evaluate what your specific relying parties and identity platform support before committing.

Common misconceptions

WS-Federation and SAML are the same thing.

They are distinct. SAML 2.0 is its own XML-based federation standard with its own web SSO profiles, while WS-Federation is a separate protocol within the WS-* family that builds on WS-Trust. WS-Federation can carry SAML assertions as tokens, but the two define different message flows and are not interchangeable.

WS-Federation is an authentication protocol that verifies user credentials.

WS-Federation defines how federation and token exchange occur between an identity provider and relying parties; the actual credential verification (authentication) is performed by the STS or an underlying mechanism it relies on. The protocol conveys the authenticated result as claims rather than specifying how the principal is authenticated.

A signed WS-Federation token is confidential.

Signing provides integrity and proof of issuer, not confidentiality. Unless the token or transport is also encrypted, claim values may be readable in transit. Whether encryption is applied depends on the deployment configuration.

Best practices

Verify token signatures against the trusted issuer's current signing certificate and validate token freshness, audience (wtrealm), and issuer before allowing the relying party to consume claims.

Apply transport-level protection (TLS) and, where sensitive claims are involved, consider token encryption in addition to signing, since a signed token is not confidential by itself.

Choose the appropriate profile for the client: use the web (passive) requestor profile for browser-based SSO and the active requestor profile for SOAP-capable clients, rather than forcing one flow across all consumers.

Keep federation metadata, endpoints, and certificates current, and establish a certificate rotation process to avoid trust failures when signing keys change.

Keep authentication concerns at the STS separate from authorization decisions made by the relying party, treating the claims in the token as inputs to the relying party's access control model rather than as authorization decisions themselves.

Where interoperability or newer deployments allow, evaluate whether SAML 2.0 or OpenID Connect better fits requirements, since WS-Federation behavior and support vary by vendor and profile.