Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
XML and Web Services Security
XML and Web Services Security can include two use cases. These use cases include the following:
- Transport-Level Security, is where security is addressed by the transport layer. Adding security in this way is discussed in the following example sections:
- Message-Level Security, is where the security information is contained within the SOAP message, which allows security information to travel along with the message. This model enables message parts to be transported without intermediate nodes seeing or modifying the message. Adding security in this way is discussed in the following section:
Transport-Level Security
Authentication is a process that verifies the identity of a user, device, or other entity in a computer system, usually as a prerequisite to allowing access to resources in a system. There are several ways in which this can happen, the following ways are discussed in this section:
- A user authentication method can be defined for an application in its deployment descriptor. When a user authentication method is specified for an application, the Web container activates the specified authentication mechanism when you attempt to access a protected resource. The options for user authentication methods are discussed in Using Login Authentication. The example application discussed in Example: Basic Authentication with JAX-RPC shows how to add basic authentication to a JAX-RPC application. The example discussed in Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC shows how to add client-certificate, or mutual, authentication to a JAX-RPC application.
- A transport guarantee can be defined for an application in its deployment descriptor. Use this method to run over an SSL-protected session and ensure that all message content is protected for confidentiality. The options for transport guarantees are discussed in Specifying a Secure Connection. An example application that discusses running over an SSL-protected session is discussed in Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC.
When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data.
Secure Socket Layer (SSL) technology allows Web browsers and Web servers to communicate over a secured connection. In this secure connection, the data that is being sent is encrypted before being sent, then decrypted upon receipt and prior to processing. Both the browser and the server encrypt all traffic before sending any data. For more information, see What is Secure Socket Layer Technology?.
Digital certificates are necessary when running HTTP over SSL (HTTPS). The HTTPS service of most Web servers will not run unless a digital certificate has been installed. Use the procedure outlined in Setting Up Digital Certificates to set up a digital certificate that can be used by your Web server to enable SSL.
Example: Basic Authentication with JAX-RPC
In this section, we discuss how to configure JAX-RPC-based Web service applications for HTTP basic authentication. With HTTP basic authentication (
<auth-method>BASIC</auth-method>
), the Web server will authenticate a user by using the user name and password obtained from the Web client. If the topic of authentication is new to you, please refer to the section titled Using Login Authentication.
Note: The instructions in this section apply to the Java WSDP version 1.3.
For this tutorial, we begin with the example application in
<
INSTALL
>/jwstutorial13/examples/jaxrpc/staticstub
and
<
INSTALL
>/jwstutorial13/examples/jaxrpc/helloservice
and add user name/password authentication. The resulting application can be found in the directories<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauth
and<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauthclient
. In general, the following steps are necessary to add basic authentication to a JAX-RPC application. In the example application included with this tutorial, many of these steps have been completed for you and are listed here expressly for the purpose of listing what needs to be done should you wish to create a similar application outside of this tutorial.
- Add the appropriate security elements to the
web.xml
deployment descriptor. For this example, these have been added. Refer to Add Security Elements to the Deployment Descriptor for further description of these elements.- Edit the
build.properties
files. Thebuild.properties
file needs to be modified because the properties in this file are specific to your installation of the Java WSDP and The Java Web Services Tutorial. See Edit the Build Properties for information on which properties need to be set.- Set security properties in the client code. For the example application, this step has been completed. The code for this example is shown in Set Security Properties in the Client Code.
- Build, deploy, and run the Web service (see Building, Deploying, and Running the Example for Basic Authentication). You will use the
Ant
tool to compile and run the example application.Add Security Elements to the Deployment Descriptor
For HTTP basic authentication, the application deployment descriptor,
web.xml
, includes the information on who is authorized to access the application, which URL patterns and HTTP methods are protected, and what type of user authentication method this application uses. This information is added to the deployment descriptor inside<security-constraint>
, <login-config
>, and<security-role>
elements. These security elements are discussed in more detail in Specifying Security Constraints and in the Java Servlet Specification, which can be browsed or downloaded online athttp://java.sun.com/products/servlet/
. Code in bold is added to the deployment descriptor,<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauth/web.xml,
to enable HTTP basic authentication:<?xml version="1.0" ?> <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http:// java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> <display-name>Basic Authentication Security</display-name> <session-config> <session-timeout>60</session-timeout> </session-config><security-constraint> <web-resource-collection> <web-resource-name>SecureHello</web-resource-name> <url-pattern>/hello</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>admin</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> </login-config> <security-role> <role-name>admin</role-name> </security-role>
</web-app>Note that the <r
ole-name
> element specifiesadmin
, a role that has already been specified in the Tomcat user's file. For more information on defining and linking roles, see Setting up Security Roles.Edit the Build Properties
To run the application with basic authentication, we have set up the application so that some of the values are passed to the application from the
build.properties
file, which is located in the<
INSTALL
>/jwstutorial13/examples/common
directory. The following example assumes you are running on Tomcat the. In order to perform basic authentication, the application needs to know your user name and password. The following items need to be set to the real values for your user name, password, and installation. Theusername
andpassword
properties must correspond to a user assigned theadmin
role, which is the user name and password entered during installation or one you've entered after installation, because that is the role to which we gave access in the deployment descriptor. Ifusername
andpassword
variables already exist in the file, change them to the correct values, otherwise, add them.If you're not using Tomcat and its default settings, you should also verify that the
host
andport
properties are set correctly. If you have modified the default host and/or port, you must also modify these settings in the<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauth/SecureHello.wsdl
file.Set Security Properties in the Client Code
The source code for the client is in the
HelloClient.java
file of the<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauthclient/src
directory. For basic authentication, the client code must setusername
andpassword
properties. The username and password properties correspond to theadmin
role, which is the user name and password combination entered during installation and provided in the application deployment descriptor as an authorized role for secure transactions. (See Setting up Security Roles.)The client sets the aforementioned security properties as shown in the code below. The code in bold is the code that had been added from the original version of the
jaxrpc/staticstub
example application.package basicauthclient; import javax.xml.rpc.Stub; public class HelloClient { public static void main(String[] args) {if (args.length !=3) { System.out.println("HelloClient Error: Wrong number of runtime arguments!"); System.exit(1); } String username=args[0]; String password=args[1]; String endpointAddress=args[2]; // print to display for verification purposes System.out.println("username: " + username); System.out.println("password: " + password); System.out.println("Endpoint address = " + endpointAddress);
try { Stub stub = createProxy();stub._setProperty( javax.xml.rpc.Stub.USERNAME_PROPERTY, username); stub._setProperty( javax.xml.rpc.Stub.PASSWORD_PROPERTY, password); stub._setProperty (javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, endpointAddress);
HelloIF hello = (HelloIF)stub; System.out.println(hello.sayHello("Duke (secure)")); } catch (Exception ex) { ex.printStackTrace(); } } private static Stub createProxy() { // Note: MyHelloService_Impl is implementation-specific. return (Stub)(new MyHelloService_Impl().getHelloIFPort()); } }Building, Deploying, and Running the Example for Basic Authentication
To build, deploy, and run the
jaxrpc/basicauth
example using basic authentication, follow these steps:
- Follow the instructions in Edit the Build Properties.
- From a terminal window or command prompt, go to the
<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauth
directory.- Build the JAX-RPC service by entering the following at the terminal window or command prompt in the
/basicauth
directory (this and the following steps that useAnt
assume that you have the executable forAnt
in your path: if not, you will need to provide the fully-qualified path to theAnt
executable). This command runs theAnt
target namedbuild
in thebuild.xml
file.
ant
build
- Start Tomcat.
- Deploy the JAX-RPC service by entering the following at the terminal window or command prompt in the
/basicauth
directory:
ant deploy
- Change to the
<
INSTALL
>/jwstutorial13/examples/jaxrpc/basicauthclient
directory. Build the JAX-RPC client by entering the following at the terminal window or command prompt:
ant
build
- Run the JAX-RPC client by entering the following at the terminal window or command prompt in the
/basicauthclient
directory:
ant
run
The client should display the following output:
Buildfile: build.xml run-secure-client: [java] username: your_name [java] password: your_pwd [java] Endpoint address = http://localhost:8080/secure- jaxrpc/hello [java] Hello Duke (secure) BUILD SUCCESSFUL
Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC
In this section, we discuss how to configure a simple JAX-RPC-based Web service application for client-certificate authentication over HTTP/SSL. Client-certificate authentication (
<auth-method>CLIENT-CERT</auth-method>
) uses HTTP over SSL, in which the server and, optionally, the client authenticate one another with Public Key Certificates. If the topic of authentication is new to you, please refer to the section titled Using Login Authentication.This example application starts with the example application in
<
INSTALL
>/jwstutorial13/examples/jaxrpc/helloservice
and adds both client and server authentication to the example. In SSL certificate-based basic authentication, the server presents its certificate to the client, and the client authenticates to the server by sending its user name and password. This type of authentication is sometimes called server authentication. Mutual authentication adds the dimension of client authentication. For mutual authentication, we need both the client's identity, as contained in a client certificate, and the server's identity, as contained in a server certificate inside a keystore file (keystore.jks
), and we need both of these identities to be contained in a mutual trust-store (cacerts.jks
) where they can be verified.To add mutual authentication to the
<
INSTALL
>/jwstutorial13/examples/jaxrpc/helloservice
example, we need to complete the following steps. In the example application included with this tutorial, many of these steps have been completed for you and are listed here expressly for the purpose of listing what needs to be done should you wish to create a similar application outside of this tutorial.
- Create the appropriate certificates and keystores. For this example, the certificates and keystores are created for a generic
localhost
and are included with the example application. See the section Keystores and Trust-Stores in the Mutual Authentication Example for a discussion of these files. If you are creating a different application, refer to the section Setting Up Digital Certificates for more information on creating the keystores and certificates and importing the client and server identity into the trust-store.- Configure the SSL Connector, if necessary. For this release of Tomcat, the SSL connector needs to be configured before you can run the example application, and the location and password of the server keystore must be specified in the
server.xml
file as well. Read the instructions on how to do this in the section Configuring the SSL Connector for Certificate Authentication.- Edit the
build.properties
files to add the location and password to the trust-store, and other properties, as appropriate. Thebuild.properties
file needs to be modified because the properties in this file are specific to your installation of the Java WSDP and Java WSDP Tutorial. For a discussion of the modifications that need to be made tobuild.properties
, see Modifying the Build Properties.- Set security properties in the client code. For the example application, this step has been completed. For a discussion of the security properties that have been set in
HelloClient
, see Setting Security Properties in the Client Code.- Add the appropriate security elements to the
web.xml
deployment descriptor. For this example, these have been added. The security elements that have been added are discussed in the section Enabling Mutual Authentication over SSL.- Build the client and server files, deploy the server, and run the client (see Build, Deploy, and Run the Mutual Authentication Example). You will use the
Ant
tool to compile and deploy the example application.Keystores and Trust-Stores in the Mutual Authentication Example
In this example, the keystore file
(keystore.jks
) and the trust-store file (cacerts.jks
) have already been created for a genericlocalhost
and are included with the example application in the directory<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth/
. These files were created using the following steps, which are discussed in more detail in Setting Up Digital Certificates.Configuring the SSL Connector for Certificate Authentication
By default, the SSL Connector is not enabled for Tomcat for this release of the Java WSDP. To use the SSL Connector that comes pre-configured for Tomcat, you need to uncomment the section that includes the SSL connector, as discussed in Configuring the SSL Connector. In this same file, you must add the information on the location and password of the server's keystore file. The following code snippet is from the Tomcat Server Configuration file, which is located at
<JWSDP_HOME>
/conf/server.xml
. First, stop the server if it is running. Open this file, remove the comment tags around the SSL Connector if you haven't done so already (highlighted in bold), and add the keystore information as shown in bold below. Be sure to enter the fully-qualified path to the keystore files.<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --> <!-- REMOVE the comment tag on the next line--><!--
<Connector className="org.apache.coyote.tomcat5.CoyoteConnector" port="8443" minProcessors="5" maxProcessors="75" enableLookups="true" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true"> <Factory className= "org.apache.coyote.tomcat5.CoyoteServerSocketFactory"keystoreFile= "<
INSTALL
>/jwstutorial13/examples/ jaxrpc/ mutualauth/keystore.jks" keystorePass="changeit"
clientAuth="false" protocol="TLS" /> </Connector> <!-- REMOVE the comment tag on the line below-->-->
Restart the server, and it will recognize the secure port and keystore.
You might notice the
clientAuth
property in theFactory
section. You would set this totrue
to enable client authentication for all traffic through this server. The different ways of authorizing client authentication are discussed in Enabling Mutual Authentication Over SSL.Modifying the Build Properties
To run the application with mutual authentication, we have set up the application so that some of the values are passed to the application from various
build.properties
file.To run any of the examples, you need to modify the
build.properties
file located in the<INSTALL>/
jwstutorial13/examples/common
directory. This file provides general properties about who you are and where things are located on your computer to theAnt
targets we will run later in this example. In this case, you need to provide the location where the tutorial is installed and your user name and password. Theusername
andpassword
properties must correspond to a user assigned to theadmin
role, which may be the user name and password entered during installation or a user name and password entered at a later time and assigned theadmin
role. If you need more information, see Modifying the Build Properties File.If you're not using Tomcat and its default settings, you should also verify that the
host
andport
properties are set correctly. If you have modified the default host and/or port, you must also modify these settings in the<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauthclient/SecureHello.wsdl
file.For this example, the
build.properties
file in the<INSTALL>/
jwstutorial13/examples/jaxrpc/common
directory has been modified for you. This file provides specific information about the JAX-RPC examples to theAnt
targets we will be running later regarding the location of the keystore and trust-store files and their associated passwords.Make sure that the following properties exist and are correctly defined.
trust.store=${tutorial.home}/examples/jaxrpc/ mutualauth/cacerts.jks trust.store.password=changeit key.store=${tutorial.home}/examples/jaxrpc/mutualauth/ keystore.jks key.store.password=changeitSetting Security Properties in the Client Code
The source code for the client is in the
HelloClient.java
file of the<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauthclient/src
directory. For mutual authentication, the client code must set several security-related properties. These values are passed into the client code when theAnt
build
andrun
tasks are executed.
trustStore
. The value of thetrustStore
property is the fully qualified name of the trust-store file:<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth/cacerts.jks
.trustStorePassword
. ThetrustStorePassword
property is the password of the trust-store. The default value of this password ischangeit
.keyStore
. The value of thekeyStore
property is the fully qualified name of the keystore file:<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth/keystore.jks
.keyStorePassword
. ThekeyStorePassword
property is the password of the keystore. The default value of this password ischangeit
.ENDPOINT_ADDRESS_PROPERTY
. TheendpointAddress
property sets the endpoint address that the stub uses to access the service.The client sets the aforementioned security properties as shown in the code below. The code in bold is the code that had been added from the original version of the
jaxrpc/staticstub
example application.package mutualauthclient; import javax.xml.rpc.Stub; public class HelloClient { public static void main(String[] args) {if (args.length !=5) { System.out.println("HelloClient Error: Need 5 runtime arguments!"); System.exit(1); } String keyStore=args[0]; String keyStorePassword=args[1]; String trustStore=args[2]; String trustStorePassword=args[3]; String endpointAddress=args[4]; // print to display for verification purposes System.out.println("keystore: " + keyStore); System.out.println("keystorePassword: " + keyStorePassword); System.out.println("trustStore: " + trustStore); System.out.println("trustStorePassword: " + trustStorePassword); System.out.println("Endpoint address: " + endpointAddress);
try { Stub stub = createProxy();System.setProperty("javax.net.ssl.keyStore", keyStore); System.setProperty("javax.net.ssl.keyStorePassword", keyStorePassword); System.setProperty("javax.net.ssl.trustStore", trustStore); System.setProperty("javax.net.ssl.trustStorePassword", trustStorePassword); stub._setProperty( javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, endpointAddress);
HelloIF hello = (HelloIF)stub; System.out.println(hello.sayHello("Duke! ( secure!")); } catch (Exception ex) { ex.printStackTrace(); } } private static Stub createProxy() { // Note: MyHelloService_Impl is implementation-specific. return (Stub)(new MySecureHelloService_Impl().getHelloIFPort()); } }Enabling Mutual Authentication over SSL
The two ways of implementing client authentication are discussed in Enabling Mutual Authentication Over SSL. You can set client authentication for all applications (by specifying this in the deployment descriptor for the server) or for just a single application (by specifying this in the deployment descriptor for the application). For this example, we are enabling client authentication for this application only, so we specify the login authentication method in the deployment descriptor,
web.xml
, as beingCLIENT-CERT
.To view the application deployment descriptor, open the
web.xml
file located in the<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth
directory. Security constraints were discussed in Specifying Security Constraints. The following section discusses the parts of the deployment descriptor that add client certification to this example:For more information on
<login-config>
options, read Using Login Authentication.The user authentication method specifies a client-certificate method of authentication in this example. For this authentication to run over SSL, we also need to specify which type of transport guarantee to use. For this example, we have chosen CONFIDENTIAL, which is specified in the web.xml file as follows:
<user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint>For more information on this type of constraint, read Specifying a Secure Connection.
Build, Deploy, and Run the Mutual Authentication Example
To build, deploy, and run the JAX-RPC service example with mutual authentication, follow these steps:
- Follow these steps even if you are running the given example from the
<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth
directory. These steps are specific to your machine and implementation.- Go to the
<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth
directory.- Build the JAX-RPC service by entering the following at the terminal window or command prompt in the
/mutualauth
directory (this and the following steps that useAnt
assume that you have the executable forAnt
in your path: if not, you will need to provide the fully-qualified path to theAnt
executable):
ant build
- Deploy the JAX-RPC service by entering the following at the terminal window or command prompt in the
/mutualauth
directory:
ant deploy
- Change to the directory
<
INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauthclient.
- Build the JAX-RPC client by entering the following at the terminal window or command prompt:
ant build
ant run
The client should display the following output:
Buildfile: build.xml
run-mutualauth-client:
[java] keyStore: <INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth/keystore.jks
[java] keyStorePassword: changeit
[java] trustStore: <INSTALL
>/jwstutorial13/examples/jaxrpc/mutualauth/cacerts.jks
[java] trustStorePassword: changeit
[java] endpointAddress = https://localhost:8443/secure-mutualauth/hello
[java] Hello Duke (secure)
BUILD SUCCESSFULFor information on verifying that mutual authentication is running, see Verifying Mutual Authentication is Running.
Message-Level Security
In message-level security, security information is contained within the SOAP message, which allows security information to travel along with the message. For example, a portion of the message may be signed by a sender and encrypted for a particular receiver. When the message is sent from the initial sender, it may pass through intermediate nodes before reaching its intended receiver. In this scenario, the encrypted portions continue to be opaque to any intermediate nodes and can only be decrypted by the intended receiver. For this reason, message-level security is also sometimes referred to as end-to-end security.
This version of XML and Web Services Security provides a framework with which a JAX-RPC application developer will be able to sign and verify SOAP messages. This implementation of XML and Web Services Security attempts to implement portions of the OASIS Web Services Security Working Draft, which may be viewed at the W3C Web site,
http://www.w3.org/Signature/
.
Note: Currently, the Java standard for XML Digital Signatures is undergoing definition under the Java Community Process. This Java standard is JSR 105-XML Digital Signature APIs, which you can read at
http://www.jcp.org/en/jsr/detail?id=105
. The security solution provided in this release of the Java WSDP is based on nonstandard APIs, which are subject to change with new revisions of the technology. As standards are defined in the Web Services Security space, these nonstandard APIs will be replaced with standards-based APIs.
This release of the Java WSDP includes samples that illustrate how a JAX-RPC developer can use the XML and Web Services Security framework, as well as documentation for the nonstandard APIs. The example applications can be found in the
<
JWSDP_HOME
>/xws-security/samples/
directory. The examples start from the<
INSTALL
>/jwstutorial13/examples/jaxrpc/helloservice/
example shipped with the Java WSDP Tutorial and add XML Digital Signature. Instructions for running the examples are included in theREADME.txt
files included with each sample.In this release, the default trust-store bundled with the Java WSDP is the only certificate that will be accepted for signing and verifying the requests and responses. This trust-store contains both the client and server certificates.
The following sample applications are included:
- Sample application
dump
prints out both the client and server request and response SOAP messages.- Sample application
sign
begins with the JAX-RPChelloservice
sample and configures it so that the response is signed by the server and verified by the client. The request message is not changed.- Sample application
sign2
starts with the JAX-RPChelloservice
sample. In this example, the client signs the request, the message is dumped out, the message travels over the network, the server verifies the signature, the business method is called, the server signs the response, the message travels back over the network, and the client verifies the response. This sample also demonstrates how the calling client identity can be retrieved in the business method.- API documentation for the nonstandard APIs can be viewed at
<
JWSDP_HOME
>/xws-security/docs/api/index.html
.Signing and Verifying a SOAP Message describes how to use the Java APIs to digitally sign a SOAP message.
Signing and Verifying a SOAP Message
This section discusses using XML and Web Services Security (XWS-Security) to sign and verify SOAP request and response messages. Starting with an unsecured JAX-RPC client, the call gets access to a client proxy object, in this case a static stub. To secure this client, a
ClientHelper
must be created and bound to that proxy object. There can be several kinds ofClientHelpers
depending on the kind of credentials the client uses. AClientHelper
has no credentials associated with it, while aCertificateClientHelper
carries X509 certificate credentials.Use the
createFor()
static factory method to create an instance of aClientHelper
. Then configure theClientHelper
for the actions you want to take. See the example code in Configuring the Server to Verify a Request Received from the Client and to Sign Responses Sent to the Client for an example of how to configure the proxy to sign requests and verify responses, and then call the business method as usual:
proxy.someBusinessMethod(arg1, arg2);
On the server side, there is only one kind of credential, an X509 Certificate credential, which means that there is only one
ServerHelper
class. As with the client, aServerHelper
instance needs to be created and this must be done before a business method is called. Use theinit(Object)
method of theServiceLifecycle
interface to do this. The unsecured JAX-RPC endpoint must implementServiceLifecycle
and add aninit(Object context)
method, as shown in the example code in Configuring the Server to Verify a Request Received from the Client and to Sign Responses Sent to the Client.In this release, only programmatic security is supported. None of the security information is added to the deployment descriptors.
Configuring the Server to Sign a Server Response
To configure a server to sign all responses to a client, you add a
ServerHelper
to your server implementation. In the example at<
JWSDP_HOME
>/xws-security/samples/sign/server/src/sign/HelloImpl.java
, when a client invokes an RPC service, the server signs the response with the default credential. The code that does this looks like this:public void init(Object context) throws ServiceException { // Configure this endpoint to sign the response with the // server's credentials. ServerHelper.createFor(context).addSignResponse(); }The
createFor(context)
method creates aServerHelper
instance and binds it to a servlet endpoint implementation. This method will attempt to initialize the server credentials and client credential databases, but will not throw any exceptions upon failure. The server credentials use a JAAS entry name ofXwsSecurityServerKey
and the client databases useXwsSecurityClientCertificateDatabase
.To read the API documentation for
ServerHelper
, open<
JWSDP_HOME
>/xws-security/docs/api/index.html
, and click the link toServerHelper.
Configuring a Static Client to Verify Server Responses
To configure a static client to verify server responses, you add a
ClientHelper
, a utility API used to add security to a proxy by adding a handler to verify all of the responses from the server. AClientHelper
has no client credential but may be associated with an optional server certificate credential. The following code (in bold), from<
JWSDP_HOME
>/xws-security/samples/sign/client/src/sign/StaticHelloClient.java
, shows one example of configuring a static client to verify server responses:public class StaticHelloClient { public static void main(String[] args) throws Exception { Remote proxy = (Remote) createProxy(); // Create a ClientHelper to verify the response from // the server
ClientHelper.createFor(proxy).addVerifyResponse();
HelloIF hello = (HelloIF) proxy; System.out.println(hello.sayHello("to Duke!")); } }
The line of code in bold gets the proxy and configures the helper for the proxy using the
ClientHelper
API. TheaddVerifyResponse
method adds an action to verify a response message from the server and returns this object in support of method-call chaining. ThecreateFor
method attempts to bind the Helper to the proxy. The server credentials will be initialized using a JAAS default entry name ofXwsSecurityServerCertificate
. If a server credential could not be located, no exception is thrown because it is possible to call methods on this class that do not require server credentials.To read the API documentation for
ClientHelper
, open<
JWSDP_HOME
>/xws-security/docs/api/index.html
, and click the link toClientHelper.
Configuring the Server to Verify a Request Received from the Client and to Sign Responses Sent to the Client
In Configuring the Server to Sign a Server Response, configuring a server to sign responses to the client was discussed. This section adds to that example by verifying that the request is from a valid client before sending a response. The
sign2
sample application includes server-side source code that illustrates how to verify a request received from the client in addition to showing how to sign responses sent to the client. This sample also shows you how to extract information about the client principal with which the request was signed. The following code snippet demonstrates one way to configure the server as described above (from<
JWSDP_HOME
>/xws-security/samples/sign2/server/src/sign2/HelloImpl.java
):public class HelloImpl implements HelloIF, ServiceLifecycle { private static final String prompt = "Hello "; private ServerHelper sh; public String sayHello(String s) { // The following illustrates how to access the Principal // associated with the client signature in a business // method. A Subject containing the public credentials // can also be accessed, but it is not shown here. return prompt + s + " and also to " + sh.getClientPrincipal(); } ... public void init(Object context) throws ServiceException { // Configure this endpoint to sign the response with the // server's credentials. Also, save the ServerHelper // instance in a field so we can access it later from a // business method. sh = ServerHelper.createFor(context); sh.addCertificateVerifyRequest().addSignResponse(); } }When you get a request that was signed by the client, use the
getClientPrincipal
method to find out who signed the request. Use theaddCertificateVerifyRequest
method to verify a request message from the client. The clientSubject
andPrincipal
will be set to the client identity if verification is successful.Of course, for this scenario to work, you need to add a sign request to your client code as well. The client source code illustrates how to sign a request sent to the server and to verify the response that is received. In this example, we use the
CertificateClientHelper
API to sign the request from the client. The server code, above, signs the response, and the client verifies the response. The CertificateClientHelper class is used to help set up client-side security using X509 Certificate credentials. ACertificateClientHelper
is typically associated with a client credential and may be associated with a server certificate credential. The following code snippet is from the sample application at<
JWSDP_HOME
>/xws-security/samples/sign2/client/src/sign2/StaticHelloClient.java
:// Create a CertificateClientHelper for a client-side // stub/proxy CertificateClientHelper cch = CertificateClientHelper.createFor(proxy); // Sign the request and then dump the message for debugging cch.addSignRequest().addDumpRequest(); // Verify the response which was signed by the server cch.addVerifyResponse(); // Call the business method HelloIF hello = (HelloIF) proxy; System.out.println(hello.sayHello("to Duke!"));The
addSignRequest
method adds an action to sign a request message to the server. IfgetClientSubject()
returns null, then this method will throw aServiceException
because a client private key is needed to sign a request. TheaddDumpRequest
method is used to dump a stack trace to the console for debugging purposes.To read the API documentation for
ClientCertificateHelper
, open<
JWSDP_HOME
>/xws-security/docs/api/index.html
, and click on the link toClientCertificateHelper.
Further Discussion of XML Digital Signatures
With this implementation of the XML Digital Signature technology, you can verify the integrity of the message, but anyone who picks up the XML document will be able to see its contents. To add authentication to this example, you can use DSig in combination with SSL technology to encrypt the actual contents of the document. Adding certificate-based authentication to a JAX-RPC application is discussed in Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.