March 8, 2012

Packaged Tomcat Instances for Federation/SSO

I've created a ZIP archive which contains two tomcat setups for the replying party (secured web application) and the identity provider (IDP). It's much easier to start with this approach and make the experience how easily a web application can be SSO enabled using SAML tokens according to the Passive Requestor Profile of WS-Federation specification.

You can download the package here.


Unzip the downloaded archive which contains in each sub-directory a dedicated tomcat instance. The two tomcat instances are described below.


Start the Tomcat container:
tomcat-idp/bin/ (or startup.bat for windows)

Mar 8, 2012 8:59:13 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-9080"]
Mar 8, 2012 8:59:13 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-9443"]
Mar 8, 2012 8:59:13 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 4245 ms

The Tomcat IDP instance creates an HTTPS listener (9443) and HTTP listener (9080). The insecure port is used for remote deployment during the maven build.

This tomcat instance has got two WAR files deployed: fedizidp and fedizidpsts.
You can find more information how to build and deploy the corresponding package here:


start the Tomcat container:
tomcat-rp/bin/ (or startup.bat for windows)

Mar 8, 2012 9:00:05 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Mar 8, 2012 9:00:05 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8443"]
Mar 8, 2012 9:00:05 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 2840 ms

The Tomcat RP instance creates an HTTPS listener (8443) and HTTP listener (8080). The insecure port is used for remote deployment during the maven build.

This tomcat instance has got one WAR file deployed: fedizhelloworld
You can find more information how to build and deploy the package here:


Enter the following URL in the browser:


to access the web application which redirects to the IDP component. The IDP challenges the browser to enter username/password. Next, the IDP/STS issues the SAML token which contains all requested claims information and "redirects" the browser back to the application.

This post describes how to test the fedizhelloworld application. The configured users and their claims are described here.

Secure your own web application

Follow these steps to secure your own web application:

  • If it is another Tomcat instance than tomcat-rp ensure to deploy the federation plugin into this tomcat instance as described here
  • Configure the Tomcat Valve FederationAuthenticator in your META-INF/context.xml or Tomcat server.xml as described here
  • Configure the URL of your web application (including the servlet context name) in the RPClaims.xml (bean realm2ClaimsMap) in <tomcat-idp>/webapps/fedizidp/WEB-INF/RPClaims.xml and update the claims if required
  • You can manage the claims of the users in <tomcat-idp>/webapps/fedizidpsts/WEB-INF/userClaims.xml

March 7, 2012

WS-Federation across several companies

I described a simple scenario about the WS-Federation Passive Requestor Profile in my previous blogs:
Before I describe a more complex scenario, I'd like to summerize the benefits of the simple scenario:
  • Authentication is externalized to IdP/STS
  • New IdP authentication mechanism can be used by all applications
  • Role Based Access control (RBAC) supported in applications
  • Claims/Attrribute based acess control (ABAC) supported in applications
  • IDP and applications deployable in different networks (ex. on-premise and cloud)
  • Easy testing with Mock IdP

Federation with B2B partners in the internet

In most cases, a web application is built for a single user group like internal users with some basic authentication mechanism like username/password against an LDAP system. Over time, the business see some potential to grow in providing this solution to partners. The application is enhanced to support a new kind of authentication mechanism for the users of the partner. The next partner has again a different kind of approach for authentication which must be extended in your application. Very often, the userids of the partner's employees have to be managed within your ID system also. What happens of an employee of the partner leaves the company? Usually, a manual process must be triggered to deprovision the user in your ID system.

How can federation and claims based authorization help here. The simple scenario doesn't support different kind of "user groups". But it's very important to highlight that the authentication mechanism is not tight into the application but instead into the IDP component. The benefit of federation is that you can integrate new partners without having an impact on your application. Just imagine how agile your application is to generate new business with new B2B partners without building a new authentication mechanism within all your applications.

How does this work? Let's look at a concrete example.

