Lessons Learned: Understanding WS-Federation

WS-Federation is an identity federation specification which makes it possible to setup a SSO federation including multiple security realms. A realm (sometimes also called domain) represents a single unit under security administration or a part in a trust relationship.

Entities

Within the WS-Federation standard the following entities are defined:

Relying Party (RP)
The relying party is a resource (web application or service) which consumes security tokens issued by the Security Token Service.
Requestor
A requestor is a user who wants to access a resource (relying party).
Identity Provider (IDP)
An Identity Provider can act as an authentication service to a requestor (in this case it is also called “Requestor IDP” or “Home-Realm IDP”) as well as an authentication service to a service provider (also called “Relying Party IDP”). If a user tries to access a relying party within his own security domain, the “Requestor IDP” and the “RP-IDP” can be the same IDP instance. An IDP can also be seen as an Web-Frontend (Extension) of an STS.
Security Token Service (STS)
A Security Token Service is a web service that validates user credentials and issues security tokens which can include user attributes (also called claims). The security token can be used at the Relying Party to authenticate the requestor’s identity.

Passive Requestor Profile

The “Passive Requestor Protocol” of the WS-Federation standard deals with web-browser based access of a resource like a web portal or a web application.

The following figure shows a standard scenario of a web application (Relying Party) which delegates the user authentication to an Identity Provider (IDP) according to the WS Federation standard. This way the web application does not need to implement multiple authentication styles for a user, as well as it allows interacting with users not known within the local security domain. Another benefit of delegating the authentication process is that the IDP can retain a session with the user, so that when a user accesses another web application and is redirected to the IDP again, the IDP does not need to request user credentials again und thus providing a SSO experience for the user.

The above figure shows a sequence diagram of a user (requestor) accessing a web application with his browser. Since the user was not authentication due to a recent session, the application redirects the user to the IDP for a user login (1). The IDP collects the credentials from the user and uses a Security Token Service (STS) to validate the credentials and also to get a SAML token from the STS (2). The STS itself is connected to a LDAP data store to validate the user credentials and also to retrieve additional information (claims) about the user, e.g. roles. On successful authentication (3) the IDP returns the SAML token issued by the STS (4) to the user and advices (auto-submitting form) the user to send this SAML token to the originally requested web application (5). The IDP takes care of providing a web user interface and handling URL redirects, whereas the STS is responsible for generating SAML Token and validating of user credentials. The web application validates the SAML token (6) and on success returns the desired web page (7).

The above sample was designed to show a simple use case scenario where the Requestor IDP is equal to the Relying Part IDP. In a more sophisticated scenario the Requestor IDP will not be equal to the Relying Party IDP. In addition to that there is also a Reverse Proxy added to the web application ensuring that the home realm discovery (also see section 2.3.3) is going to work correctly. The resulting access sequence can be seen in the following figure.

The user enters the public WebApp URL in his browser which leads him to the Reverse Proxy (0). The WebApp has no recent session with the user and therefore does not know the identity of the user. Thus the WebApp redirects the user to its Relying Party IDP (1). The Reverse Proxy detects the redirect to the RP-IDP and adds a home realm parameter for the user (1). This IDP uses this home realm parameter to perform the home realm discovery (3) and thus knowing at which IDP can be redirected to for being authenticated (4). The WS-Federation standard does not define how the home realm discovery should be performed. Multiple options are usually available:

User Selection
A list of known and trusted IDPs is shown to the user. The user selects the IDP at which he wants to be authenticated and is then redirected to that IDP.
IP Discovery
The user will be redirected automatically to another IDP based on his IP address.
whr Parameter
The URL to invoke the RP-IDP contains an additional ‘whr’ parameter to define the IDP name on which the user wants to be redirected to for authentication. The ‘whr’ parameter must be known at the RP-IDP and must either be mapped to an URL or can also already be the URL of another IDP). The ‘whr’ parameter is usually set by a Reverse Proxy or was added (by the user or a provided link) in the URL when initially calling the web application.
Custom Discovery
Any custom logic can be added to the IDP to perform the home realm discovery. The standard is not limited to any predefined behaviour.

After being redirected to the users home IDP (5) the IDP also has no recent session with the user and thus shows a login form to the user to enter his credentials (6). The user sends his username/password to the IDP, which itself creates an issue request to the STS with the received unsername/password embedded (7). The STS validates the user credentials by using the LDAP. Upon successful authentication the STS retrieves the requested user claims (e.g. roles) from the LDAP (8) and creates a SAML token (9) targeted for the RP-IDP. The Requestor IDP embeds this SAML token inside an auto-submitting (Java Script) web form (10) which is then posted to the RP-IDP (11a). The RP-IDP is now able to use this SAML token to authenticate on behalf of the user against the RP STS (11b) to request a SAML token for the previously requested web application. The RP-STS needs to perform an identity or claim mapping (12) to issue a second SAML token this time applicable for the requested web application (13). The RP-IDP puts this application specific SAML token again in a self-executing HTTP form (14) which is then automatically submitted to the web application via the reverse proxy (15). The Relying Party (the web application) validates the received SAML token by verifying that the issuer certificate of the SAML token is trusted. This should be the case, since the SAML token was issued by its own Relying Party IDP. Additional claims like the user roles can be added to the security context of the web application and thus allowing authorization above authentication.