WS-Federation support in Apache CXF

Apache CXF is a leading web services stack with excellent support for a long list of security protocols such as WS-Security, OAuth, etc. A recent addition to this list is support for WS-Federation via the Apache CXF Fediz subproject. In this post, we will introduce Fediz and illustrate how to secure a web application with Fediz via an example.

1) Introducing Apache CXF Fediz

The Apache CXF Fediz subproject provides an easy way to secure your web applications via the WS-Federation Passive Requestor Profile. A good place to start in understanding this profile is to look at the Fediz architecture page. A typical scenario is that a client browser will attempt to access a web application secured with a Fediz plugin. Fediz will redirect the brower to an Identity Provider (IdP) for authentication, if no token/cookie is present in the request. In this way, authentication is externalized from the web application to a third party IdP.

Fediz ships with an IdP component, but naturally the Fediz container plugin is also tested with other implementations. The IdP prompts the user for her credentials, and authenticates them via a Security Token Service (STS). The IdP requests that the STS issues a signed SAML Token on successful authentication. The IdP is configured to request that the STS inserts certain "Claim" attributes in the SAML Token, where the specific "Claim" types are configured per-realm. The client brower is then redirected back to the application server with the inclusion of the SAML Token.

The Fediz plugin parses the received SAML Token. Authentication is established via the trust verification of the signature on the token. Role-based Access Control (RBAC) is supported by configuring the plugin with a "roleURI" attribute (which should correspond to the standard Claims URI for a role). The corresponding attribute values are extracted from the SAML Token and stored as the role(s) of the user. The actual security enforcement is delegated to the underlying container / application server. The containers that are (planned to be) supported are:

• Apache Tomcat - See here.
• Jetty - See here, available in the forthcoming 1.1 release.
• Spring - See here, available in the forthcoming 1.1 release.
• JBoss - Planned for the forthcoming 1.1 release. 

An important point to note is that the Fediz container plugin is actually protocol-agnostic. WS-Federation is the only protocol supported to date, but support for the SAML Web SSO Profile may be added at a later date. For more detailed information on Fediz you should refer to the documentation, and also to the excellent series of blog articles by Oliver Wulff, who is the main developer on Fediz.

2) Fediz example

Download the latest Apache CXF Fediz release (currently 1.0.3) here, and extract it to a new directory (${fediz.home}). It ships with two examples, 'simpleWebapp' and 'wsclientWebapp'. We will cover the former as part of this tutorial. We will use a Apache Tomcat 7 container to host both the Idp/STS and service application - this is not recommended, but is an easy way to get the example to work. Please see the associated README.txt of the simpleWebapp example for more information about how to deploy the example properly. Most of the deployment information in this section is based on the Fediz Tomcat documentation, which I recommend reading for a more in-depth treatment of deploying Fediz to Tomcat.

a) Deploying the IdP/STS

To deploy the Idp/STS to Tomcat:

• Create a new directory: ${catalina.home}/lib/fediz
• Edit ${catalina.home}/conf/catalina.properties and append ',${catalina.home}/lib/fediz/*.jar' to the 'common.loader' property.
• Copy ${fediz.home}/plugins/tomcat/lib/* to ${catalina.home}/lib/fediz
• Copy ${fediz.home}/idp/war/* to ${catalina.home}/webapps

Now we need to set up TLS:

• Copy ${fediz.home}/examples/samplekeys/tomcat-idp.jks to ${catalina.home}.
• Edit the TLS Connector in ${catalina.home}/conf/server.xml', e.g.: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="tomcat-idp.jks" keystorePass="tompass" clientAuth="false" sslProtocol="TLS" URIEncoding="UTF-8"  />

Now start Tomcat, and check that the STS is live by opening the STS WSDL in a web browser: 'https://localhost:8443/fediz-idp-sts/STSService?wsdl'

b) Deploying the service

To deploy the service to Tomcat:

• Copy ${fediz.home}/examples/samplekeys/tomcat-rp.jks to ${catalina.home}.
• Copy ${fediz.home}/examples/simpleWebapp/src/main/config/fediz_config.xml to ${catalina.home}/conf/
• Edit ${catalina.home}/conf/fediz_config.xml and replace '9443' with '8443'.
• Do a "mvn clean install" in ${fediz.home}/examples/simpleWebapp
• Copy ${fediz.home}/examples/simpleWebapp/target/fedizhelloworld.war to ${catalina.home}/webapps.

c) Testing the service

To test the service navigate to:

• https://localhost:8443/fedizhelloworld/  (this is not secured) 
• https://localhost:8443/fedizhelloworld/secure/fedservlet

With the latter URL, the browser is redirected to the IDP and is prompted for a username and password. Enter "alice/ecila" or "bob/bob" or "ted/det" to test the various roles that are associated with these username/password pairs.

Finally, you can see the metadata of the service via the standard URL:

• https://localhost:8443/fedizhelloworld/FederationMetadata/2007-06/FederationMetadata.xml