A Glimpse of the new WS-Federation implementation in WSO2 Identity Server

5 min readJun 27, 2020

Reason for the implementation change

As the OpenSAML version of the WSO2 Identity Server was upgraded from OpenSAML2 to OpenSAML3[1], the STS implementation had to be updated to OpenSAML3 but there were a lot of complexities that we faced in doing so[2]. Below are some of the methods which we tried out and the complexities faced during those:

Wss4j was updated to the latest Apache version[3] and used with wso2-rampart[4]. Because of the major restructuring done in wss4j, we could not use the latest wss4j version with wso2-rampart.
The last release of wss4j 1.6.x[5] was used which did not contain major package changes, converted it to OpenSAML3, and used it in wso2-rampart. The OpenSAML conversion was not possible in wso2-rampart due to the usage of OpenSAML1.1 implementation.
The latest rampart version[6] was used where OpenSAML1.1 implementation was re-implemented using OpenSAML2. Converted it to OpenSAML3 and then tried to use it in our code base, but again since rampart had newer versions of axis2 and axiom than the current wso2 components available if we were to proceed then it would take a lot of time and there can be high complexities added.
Finally, since there was an alternative implementation for WS-Trust implemented for GSoC 2017[7][8][9][10] using msf4j and Apache CXF. I tried to test this out with the product. But since this implementation was based on C5, without major changes, we could not add it to the product.

Since none of the options mentioned above worked out, a meeting was held to discuss the progress of the conversion. The meeting notes for the discussion were as follows:

As the initial step, remove STS components from the product and bundle it as a connector which will give us more time for a new implementation or a conversion.
Look into the WS-Federation(Passive STS) implementation using Apache CXF.
Try and get the implementation of WS-Trust using mss4j and Apache CXF to work by making certain tweaks needed. Use this as a replacement for the current implementation.

After providing both Active STS(WS-Trust) and Passive STS(WS-Federation) as a connector there was a small concern on the WS-Federation perspective since it was used by some of our customers, providing it as a connector was not a feasible idea. Due to the aforementioned, we had to re-implement WS-Federation using Apache CXF which eliminates the possibility of maintaining wso2-wss4j[11] and wso2-rampart[4] and also the conversion of OpenSAML in WS-Federation.

Sample request flow overview

Basic flow of a request sent by the client

The above diagram represents a flow of a request which occurs inside the component org.wso2.carbon.identity.sts.passive[12] when a client’s request is received. Both the current and previous implementation follows the same flow as above.

The client sends a request to obtain a security token — The request will contain a set of parameters like realm, username, token type, required claims, etc…
With the help of the request parameters, an issue request(RST) will be built and the configurations required to generate the issue token response(RSTR) will be set accordingly.
A request will be made to obtain a security token response(RSTR) for an issue request(RST).
The generated token will be set on to the Response object’s results property.
The response will be sent back to the client with the requested security token.

Previous Implementation

Basic concept of the flow

Sets up the message context with the request parameters

Sets the username token principal and includes the created issue token request(RST) generated with the help of the request parameters. e.x.

Generates a request of type issue with the provided token type.
Creates the requested dialect and the claims.
Invokes the STSClient to create an issue token request(RST).

2. Creates a SAML token issuer config

Specifies all the configurations required to handle the issue RST. The configurations include:

Issuer name
Crypto provider
Rampart properties
Issuer key alias
Issuer key password
Requested attached reference(boolean value)
Requested unattached reference(boolean value)
Key computation
Proof key type
Callback handler name: Handles the claims.
Time to live: The lifetime of the SAML token.
Trusted service endpoint address: Where does the security token applies to.
Signature algorithm
Digest algorithm

3. Instantiates RahasData with the given context

4. Sets the SAML token issuer config and the audience restriction to the passive token issuer

5. Invokes the issuePassiveRSTR() method with the RahasData on the passive token issuer

6. Sets the result into the Response object and sends it back to the client

Sample Request Security Token Responses(RSTRs)

SAML1.1:

SAML1.1 RSTR generated using Apache Rampart.

SAML2.0:

SAML2.0 RSTR generated using Apache Rampart.

Current Implementation

Basic concept of the flow

1.Sets up the token issue operation

Responsible for making the token issue request and obtaining the processed security token(RSTR). This is where most of the configurations should be set to handle the RST. The configurations include:

A token provider — A SAML token provider based on our requirement. Every element and attributes of the assertion is under the control of the token provider e.x. claims, lifetime, subject name identifier, etc…
A service — The service which the security token applies to. e.x. realm.
STS properties — Properties which are required to be set in the RequestSecurityTokenResponse. e.x. issuer name, signature algorithm, digest algorithm, encryption properties.
Custom claims handler — Handles all the claim related logic. Ideally should first load the claim for the that tenant, do all the validations required and finally set the claims for the security token.

2. Creates an issue token request(RST)

Creates a default RST with the help of the obtained request parameters. The process is as follows:

Create a default issue token request with the given token type.
Create the secondary parameters. e.x. claims.
Create the apply to element which represents where the token is consumed. e.x. realm.

3. Sets up the message context

Message context is set for the username token.

4. Invokes token issue operation’s issue() method to obtain the RSTR

5. Converts the RSTR to a string and sends it inside the Response object

Sample Request Security Token Responses(RSTRs)

SAML1.1:

SAML1.1 RSTR generated using Apache CXF.

SAML2.0:

SAML2.0 RSTR generated using Apache CXF.

Improvements to be made

The claim handling logic should be improved and should have the capability to handle both mandatory and optional claims.
Embedded dependencies in the component should be removed.