October 11, 2011

Configure and deploy CXF 2.5 STS - Part I

Talend has donated an STS implementation to the Apache CXF community as posted already on this here

This is the first part of a series of blogs on using WS-Federation Passive Requestor Profile to implement a Web and Web Services SSO solution from a web application to a target Web Service. The used technologies are CXF 2.5 (to be released soon) and Tomcat 7.

  • Part I
    Configure and deploy CXF STS using Claims
  • Part II
    Configure and deploy Identity Provider (IdP)
  • Part III
    Configure and deploy Tomcat Relying Party (RP)
  • Part IV
    Enhance Tomcat RP to call a target web services which delegates the identity
  • Part V
    Interoperability testing with Microsoft Windows Identity Foundation

The STS in this part is configured to support the following functionality:
  • STS WSDL is enriched with the WS-SecurityPolicy information
  • STS issues a signed SAML 2.0 token
  • STS is secured using HTTPS
  • STS validates an incoming UsernameToken against a local file store
  • STS adds claims information to the SAML token in an attribute statement
You can find a running maven project called services/sts here.

1. Username and password management

The users and passwords are configured in a spring configuration file in WEB-INF/passwords.xml. The XML file has the following structure:

    <util:map id="passwords">
        <entry key="alice"
            value="ecila" />
        <entry key="bob"
            value="bob" />
        <entry key="ted"
            value="det" />

The intention of this STS example is to illustrate how to set up an STS. If you have an LDAP directory in place or any other JAAS based LoginModule you can also plug in the WSS4J JAASUsernameTokenValidator.

2. Claims management

The claims for each user are configured in a spring configuration file also in WEB-INF/userClaims.xml. The XML file has the following structure:

    <util:map id="userClaims">
        <entry key="alice"
            value-ref="aliceClaims" />
        <entry key="bob"
            value-ref="bobClaims" />
        <entry key="ted"
            value-ref="tedClaims" />
    <util:map id="aliceClaims">
        <entry key="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
            value="Alice" />
        <entry key="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
            value="Smith" />
        <entry key="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
            value="alice@mycompany.org" />
        <entry key="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role"
            value="user" />

The claim id's are configured according to chapter 7.5 in the specification Identity Metasystem Interoperability. The mapping of claims to a SAML attribute statement are described in chapter 7.2.
There is no standard URI for role. Therefore, I reuse Microsoft's role URI which is used by ADFS (Active Directory Federation Service) and Windows Identity Foundation (WIF). If the STS issues claims using the same role URI, you get role-based access control (or claims based authorization support for WIF based applications out-of-the-box).

The intention of this STS example is to illustrate how to set up an STS. If you have an LDAP directory in place you can configure the LdapClaimsHandler where you configure the mapping of the claim id (URI) to an LDAP user attribute. 

3. Project dependencies
The STS has the following dependencies in the Maven project.





4. STS endpoint configuration

Setting up the STS involves several steps. The STS is configured using the spring framework. First step is to download Tomcat 7.

4.1 Configure HTTP/S connector in Tomcat

The HTTP connector should be configured with port 9080.

The HTTPS connector in Tomcat is configured in conf/server.xml. Deploy the tomcatkeystore.jks of the example project  to the Tomcat root directory if the Connector is configured as illustrated:

    <Connector port="9443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               keystorePass="tompass" sslProtocol="TLS" />

Update: Have a read through the following blog here which describes how to generate a keystore.

4.2 Configure the WS-SecurityPolicies of the STS endpoint

The following policies must be added to the WSDL. CXF provides other ways to correlate policies with a wsdl subject (port type, service, port, ...). I've chosen the simplest one where the policies are embedded into the wsdl for illustration purposes. The WSDL can be found in WEB-INF/wsdl/ws-trust-1.4-service.wsdl

The following policy defines a transport binding (https) and expects a UsernameToken be present in the WS-Security header. The UsernameToken must be signed which is implicitly supported by HTTPS:

    <wsp:Policy wsu:Id="Transport_policy">
                        <sp:HttpsToken RequireClientCertificate="false"/>
                        <sp:TripleDesRsa15 />
                        <sp:Lax />
                  <sp:IncludeTimestamp />
                        <sp:WssUsernameToken10 />
                  <sp:MustSupportRefKeyIdentifier />
                  <sp:MustSupportRefIssuerSerial />
                  <sp:MustSupportRefThumbprint />
                  <sp:MustSupportRefEncryptedKey />
                  <sp:MustSupportIssuedTokens />
                  <sp:RequireClientEntropy />
                  <sp:RequireServerEntropy />

