Java TM Web Services Security  Sample Application 1.0


 Samples Index 



WebServices Security Sample Application 1.0


This document describes Java TM WebServices Security Sample Application 1.0 as deployed  in the Sun Java System Application Server  Platform Edition 8.

This  document contains the following sections:

1.0 Introduction
2.0 Directory Structure
3.0 Pre-Requisites
4.0 Securing WebServices
5.0 Building from the source
6.0 Configuration parameters
7.0 Troubleshooting


1.0 Introduction

This document explains the WebServices Security Sample Application.

This sample is based on the Webservices JAX-RPC simple application, it uses the WebService that is defined in JAX-RPC simple application and secures the Webservice using various security mechanisms described below.

This sample is not intended to explain webservices in general, instead it explains how a webservice can be secured using various security mechanism.  Before addressing how to secure WebServices, let us look at what happens during a WebService invocation. The following diagram(Fig -1) shows both the use-case view and component view of WebService client invocation.  



Webservice Client(Use-case view and component view)  
Fig-2 shows the use-case view of Webservice invocation from the server side. From diagrams(Fig-1 and Fig-2)  we know that webservices requests are ultimately sent from the client to the server in the form of HTTP requests. (Note: SOAP over HTTP is one specific Webservices binding, there can be other bindings). Now we can address how WebServices can be secured at various levels.
WebService invocation server side(use-case view)

