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.

Installation

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

tomcat-idp

Start the Tomcat container:
tomcat-idp/bin/startup.sh (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:

• fedizidpsts
• fedizidp

tomcat-rp

start the Tomcat container:
tomcat-rp/bin/startup.sh (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:

• fedizhelloworld

Test

Enter the following URL in the browser:

https://localhost:8443/fedizhelloworld/secureservlet/fed

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

WS-Federation across several companies

I described a simple scenario about the WS-Federation Passive Requestor Profile in my previous blogs:

• Configure and deploy Identity Provider (IdP) - Part II
• Configure Tomcat for federation - Part III

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 (fabrikam.com and adatam.com).


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

• mycompany.com
  - 10000 users
  - five roles (user, manager, sales, accountmanager, admin)
  
• adatam.com
  - IDP supported
  - 2000 users
  - three roles (employee, manager, administrator)
  
• fabrikam.com
  - 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.
fabrikam.com supports an IDP but can't provide the role information. mycompany.com 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 fabrikam.com and the dedicated ID store of mycompany.com 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.


adatam.com 
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

fabrikam.com
How can the RP-IDP get the roles of the users?
The RP-IDP maps the userid of fabrikam.com to an internal userid in mycompany.com. The mapped userid is used to retrieve the role information. The roles/claims are not transformed.


mycompany.com
Nothing changes.


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


There are different kind of relationships between mycompany.com and the partner adatam.com and fabrikam.com. 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.

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 2.3.1.2 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?
Yes, 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?
Yes, 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:

• Using WS-Trust for token transformation
  

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.

SAML tokens and WS-Trust Security Token Service (STS)

I've been working actively in the Apache CXF community with respect to SAML tokens and the WS-Trust SecurityTokenService (STS) since Talend's donation of the STS to the community. I've noticed in various WS-Trust projects that there is a lack of documentation about the different use cases for SAML tokens and the WS-Trust STS.

I'll give a brief introduction into SAML and STS before bringing the two together.


SAML


SAML is an OASIS standard and consists of several specifications. A SAML token is issued by an identity provider. A service provider relies on the identity provider to authenticate a principal (a user). The SAML assertion is provided to the service provider allowing it to make an access control decision. The main problem SAML tries to solve is Web Single Sign On.

There is a clear layering between the SAML specifications thus they can be fairly easy reused in other contexts. Another context besides Web SSO is Web Services communication - which I'll be covering here. Therefore, we only need to look into the SAML Core specification as it describes the syntax and semantics of SAML assertions. The SAML protocols are covered by SAML core too but there are not relevant for Web Services communication. This is also the case for the SAML bindings (how SAML messages are transmitted from one system entity to another) as well as for SAML profile which describes use cases for Web application Single Sign On.

A SAML assertion (also known as SAML security token) contains different kinds of statements: authentication-, attribute- and authorization decision statements. The "authorization decision statement" became deprecated in SAML 2.0 specification as it is covered in XACML and in claims based authorization based on standard SAML attribute statements. The former is quite complex whereas the latter provides already good options for fine grained authorization at less complexity. You can find more information about the latter here.


A SAML assertion contains a subject which identifies the principal. The subject can also contain additional information like key material and the subject confirmation method. One of the main topics in this blog are the different kind of subject confirmation methods and how they correlate to an STS.


As a side note, the subject confirmation method is not defined in the SAML core. Instead, the SAML profile specification defines the following three subject confirmation methods:

• Holder of Key (HOK)
  The subject must contain key material so the service provider is able to validate that the requestor is in the possession of the key(s)
• Bearer
  The subject doesn't contain key material and it is up to the service provider to accept the assertion or not
• Sender vouches (SV)
  The subject doesn't contain key material and it is up to the service provider to accept the assertion or not. The requestor and the identity provider are usually the same.
  

For more information about SAML I recommend Wikipedia and the documentation at the OASIS committee.

Web Services and SAML

SAML in the context of Web Services is standardized in the SAML token profile here. It describes on the one hand how a SAML token is embedded in a SOAP message and on the other hand what kind of requirements must be met dependent on the SAML version and subject confirmation method.


I can highly recommend the following web services security usecases from OASIS as it describes very interesting use cases by combining transport level and message level security (ex. SAML HOK is very complex and has a performance impact as XML signature is required. This document describes how to use mutual SSL handshake for the proof-of-possession processing)

In 2011, many new security features have been added to CXF. Check the following blog for more information.



WS-Trust STS


The WS-Trust standard introduces a runtime component called Security Token Service (STS). A service consumer requests a security token from the STS which is sent to the service provider. Either the service provider can validate the security token on its own or sends a request to the STS for validation. This pattern is based on an indirect trust relationship between the service provider and the STS instead of between the service provider and service consumer. As long as the service consumer is in the possession of a security token issued by a trusted STS, the service provider accepts the token sent by the service consumer. This is the same pattern as for certificates and certificate authorities. This approach has significant advantages compared to a direct (brokered) trust established between a service provider and service consumer. The specification is an OASIS standard and can be downloaded here.

The STS can issue security tokens based on requirements provided by the service consumer and/or service provider. The requirements of the service provider are either expressed in a WS-Policy document according to WS-SecurityPolicy or out-of-band agreement.


A key benefit of the STS is the reduced complexity for web service consumer. A web service consumer doesn't have to know how to create the various types of security tokens its service providers require. Instead, it sends a request to the STS containing the requirements of the client and the service provider and attaches the returned security token to the outgoing SOAP message to the service provider. One service provider could require a SAML 1.1 token, another a SAML 2.0 token and another a custom binary security token. The service consumer doesn't have to understand SAML 1.1, SAML 2.0 or the custom binary security token. All he has to do is grab the returned token from the STS and attach it to the message. Thus, you can reduce the complexity in your application and move it to a centralized component.


How does a web service consumer know whether it has to go to an STS to request a token? The policy of the service provider contains an IssuedToken assertion with some additional information like the address of the STS, token type, claims, etc.


Now, it's time to explain a few parameters of the request (RST) to the STS.


TokenType
specifies the type of security token requested (ex. SAML 1.1, 2.0, X.509, ...). URIs are defined for all standard security tokens.

KeyType
specifies the type of key desired in the security token. There are three URIs defined:

• PublicKey
• SymmetricKey
• Bearer

Claims
specifies the required and optional claims in the security token. A claim can be the email address, role information, country, etc.


AppliesTo
specifies the scope for which the security token is required. This can be the URL of the service provider.


Lifetime
specifies the creation and expiration time of the security token. The STS is not obligated to honor this range.

These parameters can be retrieved from the WS-SecurityPolicy document also. In that case, they are added as child elements of the SecondaryParameters element in the RST.



SAML and STS 


How does a SAML token and the parameters sent to the STS match with each other. How does the STS know which subject confirmation method should be used? OK, let's start with the more obvious one.

1) TokenType
the token type is either SAML 1.1 or SAML 2.0. The STS creates the corresponding SAML assertion

2) AppliesTo
the AppliesTo element defines the scope and thus match to the SAML AudienceRestriction element in the SAML condition