4.3 Configure TokenProvider

This STS endpoint configuration only supports to issue SAML tokens (2.0 or 1.1). For a full list of the supported features by the STS check this blog.

The configuration related to issuing a token is located in the following spring configuration file (cxf-transport.xml):

<bean id="transportIssueDelegate"

    <property name="tokenProviders" ref="transportTokenProviders"/>
    <property name="services" ref="transportService"/>
    <property name="stsProperties" ref="transportSTSProperties"/>
    <property name="claimsManager" ref="claimsManager"/>

<util:list id="transportTokenProviders">

    <ref bean="transportSamlTokenProvider"/>

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

<util:list id="attributeStatementProvidersList">
    <ref bean="claimsAttributeProvider"/>

<bean id="claimsAttributeProvider"

The last bean claimsAttributeProvider is described in section 4.5

4.4 Configure Username/password authentication

As described in section 1. the user and passwords are managed in the file WEB-INF/passwords.xml.

To configure username/password authentication in CXF/WSS4J you must provide a CallbackHandler. The CallbackHandler is part of this example project.

The configuration is located in the following spring configuration file (cxf-transport.xml):

     <import resource="passwords.xml" />
    <bean id="upCallBackHandler"
        <property name="passwords" ref="passwords" />

    <jaxws:endpoint id="transportSTS1"
            <entry key="ws-security.callback-handler" value-ref="upCallBackHandler"/>

The bean upCallBackHandler implements the CallbackHandler which is configured as a jaxws property ws-security.callback-handler in jaxws:properties of the jaxws:endpoint configuration. 

4.5 Configure ClaimsManager

Claims data can be stored in different kind of ID systems which can be accessed using LDAP, Web Services, REST whatever. The retrieval of claims is independent of any specific security token type and group in a list of claimshandler. Each claims handler must implement what kind of claims he can provide. It's the responsibility of the ClaimsManager to call the corresponding ClaimsHandler if a specific claim is requested by a STS client.

The claims related configuration is summerized in the following spring configuration file (cxf-transport.xml):

    <import resource="userClaims.xml" />
    <bean id="claimsManager"
        <property name="claimHandlers" ref="claimHandlerList" />
    <util:list id="claimHandlerList">
        <ref bean="fileClaimsHandler"/>
    <bean id="fileClaimsHandler"
        <property name="userClaims" ref="userClaims" />

The bean userClaims is defined in the imported spring configuration file userClaims.xml.

5. Deploy the STS to Tomcat

To deploy the STS using Maven you have to follow these steps:
  • Configuring the following maven plugin
  • Add the server with username and password to your settings.xml
  • Ensure the user has the role "manager-script" as described here
  • Run mvn tomcat:redeploy
    (I recommend to use redeploy as deploy works the first time only)
If you use Tomcat 6, you must change the url of the tomcat maven plugin:

6. Test the STS with SoapUI

This is a sample request (called RST) to the STS:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1">
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ecila</wsse:Password>
      <wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wst:Claims Dialect="http://schemas.xmlsoap.org/ws/2005/05/identity" xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity">
            <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"/>
            <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"/>
            <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"/>
         <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
            <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">

