Java TM Web Services Security Sample Application 1.0 |
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.
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.![]()
![]()
WebServices can be secured at various levels
- 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)
- 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
- 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.)
- 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).
- 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
- 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.
- 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.
![]()
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
- The application server is running (see How to start server )
- This sample assumes that the webserver is running on default port 8080 if you change the port please change the wsdl files and recompile the samples, use the commands listed in section 5.0 to build, deploy, run and undeploy samples.
- This sample uses the same WebService name(HelloWorld) and WebService Ports, for showing only the differences necessary for protecting WebServices using various mechanisms. This can cause name already in use error and deployment failures. So make sure you undeploy the applications(using "asant undeploy" command) at the end of easy sample run.
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
- Protect the Servlet, this is done by adding security-constraint, login-config and security-role elements to web.xml, these elements protect the servlet to be accesible only by the user who belongs to a role asadmin
<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>
- Add security-role-mapping in sun-application.xml, this creates a principal to role mapping
<security-role-mapping>
<role-name>asadmin</role-name>
<principal-name>admin</principal-name>
</security-role-mapping>
- Pass user name password to the client runtime, this is done through the "run" target in build.xml
<exec executable="${exec.appclient}" >
<arg line="${exec.appclient.part2}" />
<arg line=" -client ${stub.file}"/>
<arg line="${admin.user} ${admin.password}" />
</exec>
- Pass the username and password obtained through client runtime to WebServices Stub, this is used by the runtime for authentication, this is done in the HelloClient.java as shown below
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.
- Protect the Servlet, this is done by adding security-constraint, login-config and security-role elements to web.xml, these elements protect the servlet to be accesible only by the user who belongs to a role asadmin
<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>
- Add security-role-mapping in sun-application.xml, this creates a principal to role mapping
<security-role-mapping>
<role-name>asadmin</role-name>
<principal-name>admin</principal-name>
</security-role-mapping>
- Pass user name password and the trust store to the client runtime, this is done through the "run" target in build.xml. Client uses trust store to verify server's certificate.
<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>
- Pass the username and password obtained from client runtime to WebServices Stub, this is used by the runtime for authentication, this is done in the HelloClient.java as shown below
helloStub._setProperty("javax.xml.rpc.security.auth.username", args[0]); helloStub._setProperty("javax.xml.rpc.security.auth.password", args[1]);
4.3 Securing WebServices for clientCert (Servlet based WebService endpoint)
The main differences between basicSSL and clientCert mechanisms are
In a servlet based WebService endpoint, clientCert security mechanism is configured by performing the following steps.
- There is no user-data-constraint element in the security-constraint.
- 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)
- Both client keystore and trust stores are specified in the client runtime.
- User name and password are not passed to the client runtime or to the Stubs.
- Authentication is done through both client and server certificates.
- Protect the Servlet, this is done by adding security-constraint, login-config and security-role elements to web.xml, these elements make sure that the servlet is transport protected.
<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>
- Specify client keystore and trust store to the client runtime, this is done through the "run" target in build.xml. Client sends the client certificate that is specified in client keystore while establishing SSL connection, and the server also sends its certficate to the client, both client and server verifies the validity of the certificates by using the trust store.
- Note: Just to keep this example simple, both client and server uses the same keystore, it is possible to have two different keystores one for client and the other for the server.
<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.
- Protect the EJB by adding method-permission element in ejb-jar.xml, this ensures only allowed users can access the specified method.
<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>
- Add ior-security-config elements in sun-ejb-jar.xml, this specifies various IOR security configuration parameters such as (transport protection, authentication constraints and caller propagation). The following configuration protects the ejb for user-name password based authentication
<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>
- Add security-role-mapping in sun-application.xml, this creates a principal-to-role mapping
<security-role-mapping>
<role-name>asadmin</role-name>
<principal-name>admin</principal-name>
</security-role-mapping>
- Pass user name password to the client runtime, this is done through the "run" target in build.xml
<exec executable="${exec.appclient}" >
<arg line="${exec.appclient.part2}" />
<arg line=" -client ${stub.file}"/>
<arg line="${admin.user} ${admin.password}" />
</exec>
- Pass the username and password obtained from client runtime to WebServices Stub, this is used by the runtime for authentication, this is done in the HelloClient.java as shown below
helloStub._setProperty("javax.xml.rpc.security.auth.username", args[0]); helloStub._setProperty("javax.xml.rpc.security.auth.password", args[1]);
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.
- Protect the EJB by adding method-permission element in ejb-jar.xml, this ensures only allowed users can access the specified method.
<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>
- Add ior-security-config elements in sun-ejb-jar.xml, this specifies various IOR security configuration parameters such as (transport protection, authentication constraints and caller propagation). The following configuration protects the ejb for user-name password based authentication and SSL at the transport layer.
<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>
- Add security-role-mapping in sun-application.xml, this creates a principal-to-role mapping
<security-role-mapping>
<role-name>asadmin</role-name>
<principal-name>admin</principal-name>
</security-role-mapping>
- Pass user name password and the trust store to the client runtime, this is done through the "run" target in build.xml. Client uses trust store to verify server's certificate.
<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>
- Pass the username and password obtained from client runtime to WebServices Stub, this is used by the runtime for authentication, this is done in the HelloClient.java as shown below
helloStub._setProperty("javax.xml.rpc.security.auth.username", args[0]); helloStub._setProperty("javax.xml.rpc.security.auth.password", args[1]);
4.6 Securing WebServices for clientCert (EJB based WebService endpoint)
The main differences between basicSSL and clientCert mechanisms are
- There is no method-permission element in ejb-jar.xml.
- 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)
- Both client keystore and trust stores are specified in the client runtime.
- User name and password are not passed to the client runtime or to the Stubs.
- Authentication is done through both client and server certificates.
In a EJB based WebServices end point, clientCert is configured by performing the following steps.
- Add ior-security-config elements in sun-ejb-jar.xml, this specifies IOR security configuration parameters such as (transport protection, authentication constraints and caller propagation). The following configuration protects the ejb at the transport layer(SSL). Note: the establish-trust-inclient element is set to the value required
<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>
- Specify clent keystore and trust store to the client runtime, this is done through the "run" target in build.xml. Client sends the client certificate that is specified in client keystore while establishing SSL connection, and the server also sends its certficate to the client, both client and server verifies the validity of the certificates by using the trust store.
- Note: Just to keep this example simple, both client and server uses the same keystore, it is possible to have two different keystores one for client and the other for the server.
<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
- Commands to compile, deploy, run and undeploy, Go to the leaf level directory and run the following command (for example INSTALL_ROOT/samples/webservices/security/ejb/apps/basicAuth directory)
- To compile samples:
- asant
- To deploy samples :
- asant deploy
- To run samples :
- asant run
- To undeploy samples:
- asant undeploy
- Note: For running each sample you can issue the following commands from their leaf level directory in succession, this will deploy the sample, run the sample and undeploy the sample.
- asant deploy
- asant run
- asant undeploy
6.0 Configuration Parameters
WebServices security samples uses following configuration parameters from common.properties file under INSTALL_ROOT/samples directory.
- Admin user name used in all authentication mechanisms
- admin.user=admin
- Admin password used in all authentication mechanisms
- admin.password=adminadmin
- Client keystore, this contains the client certificate. Note: for sake of simplicity client and server uses the same keystore
- keystore =/sun/appserver8/domains/domain1/config/keystore.jks
- Client keystore password this will be used by the runtime to open the keystore and read certificates from keystore.jks
- keystore.password=changeit
Note: The values shown here are only for example purpose, you should set the correct values for your environment.
- TrustStore, this contains the list of trusted certificate both client and server uses this to verify the validity of the client's and server's identity
- trustStore =/sun/appserver8/domains/domain1/config/cacerts.jks
7.0 Troubleshooting
- This sample assumes that the webserver is running in the default port 8080, if you install your appserver in non-default port, you should recompile the samples, use the commands listed in section 5.0 to build, deploy, run and undeploy samples.
- This sample uses the same WebService name(HelloWorld) and WebService Ports, for showing only the differences necessary for protecting WebServices using various mechanisms. This can cause name already in use error and deployment failures. So make sure you undeploy the applications(using "asant undeploy" command) at the end of easy sample run.