3) Lifetime
the value of the lifetime or the lifetime choosen by the STS matchs to the SAML conditions NotBefore and NotAfter

4) Claims
the claim values maps to a SAML attribute statement. It's standardized here how claims are encoded as a SAML attribute statement. You can get more information about claims here.


How is the trust between the service provider and the STS established? This is fairly easy. The SAML assertion is signed by the STS. The signing certificate must be configured in the service provider to be trusted.


But how can the STS know whether the subject confirmation method should be HoK, SV or Bearer.
If the KeyType contains the value PublicKey or SymmetricKey, the subject confirmation method is Holder-Of-Key.
If the KeyType contains the value Bearer, the subject confirmation method is Bearer.

The benefit of HoK is that even if somebody gets into the possession of a SAML token he can't 
send requests masquerading as the subject in the SAML token as he doesn't know the key (symmetric or private key). However SAML tokens with Bearer subject confirmation method must be protected. In most cases, Bearer combined with HTTPS is sufficient to prevent that "a man in the middle" can get into the possession of the SAML token.

The subject confirmation methods Bearer and Holder-Of-Key are widely used for all STS use cases as well as for Web Single Sign On in WS-Federation Passive Requestor Profile and SAML Post Profile.


OK, what about sender-vouches? Even it is not clearly stated it makes no sense to request a SAML token from an STS with sender-vouches subject confirmation method.