and this the expected response (called RSTR):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <RequestSecurityTokenResponseCollection xmlns="http://docs.oasis-open.org/ws-sx/ws-trust/200512" xmlns:ns2="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns3="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns4="http://www.w3.org/2005/08/addressing" xmlns:ns5="http://docs.oasis-open.org/ws-sx/ws-trust/200802">
               <saml2:Assertion ID="_ACF774CE2C8F387D9413183197088603" IssueInstant="2011-10-11T07:55:08.860Z" Version="2.0" xsi:type="saml2:AssertionType" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                        <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                        <ds:Reference URI="#_ACF774CE2C8F387D9413183197088603">
                              <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                                 <ec:InclusiveNamespaces PrefixList="xs" xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                           <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                     <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="http://cxf.apache.org/sts">alice</saml2:NameID>
                     <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/>
                  <saml2:Conditions NotBefore="2011-10-11T07:55:08.860Z" NotOnOrAfter="2011-10-11T08:00:08.860Z">
                     <saml2:Attribute Name="givenname" NameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/claims">
                        <saml2:AttributeValue xsi:type="xs:string">Alice</saml2:AttributeValue>
                     <saml2:Attribute Name="surname" NameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/claims">
                        <saml2:AttributeValue xsi:type="xs:string">Smith</saml2:AttributeValue>
                     <saml2:Attribute Name="emailaddress" NameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/claims">
                        <saml2:AttributeValue xsi:type="xs:string">alice@mycompany.org</saml2:AttributeValue>
               <ns3:SecurityTokenReference wsse11:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" xmlns:wsse11="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
                  <ns3:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">#_ACF774CE2C8F387D9413183197088603</ns3:KeyIdentifier>
               <ns3:SecurityTokenReference wsse11:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" xmlns:wsse11="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
                  <ns3:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">_ACF774CE2C8F387D9413183197088603</ns3:KeyIdentifier>
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
               <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">

