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" />
    </util:map>

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>
   
    <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" />
           
    </util:map>


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.

    <properties>
      <cxf.version>2.5.2</cxf.version>

   </properties>

   <dependencies>

        <dependency>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-rt-transports-http</artifactId>
            <version>${cxf.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-rt-frontend-jaxws</artifactId>
            <version>${cxf.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-rt-ws-policy</artifactId>
            <version>${cxf.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.cxf.services.sts</groupId>
            <artifactId>cxf-services-sts-core</artifactId>
            <version>${cxf.version}</version>
        </dependency>
   </dependencies>  


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"
               keystoreFile="tomcatKeystore.jks"
               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">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsap10:UsingAddressing/>
            <sp:TransportBinding
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:TransportToken>
                     <wsp:Policy>
                        <sp:HttpsToken RequireClientCertificate="false"/>
                     </wsp:Policy>
                  </sp:TransportToken>
                  <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:TripleDesRsa15 />
                     </wsp:Policy>
                  </sp:AlgorithmSuite>
                  <sp:Layout>
                     <wsp:Policy>
                        <sp:Lax />
                     </wsp:Policy>
                  </sp:Layout>
                  <sp:IncludeTimestamp />
               </wsp:Policy>
            </sp:TransportBinding>
            <sp:SignedSupportingTokens
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:UsernameToken
                     sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                     <wsp:Policy>
                        <sp:WssUsernameToken10 />
                     </wsp:Policy>
                  </sp:UsernameToken>
               </wsp:Policy>
            </sp:SignedSupportingTokens>
            <sp:Wss11
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportRefKeyIdentifier />
                  <sp:MustSupportRefIssuerSerial />
                  <sp:MustSupportRefThumbprint />
                  <sp:MustSupportRefEncryptedKey />
               </wsp:Policy>
            </sp:Wss11>
            <sp:Trust13
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportIssuedTokens />
                  <sp:RequireClientEntropy />
                  <sp:RequireServerEntropy />
               </wsp:Policy>
            </sp:Trust13>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>


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"
class="org.apache.cxf.sts.operation.TokenIssueOperation">
    <property name="tokenProviders" ref="transportTokenProviders"/>
    <property name="services" ref="transportService"/>
    <property name="stsProperties" ref="transportSTSProperties"/>
    <property name="claimsManager" ref="claimsManager"/>
</bean>

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

<util:list id="attributeStatementProvidersList">
    <ref bean="claimsAttributeProvider"/>
</util:list>
   
<bean id="claimsAttributeProvider"
        class="org.apache.cxf.sts.claims.ClaimsAttributeStatementProvider">
</bean>

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"
        class="org.talend.security.sts.UsernamePasswordCallbackHandler">
        <property name="passwords" ref="passwords" />
    </bean>

    <jaxws:endpoint id="transportSTS1"
        implementor="#transportSTSProviderBean"
        address="/STSService"
        wsdlLocation="/WEB-INF/wsdl/ws-trust-1.4-service.wsdl"
        xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        serviceName="ns1:SecurityTokenService"
        endpointName="ns1:TransportUT_Port">
        <jaxws:properties>
            <entry key="ws-security.callback-handler" value-ref="upCallBackHandler"/>
        </jaxws:properties>
    </jaxws:endpoint>

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"
        class="org.apache.cxf.sts.claims.ClaimsManager">
        <property name="claimHandlers" ref="claimHandlerList" />
    </bean>
   
    <util:list id="claimHandlerList">
        <ref bean="fileClaimsHandler"/>
    </util:list>
   
    <bean id="fileClaimsHandler"
        class="org.talend.security.sts.FileClaimsHandler">
       
        <property name="userClaims" ref="userClaims" />
    </bean>

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
      <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>tomcat-maven-plugin</artifactId>
          <version>1.1</version>
          <configuration>
               <server>myTomcat</server>
               <url>http://localhost:9080/manager/text</url>
               <path>/${project.build.finalName}</path>
          </configuration>
      </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:
    <url>http://localhost:9080/manager</url>


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/">
   <soap:Header>
      <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:Username>alice</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ecila</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soap:Header>
   <soap:Body>
      <wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
         <wst:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer</wst:KeyType>
         <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"/>
         </wst:Claims>
         <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
         <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
            <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
               <wsa:Address>https://localhost:8081/doubleit/services/doubleittransportsaml1claims</wsa:Address>
            </wsa:EndpointReference>
         </wsp:AppliesTo>
      </wst:RequestSecurityToken>
   </soap:Body>
</soap:Envelope>



and this the expected response (called RSTR):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Header/>
   <soap:Body>
      <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">
         <RequestSecurityTokenResponse>
            <TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</TokenType>
            <RequestedSecurityToken>
               <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">
                  <saml2:Issuer>DoubleItSTSIssuer</saml2:Issuer>
                  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                     <ds:SignedInfo>
                        <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:Transforms>
                              <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:Transform>
                           </ds:Transforms>
                           <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                           <ds:DigestValue>YIHAnHYol0pOs1Mc4MWhgwTP540=</ds:DigestValue>
                        </ds:Reference>
                     </ds:SignedInfo>
                     <ds:SignatureValue>Mb3WfLefs0KziHe7NjhLUBsgfD2spr8M3HpqqhpO+yzIqMrw9eY1r7nFIh3nWeDOHY4odPBa0w06XDpzPGSzdmm9k/Ay+S6trtkgS/Hoi3sL8CGAmAHEPWSO4+td6MNrucdVhG9P+do6JflXDOppDroGh/YjvxpdosM55G2TbL0=</ds:SignatureValue>
                     <ds:KeyInfo>
                        <ds:X509Data>REMOVED</ds:X509Certificate>
                        </ds:X509Data>
                     </ds:KeyInfo>
                  </ds:Signature>
                  <saml2:Subject>
                     <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:Subject>
                  <saml2:Conditions NotBefore="2011-10-11T07:55:08.860Z" NotOnOrAfter="2011-10-11T08:00:08.860Z">
                     <saml2:AudienceRestriction>
                        <saml2:Audience>https://localhost:8081/doubleit/services/doubleittransportsaml1claims</saml2:Audience>
                     </saml2:AudienceRestriction>
                  </saml2:Conditions>
                  <saml2:AttributeStatement>
                     <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>
                     <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>
                     <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>
                     </saml2:Attribute>
                  </saml2:AttributeStatement>
               </saml2:Assertion>
            </RequestedSecurityToken>
            <RequestedAttachedReference>
               <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>
            </RequestedAttachedReference>
            <RequestedUnattachedReference>
               <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>
            </RequestedUnattachedReference>
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
               <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
                  <wsa:Address>https://localhost:8081/doubleit/services/doubleittransportsaml1claims</wsa:Address>
               </wsa:EndpointReference>
            </wsp:AppliesTo>
            <Lifetime>
               <ns2:Created>2011-10-11T07:55:08.872Z</ns2:Created>
               <ns2:Expires>2011-10-11T08:00:08.872Z</ns2:Expires>
            </Lifetime>
         </RequestSecurityTokenResponse>
      </RequestSecurityTokenResponseCollection>
   </soap:Body>
</soap:Envelope>



Have fun!