You might know this paper from IBM which describes how to get a SAML token from the STS with sender-vouches. Even though it's from IBM, I won't change my opinion ;-)

Let's step back once and have a look what the differences are between a SAML token with subject confirmation method Bearer and Sender-Vouches. Utlimately, it is just a string in the ConfirmationMethod element. Of course, an STS can put the string for Sender-Vouches into the SAML token - not a big deal.

The WS-Security SAML token profile defines the processing rules for HoK and Sender Vouches. In the case of Sender-Vouches it says that the attesting entity, (presumed to be) different from the subject, vouches for the verification of the subject. The receiver MUST have an existing trust relationship with the attesting entity. The attesting entity MUST protect the assertion in combination with the message content against modification by another party. The trust is established based on certificates where the attesting entity (service consumer) creates a signature which protects the SAML token and the SOAP body. The service provider verifies the signature to have the confirmation that nobody made changes either to the token or the SOAP body. The receiver (service provider) must have imported the certificate of the service consumer.
A SV SAML token itself is not signed in contrast to Bearer and HoK because there is no third party like an STS. It wouldn't make sense for an STS to issue unsigned SAML tokens as there would be no way to protect against other entities adding additional statements.

Therefore, Sender-Vouches doesn't make sense in the context of STS.

Where is SAML Sender-Vouches used? I blogged about this topic here.

Configure Fediz IDP and ASP.NET using WIF

Fediz provides different components to support single sign on and claims based authorization for web applications based on WS-Federation. As described here, the IDP/STS is the central component which authenticates users and issues security tokens (ex. SAML) which includes information about the authenticated identity, their keys and claims. The other component is deployed within the relying party, the web application. How you can enable WS-Federation for Tomcat is described here.
What about other technologies like Microsoft. WS-Federation is supported by Microsoft out-of-the-box by the Windows Identity Foundation (WIF). ASP.NET supports similar extension points like Tomcat to intercept and customize request processing and authentication. The counterpart of a Tomcat Valve is a .NET HttpModule.

WIF is a .NET assembly (DLL) which provides http modules, new config section and other stuff. Thus, you can enable WS-Federation for your ASP.NET based web application by configuration. There is a very good post about WIF and ASP.NET here. There is also a Visual Studio extension to generate a mock IDP based on ASP.NET and WIF but it doesn't have the functionality supported by the mock IDP as part of Fediz. You can create test users and assign any kind of claims to each users thus you can easily test your claims based ASP.NET web application. IMHO, there is another reason, isn't it cool to show how interoperable .NET and Java is !?

You can re-use the updated IDP provided here.

The following steps are required to use this mock IDP in your ASP.NET web application.

1. Deploy Windows Identity Foundation

You can download WIF here and install it. Finally, you only have to deploy the Microsot.IdentityModel.dll‎ to your bin directory of the web application.

 
2. Import the IDP/STS certificate in the Microsoft certificate store
You can get more information about the Microsoft certificate store here.
The relying party must establish a trust with the IDP/STS. This is achieved by trusting the certificate which was used to sign the SAML token. Windows and .NET have their own certificate store and doesn't understand a Java keystore (JKS). Therefore, we have to export the certificate in the JKS in a platform neutral format like PEM. You have to run the following command:

keytool -exportcert -alias mystskey -keystore stsstore.jks
-storepass stsspass -rfc -file sts.pem
Import the certificate file sts.pem into the store as described here.
Ensure that you import the certificate into the "Trusted People" store.