Have fun!


  1. Hello Oliver,

    Thank you for the excellent article, and also the STS implementation your company contributed to CXF.

    I need to implement now an STS and would like to run your demo project as first step. Everything seems ok, except I cannot find the tomcatkeystore.jks keystore you are writing about in this article. Could you please make it downloadable?

    Thanks a lot,
    Ivan Brencsics

    1. Hi Ivan

      Happy to hear you're interested into it. You can download the keystore here:

      Glen Mazza described on his blog how to create certificates:

      Keep in mind that these are self-signed certificates and not intended to be used for production.

      Oliver Wulff

    2. Thanks Oliver, I managed to make your project running. In the meantime I read the excellent articles by Glen Mazza as well, all these are big help to me now. It is not very easy to do the first steps in the WS-Trust topic.

  2. Hello Oliver,

    I spent a few days with experimenting with your STS implementation. Also read the blogs of Glen Mazza and Colm O hEigeartaigh. Now I have quite a good understanding of the topic.

    What I would need is a SAML 2.0 token service that would populate a token with Attribute Statements, Authorization Decision Statements and Authentication Statements. The only example describing the Attribute Statement usage is your example cxf-transport.xml. But I cannot figure out how to insert the other two kinds of statements. And also I cannot create a client (Java or Spring) that contains the tag. I am experimenting based on the IssueUnitTest.

    Could you suggest where to find more information on this? I checked the systests, but I have not found anything on this, maybe I overlooked something. I could spend some more days with doing deeper into the source code, but maybe you could give me some hint where to look for more information.

    Thanks a lot,

    1. Hi Ivan

      I was on vacation last week. If you have any questions regarding the STS and such, feel free to post your questions to the CXF user mailing list:

      The SAMLTokenProvider provides attributes for all the SAML statements. You can find some unit tests here:


      You can code your own implementations for authentication, attribute and authorization statements and configure them in the SAMLTokenProvider bean.

      BTW, the AuthzDecisionStatement is frozen in SAML 2.0. See here (2.7.4):
      IMHO, I wouldn't invest too much into it. You might be able to cover your requirements using the Claims feature of the STS.

  3. Hai, guys what an interesting topic thanks a lot for such a blog, but I have some problems in configuration.

    I was able to deploy both the STS and IDP on tomcat successfully in the same machine as per instruction, but my problem is ,I can not test either of the if they work or not. i'm not sure if it because of the following statement or not

    As long as you don't have a relying party in place you can't easily test the IDP.

    so can you please give me a step by step procedure on how to test the STS and IDP after deploying them to tomcat?

    I really need to get this ...
    Thank you in advance

    1. Hi there

      I was a little bit lazy in updating the blogs and link to the most recent sources and blog entries. I've done this now.

      - the following blog describes where the most recent sources are located and the enhancements:

      - You can test the STS with the soapui test message described here:

      - You're right that you can test the IDP only with the relying party. This blog post is available here:

      You can also use the CXF user mailing list to post questions as there are more people reading it than the comments on this blog ;-)


    2. wa wsignin1.0
      wreply http://localhost:8080/wsfedhelloworld/secureservlet/fed
      wtrealm http://localhost:8080/wsfedhelloworld

      how do we use these parameters in tomcat because, i only get wa missing parameter error?

      in my tomcat this is what is required

      Context Path (required):

      XML Configuration file URL:

      WAR or Directory URL:

      thank you

    3. Could you attach a snippet of the log?

      Have you deployed the fediz-idp and fediz-idp-sts into one tomcat instance and deployed the fediz-core and fediz-tomcat plugin to a second tomcat instance. When you access your application in the 2nd tomcat instance, it will redirect your browser and add the above http parameters to the redirect url.

      Maybe your question should be placed on this blog (context wise) http://owulff.blogspot.com/2011/11/configure-tomcat-for-federation-part.html as it describes the federation functionality in tomcat.

  4. I Have you deployed the fediz-idp and fediz-idp-sts into one tomcat instance and deployed the fediz-core and fediz-tomcat plugin to a second tomcat instance.
    now i'm wondering when will i get to the part where I see the identity provider and interact with it on the browser?

    Tomcat instance 1 log file

    Mar 5, 2012 11:35:46 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: init: Associated with Deployer 'Catalina:type=Deployer,host=localhost'
    Mar 5, 2012 11:35:46 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: init: Global resources are available
    Mar 5, 2012 11:35:46 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: deploy: Deploying web application '/fedizidpsts'
    Mar 5, 2012 11:35:46 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: Uploading WAR file to C:\apache-tomcat-7.0.25\tomcat-instance1\webapps\fedizidpsts.war
    Mar 5, 2012 11:37:07 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: list: Listing contexts for virtual host 'localhost'
    Mar 5, 2012 11:59:04 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: deploy: Deploying web application '/fedizidp'
    Mar 5, 2012 11:59:04 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: Uploading WAR file to C:\apache-tomcat-7.0.25\tomcat-instance1\webapps\fedizidp.war
    Mar 5, 2012 11:59:30 AM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: list: Listing contexts for virtual host 'localhost'

    Tomcat instance 2 log file

    Mar 5, 2012 12:16:12 PM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: init: Associated with Deployer 'Catalina:type=Deployer,host=localhost'
    Mar 5, 2012 12:16:12 PM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: init: Global resources are available
    Mar 5, 2012 12:16:12 PM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: list: Listing contexts for virtual host 'localhost'
    Mar 5, 2012 12:30:44 PM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: list: Listing contexts for virtual host 'localhost'
    Mar 5, 2012 12:31:00 PM org.apache.catalina.core.ApplicationContext log
    INFO: HTMLManager: list: Listing contexts for virtual host 'localhost'

    1. That's really not too much in the logs. I don't even see a request to your application which should be deployed in tomcat instance 2.
      Have you deployed the fedizhelloworld application in tomcat instance 2? I don't see a log statement like "Deploying web application '/fedizhelloworld'.
      You can find the maven project fediz-tomcat-example here:

      If you have deployed your own application please share with me your META-INF/context.xml. It should look similar as the one in fediz-tomcat-example which is described here:

      Maybe increase the logging level in conf/logging.properties by adding the following lines:
      org.apache.catalina.authenticator.level = FINEST

      org.apache.catalina.realm.level = FINEST

  5. Is it possible for me to get your working files and than configure the port numbers , because i'm not getting this thing right ?

  6. Hey thanks Oliver

    Now it working pretty fine, I can see all the configured users and their claims thanks hey .... wonderful work

    keep it up

  7. hi Oliver,

    The above works fine for Keytype as Bearer. However If I change to PublicKey or SymmetricKey it does not work. Is there an additional configuration required?

  8. Sorry for the late reply. Do you use the Fediz IDP and Fediz Plugin or combine it with another solution?

    If it's purely Fediz, you have to configure the IDP to use SAML HOK in the STSClientAction bean. Did you try this? What kind of error did you get?

    Note: I'd recommend to post these kind of questions to the CXF mailing list (http://cxf.apache.org/mailing-lists.html). I didn't implement this feature and the person who implemented it is also active in the CXF mailing list.