Our federation enabled web application should be provided to two new partners ( and

The users of and are managed within their own identity store. The following list provides more context information of the companies:
    - 10000 users

    - five roles (user, manager, sales, accountmanager, admin)

    - IDP supported

    - 2000 users

    - three roles (employee, manager, administrator)

    - IDP supported
    with restrictions (SAML token contains user only)
    - 50 users

    - two roles (user, accountmanager)
The three companies have their own kind of naming for roles but the application must not differentiate between the different kind of role semantic. supports an IDP but can't provide the role information. decides to manage the 50 users and its roles within a dedicated ID store within their network (another option would have been to choose a more advanced IDM solution in the cloud). The usernames are different within the ID store at and the dedicated ID store of due to different naming conventions in place.

The following deployment diagram illustrates the solution:

I haven't drawn any lines between the browser and the relying party which is the first component the browser accesses. The relying party redirects the browser to the RP-IDP (resource IDP) where the home realm discovery mechanism redirects the browser to its (requestor) IDP. The requestor IDP authenticates the browser and issues a SAML token with claims information. The browser sends the SAML token to the RP-IDP which transforms the SAML token into a format which can be validated and processed by the application (RP). This SAML token has the exact same structure independent who the requestor IDP was. 
What happens with the different kind of syntax of the roles?
The RP-IDP transforms the roles from the requestor IDP to the internal set of roles.
  • employee -> user
  • manager -> manager
  • administrator -> admin
How can the RP-IDP get the roles of the users?
The RP-IDP maps the userid of to an internal userid in The mapped userid is used to retrieve the role information. The roles/claims are not transformed.
Nothing changes.

Finally, the issued tokens by the RP-IDP have the same syntax and semantic independent whether a user from, or an internal user accesses the application.

There are different kind of relationships between and the partner and The former relies on federating the claims information whereas the latter federates/maps the userid/identity.

Support for identity mapping and claims transformation in STS

The STS is the key component in the WS-Federation based solution who issues the security tokens. The CXF STS supports identity mapping in the release 2.5.x.

I've finished my work to add support for claims transformation in the CXF STS.

Soon, I'll provide more details how to configure an STS with several realms (security domains) and different federation relationships among them.

March 6, 2012

SAML sender-vouches use case

In my previous blog here I described the different SAML subject confirmation methods (SCM) and how they integrate with an STS. This blog describes the use case for the Sender-Vouches (SV) SCM. As this use case can be solved with an STS also, I compare the two approaches finally.

Use case for SAML Sender-Vouches

The SAML token profile states that the attesting entity is different from the subject. You have such kind of a scenario where a web service proxy/gateway (intermediary) is deployed between your service consumer and service provider. The proxy is the attesting entity and vouches for verification (or authentication) of the subject (service consumer). The proxy signs the SAML token and the soap body to protect against modification by another party.

The following picture illustrate the deployment diagram of this intermediary pattern:

(This kind of intermediary pattern is often referred to as an ESB)

The characteristic of the intermediary is that TCP connections (HTTP) are terminated and new connections are established between the intermediary and the service providers (the term proxy is widely used for settings in your OS or browser which support HTTP tunneling).

The service provider must not accept a SAML SV token unless the token and the SOAP message content being vouched for are protected by the intermediary (attesting entity) who is trusted by the service provider. The protection can be achieved by using XML signature in the WS-Security header by signing the SAML token and the SOAP body. A direct trust is established between service provider and intermediary (service consumer).

The usage of XML Signature has a significant performance impact as most XML security libraries are DOM dependent which means you need an full in-memory representation of the SOAP message. This breaks streaming (StAX parser) and increases memory usage by factors of the original message size. Another issue to consider is the potential lack of support for the STR Dereference transform algorithm  to build the signature (this was not supported two years ago in .NET). This algorithm is described in section 3.4.3 in the SAML Token Profile specification.
(Apache CXF/WSS4J 2.0 is going to support streaming based XML signature and encryption in the near future)

The OASIS WS-SecurityPolicy Examples document describes in a more performant approach. Instead of signing the SOAP message on the XML level it uses a mutual SSL handshake where the service provider requires that the intermediary has configured a client certificate for the HTTPS communication he trusts. The side effect is that this won't be supported by all web service stacks and so you can run into interoperability issues.

SAML SV works fine if the service provider, the intermediary and service consumer are in the same security domain which means that the principal name "jdoe" is processable in all of them. 
  • If the service providers are in different security domains how shall the intermediary map/federate the identity? 
  • If the service provider should support more than one security domain how should the intermediary encode the security domain information into the SAML token? 
  • Do the different web service stacks of your service providers support the same kind of mechanism to decode security domain information or do you have to write code for all your stacks to support that? 
  • If the service provider requires role information in the SAML token how should the intermediary retrieve that and encode it within the SAML token?
  • Do the web service stacks of your service providers support the same kind of mechanism to decode role information thus you can use container managed role based access control?
  • Are the issued security tokens/retrieved authorization information cached?
  • If the service provider requires specific claims information in the SAML token ...
As you can see, you have to consider a few things before deciding to go with the SAML Sender-Vouches subject confirmation method.

If your enviroment can fulfill the following requirements you can consider using SAML Sender-Vouches:
  • there is only one security domain
  • you don't have to authorize your web services and thus don't need additional claims in the token
  • you're using only one Java or .NET web service stack
  • soap message size is small
  • performance is not critical or business logic related processing time is  comparatively higher
By now it should be apparent that  SAML Sender-Vouches is not my favourite subject confirmation method. The main reasons are the underlying pattern of a direct trust (resulting in more administration effort, comparable to the usage of self-signed certificates without a certificate authority) and lots of functionality that should instead be handled by an IDM solution which can be integrated into different kind of contexts (Web Services, Web SSO, B2B gateway, ...).
Is there another solution to address the intermediary case?

Use case "Intermediary" for WS-Trust Security Token Service

The answer to the question in my last paragraph is yes.

The WS-Trust specification defines two ways to address it:
  • OnBehalfOf
  • ActAs
The following blog post provides more information about the differences of OnBehalfOf and ActAs. In both cases, the security token received by the intermediary is sent within one of these elements in the request (RST) to the STS. The STS validates the security token and issues a new one with the information of the original principal.

Is there a standard mechanism to tell the intermediary that the service provider requires a token issued by an STS?
Yes, the service provider's WS-SecurityPolicy defines an IssuedToken assertion.

Is there a standard mechanism to tell the intermediary what kind of security token (saml1, saml2, other) the service provider requires?
the service provider's WS-SecurityPolicy defines the TokenType in the RequestSecurityTokenTemplate of the IssuedToken assertion.

Is there a standard mechanism to tell the intermediary from which security domain the service provider requires a token issued?
Yes, the service provider's WS-SecurityPolicy defines the Issuer element in the IssuedToken assertion.

Is there a standard mechanism to tell the intermediary which claims information the service provider requires in the issued token?
the service provider's WS-SecurityPolicy defines the Claims element in the IssuedToken assertion.

This logic doesn't have to be coded and managed statically within the intermediary in a non-standard compliant way. It's very flexible by just changing the policy information of the service provider.

In both intermediary solutions (with and without STS), if the intermediary has to communicate with a remote component (ID system or STS) it's recommended to cache issued security tokens for the duration of their lifetimes. This avoids needing to obain a new security token for each web service request issued by the intermediary on behalf of a particular subject.

How does the intermediary know how long should a token be cached?
How should the intermediary know if a security token has been issued for a specific service only?
This is fairly easy, the response of an STS usually returns a Lifetime and AppliesTo element. The cache can be built around the incoming security token id, the subject the token is for, the lifetime and AppliesTo information to build a flexible and token agnostic cache.

Last but not least, is there a web services stack which supports this functionality without having to write a single line of code?
Yes, it's Apache CXF. The intermediary use case is described in the above mentioned blog post. A system test and its configuration for the CXF STS is available too.

CXF is not the only web services stack supporting the intermediary case with an STS as the following article shows:

One question remains: How can the service provider process claims information like roles, etc. which are encoded as an AttributeStatement in the SAML token? Do I have to implement and maintain this for Websphere, Weblogic, Tomcat, JBoss, etc.

This answer is no.
In one of my next posts I will explain how to reduce the complexity and increase interoperability of your web services deployment even you've got different application server stacks in house.