You are able to click on the certificate you imported before. The value of the field "Thumbprint" is required to establish the trust to the IDP within the relying party.

3. Configure WIF in web.config


Different sections of the web.config must be updated. First, you must configure the new config section for WIF:


   <configSections>
      <section name="microsoft.identityModel"
         type="Microsoft.IdentityModel.Configuration.MicrosoftIdentityModelSection, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
   </configSections>

Second, configure the http modules:

   <system.web>
      <httpModules>
         <add name="SessionAuthenticationModule"
            type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
         <add name="WSFederationAuthenticationModule"
            type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
      </httpModules>

Disable default authentication/authorization. Instead, the above http modules will handle authentication and authorization:

      <authentication mode="None" />
      <authorization>
         <deny users="?" />
      </authorization>

Configure WIF:


   <microsoft.identityModel>
      <service saveBootstrapTokens="true">
         <issuerNameRegistry      type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
            <trustedIssuers>
               <add thumbprint="977f0c1c0a2e9534d310a8e05380f5653524ca3f"
                  name="https://b0d0ma02.ch.zurich.com:16050/fedizidp/" />
            </trustedIssuers>
         </issuerNameRegistry>
         <certificateValidation
            certificateValidationMode="PeerTrust" revocationMode="Online"
            trustedStoreLocation="LocalMachine" />
         <audienceUris>
            <add value="https://teinf0095.emea.zurich.test/helloworld/" />
         </audienceUris>
         <federatedAuthentication>
            <wsFederation passiveRedirectEnabled="true"
               issuer="https://b0d0ma02.ch.zurich.com:16050/fedizidp/"
               realm="https://teinf0095.emea.zurich.test/helloworld/"
               requireHttps="true" />
            <cookieHandler requireSsl="false" name="FedAuth"
               hideFromScript="true" path="/helloworld" />
         </federatedAuthentication>
      </service>
   </microsoft.identityModel>


I'd like to highlight the following pieces in the section "microsoft.identityModel".

1) issuerNameRegistry
add the thumbprint to the issuerNameRegistry


2) audienceUris
add the valid uri's which must match with the audience restriction in the SAML token


3) federatedAuthentication
configure the URL of the IDP in the attribute "issuer" and the realm for the application. The realm matches with the audience restriction finally.




More information about WIF configuration can be found here.
That's it. You are ready for testing...


4. If it doesn't work...

1) A generic exception is returned by the .NET application without indicating the root cause.


There should be an error logged in the Microsoft Event Viewer (Administrative Tools) for the log type "Application".


2) SecurityTokenValidationException is returned by the application


exception details:
[SecurityTokenValidationException: The X.509 certificate E=sts@sts.com, CN=www.sts.com, OU=IT Department, O=Sample STS -- NOT FOR PRODUCTION, L=Baltimore, S=Maryland, C=US is not in the trusted people store.]


Certificate not imported into the Microsoft Certificate store (Trusted People store. See section 2.


3) SecurityTokenException


exception details:
[SecurityTokenException: ID4175: The issuer of the security token was not recognized by the IssuerNameRegistry. To accept security tokens from this issuer, configure the IssuerNameRegistry to return a valid name for this issuer.]


Certificate not trusted. Ensure that the correct thumbprint is configured in web.config.

Updates on federation sources

In the last weeks I was working in enabling IBM Websphere with WS-Federation and setting up a testcase where a federation enabled web application consumes web services where the security context must be propagated. I need some more time to prepare an example and post a blog. Stay tuned.

There are some updates with respect to the federation examples I posted in the last weeks.

• Sources have been moved from Google docs to the Apache CXF project
• The SAML security token had a lifetime of 5 minutes which has been increased to 20 minutes
• The Tomcat authenticator doesn't redirect if the security token is expired instead it blocks the incoming request

Sources have been moved from Google docs to the Apache CXF project

You can find the sources here. Right now, you have to check out the sources and build them on your own. This is fairly simple with Maven (mvn clean install).

The package names have changed. Please ensure to configure the new package name org.apache.cxf.fediz. ...