WebServices can be secured at various levels

  1. BasicAuth : In this mechanism WebServices are protected using HTTP protocol's basic authentication security feature. (i.e The WebService implementation bean(either a Servlet or an EJB is protected with username password. The client accessing this WebService should provide username and password to access this WebService) 
  2. Transport Level Security : In this mechanism WebServices are protected at the Transport level(SSL). (i.e the WebService implementation bean either a Servlet or an EJB establishes SSL connection between the client and server during WebService invocation. There are two ways to esablish transport level security
    1. BasicSSL : In BasicSSL, the SSL connection is established using Server only authentication(i.e the Server provides its identity to the client using server certificate, client can verify the server's identity using a trust store.)
    2. ClientCert : In ClientCert protection the SSL connection is established using both client and server authentication. (i.e Both Server and Client provide their certificates and these certificates are verified against a trust store(or multiple trust stores).
  3. Message Level Security : In Message level security, the security information is stored in the XML messages that are exchanged during WebService invocation, this involves using XML Encryption and XML digital signatures. Message Level Security can be enabled in two ways
    1. At the application server level by enabling Appserver's default WSS providers, webservices can be protected at the message level.  In this case the developer need not code the webservices in a special manner,  but the webservices are protected using default configuration files and default WSS providers.
    2. At the application level by modifying the application runtime xml (sun-ejb-jar.xml or web.xml). In this case the developer can selectively specify how message level security can be used (for example to a specific method or for the whole webservices)
Note: The xms sample shows how to enable message level security by enabling appserver's default WSS providers.
The following J2EE Architecture diagram shows how a WebService can be accessed from client container using SOAP/HTTP. A WebService that is implemented by a Servlet or EJB component can be secured with the various security mechanism described above.

webservice Architecture


In the following sections we will explore the two protection mechanisms(BasicAuth and Transport level Security) with servlet based WebService endpoint and EJB based WebService endpoint.


2.0 Directory Structure

This section explains the directory structure

docs 

 HTML Documentation

ejb

 WebServices implemented using EJB component

web

 WebServices implemented using Servlet component

src

 Source files

basicAuth

 Shows securing WebServices using Basic Authentication 

basicSSL

 Shows securing WebServices using Basic SSL (Transport Level Security) 
clientCert
 Shows securing WebServices using Client certificate (Transport Level Security)
xms
 Shows securing WebServices using Message Level Security

Note: All four variations (basicAuth, basicSSL and clientCert, xms) are explained for both Servlet and EJB WebService endpoints.


3.0 Pre-Requisites

Before running any WebServices Security samples, Please verify the following



4.0 Securing WebServices

This section explains how the WebServices security mechanism are configured (Three variations for servlet based WebService endpoint and three variations for EJB based WebService endpoint are explained here)

4.1 Securing WebServices for basicAuth (Servlet based WebService endpoint)

In a servlet based WebService endpoint, basicAuth is configured by performing the following steps
  <security-constraint>
    <display-name>SecurityConstraint</display-name>
    <web-resource-collection>
    <web-resource-name>WRCollection</web-resource-name>
     <url-pattern>/basicAuth</url-pattern>
    </web-resource-collection>
    <auth-constraint>
    <role-name>asadmin</role-name>
    </auth-constraint>
    <user-data-constraint>
    <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>default</realm-name>
  </login-config>
  <security-role>
    <role-name>asadmin</role-name>
  </security-role>
 <security-role-mapping>
    <role-name>asadmin</role-name>
    <principal-name>admin</principal-name>
  </security-role-mapping>
    <exec executable="${exec.appclient}" >
    <arg line="${exec.appclient.part2}" />
    <arg line=" -client ${stub.file}"/>
    <arg line="${admin.user} ${admin.password}" />
    </exec>
helloStub._setProperty("javax.xml.rpc.security.auth.username", args[0]);    helloStub._setProperty("javax.xml.rpc.security.auth.password", args[1]);

4.2 Securing WebServices for basicSSL (Servlet based WebService endpoint)

In a servlet based WebService endpoint, basicSSL is configured by performing the following steps. The main difference between basicAuth and basicSSL is the user-data-constraint element, and the way trust store is specified in the client runtime.
  <security-constraint>
    <display-name>SecurityConstraint</display-name>
    <web-resource-collection>
        <web-resource-name>WRCollection</web-resource-name>
    <url-pattern>/basicSSL</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>asadmin</role-name>
    </auth-constraint>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>

  </security-constraint>
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>default</realm-name>
  </login-config>
  <security-role>
    <role-name>asadmin</role-name>
  </security-role>

 <security-role-mapping>
    <role-name>asadmin</role-name>
    <principal-name>admin</principal-name>
  </security-role-mapping>
    <exec executable="${exec.appclient}" >
    <env key="VMARGS" value="-Djava.protocol.handler.pkgs=javax.net.ssl -Djavax.net.ssl.trustStore=${trustStore}" />
    <arg line="${exec.appclient.part2}" />
    <arg line=" -client ${stub.file}"/>
    <arg line="${admin.user} ${admin.password}" />
    </exec>

4.3 Securing WebServices for clientCert (Servlet based WebService endpoint)

The main differences between basicSSL and clientCert mechanisms are
  1. There is no user-data-constraint element in the security-constraint.
  2. security-role-mapping is not necessary , because there is no user or role involved in transport protecting the servlet.( though this can be done as well, if required)
  3. Both client keystore and trust stores are specified in the client runtime.
  4. User name and password are not passed to the client runtime or to the Stubs.
  5. Authentication is done through both client and server certificates.
In a servlet based WebService endpoint, clientCert security mechanism is configured by performing the following steps.
  <security-constraint>
    <display-name>SecurityConstraint</display-name>
    <web-resource-collection>
    <web-resource-name>WRCollection</web-resource-name>
    <url-pattern>/clientCert</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  <login-config>
    <auth-method>CLIENT-CERT</auth-method>
  </login-config>
    <exec executable="${exec.appclient}" >
    <env key="VMARGS" value="-Djava.protocol.handler.pkgs=javax.net.ssl -Djavax.net.ssl.keyStore=${keystore} -Djavax.net.ssl.keyStorePassword=${keystore.password} -Djavax.net.ssl.trustStore=${trustStore}" />
    <arg line="${exec.appclient.part2}" />
    <arg line=" -client ${stub.file}"/>
    </exec>

4.4 Securing WebServices for basicAuth (EJB based WebService endpoint)

In a EJB based WebService endpoint, basicAuth security mechanism is configured by performing the following steps.

  <assembly-descriptor>
    <security-role>
    <role-name>asadmin</role-name>
    </security-role>
    <method-permission>
    <role-name>asadmin</role-name>
    <method>
    <ejb-name>HelloWorld</ejb-name>
    <method-intf>ServiceEndpoint</method-intf>
    <method-name>sayHello</method-name>
    <method-params>
      <method-param>java.lang.String</method-param>
    </method-params>
    </method>
    </method-permission>
 </assembly-descriptor>
    <ior-security-config>
     <transport-config>
       <integrity>none</integrity>
       <confidentiality>none</confidentiality>
       <establish-trust-in-target>none</establish-trust-in-target>
       <establish-trust-in-client>none</establish-trust-in-client>
     </transport-config>
     <as-context>
       <auth-method>username_password</auth-method>
       <realm>default</realm>
       <required>true</required>
     </as-context>
     <sas-context>
       <caller-propagation>none</caller-propagation>
     </sas-context>
    </ior-security-config>
    <webservice-endpoint>
    <port-component-name>HelloIF</port-component-name>
    <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
    <login-config>
       <auth-method>BASIC</auth-method>
    </login-config>
    </webservice-endpoint>
  <security-role-mapping>
    <role-name>asadmin</role-name>
    <principal-name>admin</principal-name>
  </security-role-mapping>
    <exec executable="${exec.appclient}" >
    <arg line="${exec.appclient.part2}" />
    <arg line=" -client ${stub.file}"/>
    <arg line="${admin.user} ${admin.password}" />
    </exec>

4.5 Securing WebServices for basicSSL (EJB based WebService endpoint)

In a EJB based WebServices end point basicSSL is configured by performing the following steps. The main difference between basicAuth and basicSSL is the transport-config element in sun-ejb-jar.xml and the way trustStore is specified to the client runtime.

  <assembly-descriptor>
    <security-role>
    <role-name>asadmin</role-name>
    </security-role>
    <method-permission>
    <role-name>asadmin</role-name>
    <method>
    <ejb-name>HelloWorld</ejb-name>
    <method-intf>ServiceEndpoint</method-intf>
    <method-name>sayHello</method-name>
    <method-params>
      <method-param>java.lang.String</method-param>
    </method-params>
    </method>
    </method-permission>
 </assembly-descriptor>
    <ior-security-config>
     <transport-config>
       <integrity>required</integrity>
       <confidentiality>required</confidentiality>
       <establish-trust-in-target>supported</establish-trust-in-target>
       <establish-trust-in-client>none</establish-trust-in-client>
     </transport-config>
     <as-context>
       <auth-method>username_password</auth-method>
       <realm>default</realm>
       <required>true</required>
     </as-context>
     <sas-context>
       <caller-propagation>none</caller-propagation>
     </sas-context>
    </ior-security-config>
    <webservice-endpoint>
    <port-component-name>HelloIF</port-component-name>
    <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
    <login-config>
       <auth-method>BASIC</auth-method>
    </login-config>
    </webservice-endpoint>
  <security-role-mapping>
    <role-name>asadmin</role-name>
    <principal-name>admin</principal-name>
  </security-role-mapping>
    <exec executable="${exec.appclient}" >
    <env key="VMARGS" value="-Djava.protocol.handler.pkgs=javax.net.ssl -Djavax.net.ssl.trustStore=${trustStore}" />
    <arg line="${exec.appclient.part2}" />
    <arg line=" -client ${stub.file}"/>
    <arg line="${admin.user} ${admin.password}" />
    </exec>

4.6 Securing WebServices for clientCert (EJB based WebService endpoint)

The main differences between basicSSL and clientCert mechanisms are
  1. There is no method-permission element in ejb-jar.xml.
  2. security-role-mapping is not necessary , because there is no user or role involved in transport protecting the servlet.( though this can be done as well, if required)
  3. Both client keystore and trust stores are specified in the client runtime.
  4. User name and password are not passed to the client runtime or to the Stubs.
  5. Authentication is done through both client and server certificates.

In a EJB based WebServices end point, clientCert is configured by performing the following steps.

    <ior-security-config>
     <transport-config>
       <integrity>required</integrity>
       <confidentiality>required</confidentiality>
       <establish-trust-in-target>supported</establish-trust-in-target>
       <establish-trust-in-client>required</establish-trust-in-client>
     </transport-config>
     <as-context>
       <auth-method>none</auth-method>
       <realm>default</realm>
       <required>false</required>
     </as-context>
     <sas-context>
       <caller-propagation>none</caller-propagation>
     </sas-context>
    </ior-security-config>
    <webservice-endpoint>
    <port-component-name>HelloIF</port-component-name>
    <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
    <login-config>
       <auth-method>CLIENT-CERT</auth-method>
    </login-config>
    </webservice-endpoint>
    <exec executable="${exec.appclient}" >
    <env key="VMARGS" value="-Djava.protocol.handler.pkgs=javax.net.ssl -Djavax.net.ssl.keyStore=${keystore} -Djavax.net.ssl.keyStorePassword=${keystore.password} -Djavax.net.ssl.trustStore=${trustStore}" />
    <arg line="${exec.appclient.part2}" />
    <arg line=" -client ${stub.file}"/>
    </exec>

4.7 Securing WebServices using Message Level Security (EJB based WebService endpoint & Servlet Based WebService endpoint)

For securing webservies using message level security at the appserver level, a developer need not add anything  to the runtime xml file or the client program, only step necessary is to enable the default WSS providers, this can be done using the ant target "enable-wss-message-security-provider", this target is  automatically invoked during the sample run. (i.e when the user invoke "ant run" the enable-wss-mesage-security-provider is called automatically)

Note: The default WSS providers protects the webservice by sending digital signature as a part of the SOAP message during request and response processing.  Please notice message-security-config element in domain.xml and sun-acc.xml,  the request-policy, response-policy  elements along with the configuration files wss-server-config.xml / wss-client-config.xml specifies how the default providers should protect the webservices using what mechanisms(username-password /digital signature/ encryption)

From domain.xml
   
          <message-security-config auth-layer="SOAP"  default-client-provider="ClientProvider" default-provider="ServerProvider">
     <provider-config class-name="com.sun.xml.wss.provider.ClientSecurityAuthModule" provider-id="ClientProvider" provider-type="client">
            <request-policy auth-source="content"/>
            <response-policy auth-source="content"/>
            <property name="security.config"  value="${com.sun.aas.instanceRoot}/ config/wss-server-config.xml"/>
          </provider-config>
          <provider-config class-name="com.sun.xml.wss.provider.ServerSecurityAuthModule" provider-id="ServerProvider" provider-type="server">
            <request-policy auth-source="content"/>
            <response-policy auth-source="content"/>
            <property name="security.config" value="${com.sun.aas.instanceRoot}/config/wss-server-config.xml"/>
          </provider-config>
        </message-security-config >

From sun-acc.xml
  <message-security-config auth-layer="SOAP" default-client-provider="ClientProvider">
    <provider-config class-name="com.sun.xml.wss.provider.ClientSecurityAuthModule" provider-id="ClientProvider" provider-type="client">
        <request-policy auth-source="content"/>
         <response-policy auth-source="content"/>
         <property name="security.config" value="${INSTALL_DIR}/lib/appclient/wss-client-config.xml"/>
 </provider-config>
 </message-security-config>

For more information regarding the message-security-config XML elements see the dtds under INSTALL_ROOT/lib/dtds/sun-domain_1_1.dtd and INSTALL_ROOT/lib/dtds/sun-application-client-container_1_1.dtd

5.0 Building from the source


6.0 Configuration Parameters

WebServices security samples uses following configuration parameters from common.properties file under INSTALL_ROOT/samples directory.

 Note: The values shown here are only for example purpose, you should set the correct values for your environment.

7.0 Troubleshooting