Configuring JBossWS Web Services security to use JBoss Security Domains

Ovidiu Feodorov <ovidiu@novaordis.com> 12/14/2010

This document explains how to configure a native-stack JBossWS Web Service and the associated
client to take advantage of new configuration features introduced with the JBossSX/JBossWS code
changes described by Case 00390063.

Since Case 00390063, it is possible to configure a native-stack Web Service in such a way that no
keystore/truststore details (except conventional key labels, and not actual key aliases) are
present in the the JBossWS security configuration files.

This feature can be used when it is necessary to isolate operational environment security
configuration details such as key store and trust store locations, passwords and key aliases
from JBossWS configuration files bundled with deployment artifacts produced by a separate
development organization. The deployment artifacts refer to a series of conventional names -
the JNDI name of a JAAS security domain and a set of labels that designate keys and certificates
used to sign/encrypt the WS message. The operations group has the freedom to declare
different security configuration details for different environments, without changing the
deployment artifacts.

Configuring the Web Service and the associated client involves the following steps:

1. Configuration of the JAAS Security Domain -------------------------------------------------------

The security domain must declare the keystore and truststore URLs, as usual, as well as
two new elements:

1.1 A service authorization token

This service authorization token establishes the trust between the JAAS security domain
and the WS layer that requests private keys from the JAAS security domain. It is declared
as follows:

    <attribute name="ServiceAuthToken">abc123</attribute>

The same service authorization token must be present in the configuration of the WS layer, as
shown below.


1.2 A label-to-key-alias map

The mapping is necessary to prevent the need of specifying actual key aliases in the WS
layer configuration. The labels are conventional names given to keys/certificates with
specific purposes:

       <attribute name="AdditionalOptions">
            web-services-signature-key=secret_key_alias_1
            web-services-encryption-certificate=certificate_alias_1
       </attribute>

The labels will also be present in the configuration of the WS layer.


1.3 Complete JAAS security domain configuration example.

A complete JAAS security domain that uses JKS keystores/truststores and includes the elements
introduced above, follows:

<?xml version="1.0" encoding="UTF-8"?>
<server>
    <mbean code="org.jboss.security.plugins.JaasSecurityDomain"
           name="test:service=JaasSecurityDomain,domain=TEST_WS">
        <constructor>
            <arg type="java.lang.String" value="TEST_WS"/>
        </constructor>
        <attribute name="KeyStoreType">JKS</attribute>
        <attribute name="KeyStorePass">password</attribute>
        <attribute name="KeyStoreURL">file:///sys_apps_01/JBoss/jboss-eap-5.1-reference/server/reference/conf/props/test-keystore.jks</attribute>
        <attribute name="TrustStoreType">JKS</attribute>
        <attribute name="TrustStoreURL">file:///sys_apps_01/JBoss/jboss-eap-5.1-reference/server/reference/conf/props/test-truststore.jks</attribute>
        <attribute name="TrustStorePass">password</attribute>
        <attribute name="ServiceAuthToken">abc123</attribute>
        <attribute name="AdditionalOptions">
            web-services-signature-key=secret_key_alias_1
            web-services-encryption-certificate=certificate_alias_1
        </attribute>
    </mbean>
</server>



2. Configuration of the WS layer -------------------------------------------------------------------

2.1 The jboss-wsse-client.xml configuration file should specify the JNDI name of the JAAS security
domain and key/certificate labels as follows:


<?xml version="1.0" encoding="UTF-8"?>
<jboss-ws-security
        xmlns="http://www.jboss.com/ws-security/config"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.jboss.com/ws-security/config
        http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
    <security-domain jndi="java:/jaas/TEST_WS" authToken="abc123"/>
    <config>
        <username/>
        <sign securityDomainAliasLabel="web-services-signature-key"/>
        <encrypt securityDomainAliasLabel="web-services-encryption-certificate"/>
        <requires>
            <signature/>
            <encryption/>
        </requires>
    </config>
</jboss-ws-security>


2.2 The jboss-wsse-server.xml configuration file should specify the JNDI name of the JAAS security
domain and key/certificate labels as follows:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-ws-security
        xmlns="http://www.jboss.com/ws-security/config"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.jboss.com/ws-security/config
        http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
    <security-domain jndi="java:/jaas/TEST_WS" authToken="abc123"/>
    <config>
        <username/>
        <sign securityDomainAliasLabel="web-services-signature-key"/>
        <encrypt securityDomainAliasLabel="web-services-encryption-certificate"/>
        <requires>
            <signature/>
            <encryption/>
        </requires>
    </config>
</jboss-ws-security>


Notes: ---------------------------------------------------------------------------------------------

The solution described by Case 00390063 has the following limitations:

1. The private keys and the public certificates must be available in the same key store.

2. The JBossWS stack that comes with JBoss EAP 5.1.0 exhibits a defect requiring to
   bundle the client-side security configuration file jboss-wsse-client.xml under
   WEB-INF/classes/WEB-INF instead of WEB-INF, as it would have been expected.


----------------------------------------------------------------------------------------------------