The STS of the CXF release 2.5.1 is used

If you have any questions please raise them at the Apache CXF mailing list.


The SAML security token had a lifetime of 5 minutes which has been increased to 20 minutes

If you deploy the previous Tomcat example you could test the application for 5 minutes. Further requests have been rejected because the security token  lifetime is expired (Condition in SAML 2.0).

I made the following changes to the STS configuration to change the default lifetime which is fairly simple to do due to the usage of Spring.


    <bean id="transportSamlTokenProvider" class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
        <property name="attributeStatementProviders" ref="attributeStatementProvidersList" />
        <property name="conditionsProvider" ref="conditionsProvider" />
    </bean>

    <bean id="conditionsProvider"
        class="org.apache.cxf.sts.token.provider.DefaultConditionsProvider">
        <property name="lifetime" value="1200" />
    </bean>

If you don't configure the DefaultConditionsProvider the default lifetime is 5 minutes. You configure a different lifetime by setting a value in seconds for the property lifetime.

The Tomcat authenticator doesn't redirect if the security token is expired instead it blocked the incoming request

As mentioned in the previous section, the issued SAML token expires after 5 minutes and blocks any incoming request of this user. The lifetime of the HTTP session and the security token can be different in deployments due to different non functional requirements for the application and the security infrastructure. Thus, the application server (Relying Party) should transparently redirect the user to the IDP. Usually, the user still has got a session with the IDP and is not challenged to enter username and password. A new SAML token is issued and sent back to the application server which validates the token and updates the session.

This fix has been applied in revision r1222148 here.

Configure Tomcat for federation - Part III

I described in the previous blogs how to set up the IDP which plays a key role in Web SSO based on the Passive requestor profile of WS-Federation and the CXF STS to issue security tokens. The IDP delegates authentication requests to the STS.

In WS-Federation, the authentication process is externalized to the IDP/STS. It provides you a SAML token (or another security token, WS-Federation is not tight to SAML) which contains all information of the authenticated user you need to implement finer grained authorization requirements without being tight to the user name.

The information in the SAML token must be integrated in Tomcat in such a way that application developers can use J2EE security as they are used to.
Example:

• HttpServletRequest.getUserPrincipal()
• HttpServletRequest.isUserInRole()
• security constraints in web.xml

There is no need to configure any security related servlets/filters in the web.xml. This is managed on the Tomcat container level to benefit of container managed security.

It's standardized here how claim information (firstname, lastname, email, etc) must be represented in an AttributeStatement of a SAML token (assertion) but there is no Java API standard how this information could be accessed by programming. The federation plugin provides an extension of the Tomcat principal class which provides all these information.


This blog addresses two topics:

• how to build and deploy the federation plugin into Tomcat
• how to build and deploy a federation enabled web application into Tomcat

The plugin has been tested with JDK 1.6 and Tomcat 7.0.



Build and deploy the federation plugin into Tomcat
The source code is bundled as maven plugins which can be downloaded here and contains the following maven modules:

• plugins/core
  This module contains the core ws-federation functionality which is container agnostic. The core functionality includes SAML 1.1/2.0 token validation (signature verification), lifetime and audience restriction validation. The FederationProcessor returns all information like roles, claims and authenticated user.
• plugins/tomcat
  This module contains the tomcat authenticator which integrates the ws-federation functionality into Tomcat. It hydrates the tomcat security context
• examples/simpleWebapp/
  This is a sample web application where the federation plugin is configured and makes use of security constraints and the Servlet Security API.
  This module is described in section "Build and deploy the federation sample application".

Run mvn clean install in each module to build the jar file.
After the build, please follow these steps to deploy and configure the federation plugin.

1) Create sub-directory fediz in ${catalina.home}/lib

