Friday, June 20, 2014

Apache CXF Fediz 1.1.1 released

Apache CXF Fediz 1.1.1 and 1.0.4 have been released. Fediz is a subproject of Apache CXF which implements the WS-Federation Passive Requestor Profile. It allows you to secure web applications using Single Sign-On (SSO) and Claims Based Access Control (CBAC), by redirecting users to an IdP (Identity Provider) for authentication, which in turn leverages the CXF STS (SecurityTokenService). Plugins are provided for the most popular web application containers, such as Apache Tomcat, Jetty, Spring, etc.

The 1.0.4 release  upgrades the underlying CXF dependency from 2.6.6 to 2.6.14, and the 1.1.1 release upgrades CXF from 2.7.7 to 2.7.11, thus picking up important bug fixes. Fediz 1.0.4 adds support for the wauth + whr parameters, while Fediz 1.1.1 adds support for wreq (see section 1.d below) and the older WS-Policy namespace, along with a few other bug fixes. See the Fediz JIRA for more information.

1) Fediz example

In a previous post introducing Apache CXF Fediz I gave instructions about how to deploy one of the Fediz 1.0.x examples to Apache Tomcat. In this section, I will update the deployment instructions for Fediz 1.1.1, as the examples have changed slightly since 1.0.x. In addition, I will give a simple example about how to use the new support for the "wreq" parameter added in Fediz 1.1.1 as part of FEDIZ-84 to request a SAML 1.1 token from the IdP.

Download the latest Apache CXF Fediz release (currently 1.1.1) 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/idp-ssl-server.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="idp-ssl-server.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/REALMA/STSServiceTransport?wsdl'

b) Deploying the service

To deploy the service to Tomcat:
  • Copy ${fediz.home}/examples/samplekeys/rp-ssl-server.jks and ${fediz.home}/examples/samplekeys/ststrust.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 (select realm "A") 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 
d) Obtaining a SAML 1.1 token via wreq

Let's assume that the Service Provider can only handle SAML 1.1 tokens. Fediz 1.1.1 supports this by allowing the service provider to configure a "request" parameter to send a WS-Trust RequestSecurityToken Element to the IdP containing a desired TokenType. To update the example above to obtain a SAML 1.1 token instead of a SAML 2.0 token do the following:
  • Update ${catalina.home}/conf/fediz_config.xml + add the following to the "protocol" section: <request type="String">&lt;RequestSecurityToken xmlns=&quot;http://docs.oasis-open.org/ws-sx/ws-trust/200512&quot;&gt;&lt;TokenType&gt;http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1&lt;/TokenType&gt;&lt;/RequestSecurityToken&gt;</request>
Now simply follow the same steps as before in accessing 'fedizhelloworld/secure/fedservlet' in a browser. You will see that the Bootstrap token that appears on the final screen is now a SAML 1.1 token.