2) Update calatina.properties in ${catalina.home}/conf
add the previously created directory to the common loader:
common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,${catalina.home}/lib/fediz/*.jar

3) Deploy the built libraries and dependencies to the directory created in (1)
The built libraries and their dependencies can be found in the zip file located in fediz-tomcat/target/...zip-with-dependencies.zip

4) Configure Federation plugin
The current release of the federation plugin requires to configure the FederationAuthenticator which is configured like any other Valve as described here.

You can either configure the context in the server.xml or in META-INF/context.xml as part of your WAR file.

server.xml
  <Context path="/fedizhelloworld" docBase="fedizhelloworld">
    <Valve className="org.apache.cxf.fediz.tomcat.FederationAuthenticator"
      issuerURL="https://localhost:9443/fedizidp/"
      truststoreFile="conf/stsstore.jks"
      truststorePassword="stsspass"
      trustedIssuer=".*CN=www.sts.com.*" />
  </Context>
       
META-INF/context.xml

  <Context> 
    <Valve className="org.apache.cxf.fediz.tomcat.FederationAuthenticator"
      issuerURL="https://localhost:9443/fedizidp/"
      truststoreFile="conf/stsstore.jks"
      truststorePassword="stsspass"
      trustedIssuer=".*CN=www.sts.com.*" />
  </Context>


The attribute issuerURL tells the plugin where to redirect unauthenticated requests which access a protected resource (security constraint matches URI pattern).
The current release of the federation plugin supports SAML 1.1/2.0 tokens. The SAML token is signed to provide a way to establish a trust. The federation plugin must validated the SAML token. The validation process includes verifying whether the certificate has been issued by a trusted CA and whether the certificate subject is trusted. The certificate subject identifies the IDP/STS.
You can have more than one IDP/STS in your company. As soon as you grant B2B partners access (internet) to your web application you have at least 2 IDP/STS instances. Usually, you create a chain of IDP instances where the RP trusts only the internal IDP/STS instance and the internal IDP (so called Relying Party IDP) trusts the external IDP. This scenario is addressed in one of the next blogs.
The attribute truststoreFile tells the plugin where the truststore is located (Java Keystore format) and the password is configured in the attribute truststorePassword. The trusted IDP/STS is configured as a regular expression in the attribute trustedIssuer.

It's not yet possible to configure a custom security token validator.


5) Configure the CA certificates

If you use the STS as described here you can copy the keystore from fediz-idp-sts/src/test/resources/stsstore.jks to the configured location in the attribute truststoreFile.

(you can ignore the fact in this demo that the private key is contained in this keystore also which must not be the case for production. The certificate is sufficient for signature validation)


Build and deploy the federation sample application
I've chosen the META-INF/context.xml approach to configure the federation plugin for ease of use.

This web application provides three accessible resources:

• index.html
  This static page is not secured by a security constraint
• secure/test.html
  This static page is secured by a security constraint in the web.xml
• /secureservlet/fed
  This servlet provides information about the authenticated user like username, roles and claims as illustrated in the following picture:

    
The user and role information can be retrieved using standard J2EE security API. Unfortunately, there is no standard API to retrieve claims information thus the federation plugin provides an extension of the principal which can be accessed as illustrated here:

  Principal p = request.getUserPrincipal();

  if (p instanceof FederationPrincipal) {
     FederationPrincipal fp = (FederationPrincipal)p;

     ClaimCollection claims = fp.getClaims();

     ...

  }

Every security constraint must define at least one role in auth-constraint as defined in the Servlet specification. There are use cases where you might want to give access to resources to everybody who is authenticated. Therefore, the plugin can add a default role if no roles are provided as part of the SAML token. If not explicitly configured, the default role name is Authenticated.

Encoding of roles in SAML token

The federation authenticator provides the following attributes to customize where and how the role information is encoded in the SAML token. The role is like any other claim represented within the attribute statement.

The IDP/STS in this example uses the following URI for the role claim:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role

If your IDP/STS stores the role information in another claim, configure the attribute roleClaimURI in the FederationAuthenticator. The value of the attribute is a string where the list of roles are delimited by a character. The IDP/STS in this example use "," as the default delimiter. If you want to use another delimiter configure the attribute roleDelimiter in the FederationAuthenticator.