Section 2.

Introduction to message-level security

Transport-level security (e.g. HTTPS) is a point-to-point security model where the channel is protected between two parties. However, many times the service consumer and service provider are separated by intermediaries (e.g. an Enterprise Service Bus). In situations like these, message-level security can provide an end-to-end security solution. Figure 1 depicts how message-level security can provide an end-to-end security solution even if intermediaries are between the consumer and provider. The secret is that with messagelevel security, you can encrypt the message using the public key of the final destination. In this way, only the intended receiver can decrypt the message. Additionally, by encrypting the message and storing the encrypted data into the message, you can store the message on the file system for asynchronous communication and later decrypt it when the receiver is available. These are just a few of the reasons that message level security is often being applied to secure Web services. Figure 1. Comparison of transport level security and message level security (see enlarged Figure 1)

Web Services Security (WS-Security) is an OASIS standard to describe how to implement message-level security with Web services. Specifically, WS-Security describes how you can add confidentiality (e.g. encryption), integrity (e.g. digital signatures), and authentication (e.g. username and password) to a SOAP message. In most cases, XML encryption and XML signatures are the mechanisms for securing the message; WS-Security describes how to use these technologies with Web services to provide message-level security as well as providing a framework for propagating security identities. Figure 2 provides an example of how message-level security looks in a SOAP message. In this tutorial, you learn how to build SOAP messages that get encrypted and signed to provide messages like the one shown in Figure 2. Figure 2. Example of message-level security of a SOAP message (see enlarged Figure

2)

Section 3. Creating and consuming JAX-WS Web services

In this section, you create a simple HelloWorld Web service using a JAX-WS annotation and the Rational Application Developer tooling. Then you use the Rational Application Developer tooling to generate a proxy client to invoke the Web service. Finally, you test your service provider (i.e. Web service) running on the WebSphere Test Environment (WTE) that comes packaged with Rational Application Developer. In your testing, you examine the SOAP messages (i.e. request and response) as they appear on the network.

Creating a JAX-WS Service Provider

In this tutorial, you will use a dynamic Web project to contain the Web service. Start by creating a dynamic Web project and a plain old Java object (POJO) for your service provider as shown in the following steps: 1. Start Rational Application Developer 7.5.2. Click File > New > Dynamic Web Project, then enter HelloWorldProject as the project name, as shown in Figure 3.

Figure 3. Create a dynamic Web project

2. Accept the defaults for the other fields, then click the Finish button. Choose No if
prompted to change to the Web perspective. For this tutorial, you will use the Java EE perspective. 3. Select the HelloWorldProject project in the project explorer view. Right-click and select New > Class, which brings up a Java Class wizard as shown in Figure 4.

Figure 4. Create new Java class wizard

4. Enter com.ibm.dwexample for the package name and HelloWorldProvider as

the class name , and click the Finishbutton.

5. Copy the code from Listing 1 into the HelloWorldProvider.java file and save the
file. Listing 1. HelloWorldProvider.java
package com.ibm.dwexample; import javax.jws.WebService; @WebService public class HelloWorldProvider { public String sayHello(String msg) { System.out.println("[helloworld provider] Hello " + msg); return "Hello " + msg; }

Thats it! A simple POJO with the @WebService annotation is all that is necessary to create a JAX-WS Web service. Now that you have created a Web service, you can use Rational Application Developer to deploy your service onto the WebSphere Test Environment (WTE). To deploy your service: 1. Select the HelloWorldProvider.java file that contains the code from Listing 1. Rightclick and choose Run As > Run on Server, which displays the Run On Server wizard in Figure 5. Figure 5. Run On Server wizard

2. Select the Choose an existing server radio button, and then select WebSphere
Application Server V7.0 at localhost. If you do not have a WebSphere Application Server V7 server defined, you can define a new one by selecting Manually define a new server followed by expanding the IBM folder and selecting the WebSphere Application Server v7.0 server. 3. Click the Finish button to deploy and start the Web service on WebSphere Application Server.

At this point, you have created a simple JAX-WS Web service, deployed it to WTE, and started the service. Next well create a JAX-WS client that can invoke the running Web service. Back to top

Creating a JAX-WS service consumer

Rational Application Developer V7.5.2 provides a wizard for generating a client from a JAXWS Web service. In this tutorial, you use a standalone Java client as your service consumer. Therefore, you begin by creating a simple Java project that will contain your JAX-WS client proxy as well as your client code that uses the generated client proxy. To create a Java project: 1. Using Rational Application Developer select File > New > Other. Locate the Java Project wizard and click Next. 2. In the New Java Project wizard, enter HelloWorldConsumer as the project name and click Finish as shown in Figure 6. If prompted to switch to the Java perspective, choose No to stay in the Java EE perspective.

Figure 6. New Java Project wizard

Now that you have a Java project to hold the JAX-WS proxy classes that are generated by Rational Application Developer, you can use Rational Application Developer to generate the client proxy classes. 3. Expand the Services folder of the HelloWorldProject Web project. Right-click the{http://dwexample.ibm.com/}HelloWorldProviderService service and choose Generate > Client as shown in Figure 7.

Figure 7. Generate the Web service client

4. Ensure the Web service runtime value in the configuration section is set to IBM
WebSphere JAX-WS, and Java Proxyis selected as the client type. 5. Click the Client project: link to change the client project to use the standalone Java project you created above, as shown in Figure 8. Figure 8. Web Service Client wizard

6. Choose HelloWorldConsumer as the client project for the generated Java proxy,
and then click OK as shown in Figure 9. Figure 9. Specify the Client project for proxy

7. Click the Next button and enter com.ibm.dwexample.clientproxy as the target

package of the Web service client. Ensure the Generate portable client checkbox is selected, as shown in Figure 10. It is usually a good idea to segregate the generated code from your client code by using a different package name for the proxy code as shown in this step.

Figure 10. Web Service Client Configuration wizard

8. Click the Finish button to generate the client proxy code, which will look like Figure
11.

Figure 11. Generated client proxy classes

Rational Application Developer uses the WSDL of the service provider to auto-generate Java classes that can invoke the service provider Web service. Figure 11 shows the classes that get generated for you. Using the generated proxy classes, you do not have to worry about SOAP message building, XML parsing, or any other low-level programming constructs the generated classes do this for you. All you need to do is instantiate the client proxy and invoke methods you want to be sent to the Web service. Therefore, next you will create a simple Java test client that instantiates the generated client proxy in order to invoke the service provider. To create a Java test client: 1. Right-click the HelloWorldConsumer project and choose New > Class. 2. Enter com.ibm.dwexample as the package for the client and ClientTest as the Java class name as shown in Figure 12. Note that you segregate your client code from the generated proxy client by using a different Java package name.

Figure 12. New Java Class wizard

3. Click the Finish button. Copy the code from Listing 2 into the ClientTest.java file
and save the file. Listing 2. ClientTest.java
1 package com.ibm.dwexample; 2 import com.ibm.dwexample.clientproxy.HelloWorldProvider; 3 import com.ibm.dwexample.clientproxy.HelloWorldProviderService; 4 public class ClientTest { 5 6 7 8 public static void main(String[] args) { try { HelloWorldProviderService srv = new HelloWorldProviderService(); HelloWorldProvider port = srv.getHelloWorldProviderPort();

9 String resp = port.sayHello("World"); 10 System.out.println("[response] " + resp); 11 } catch(Exception e) { 12 e.printStackTrace(); 13 } 14 } 15 }

In Listing 2, line 7 demonstrates how you instantiate the client proxy service that Rational Application Developer generated for you. Then in line 8, you use the generated interface (i.e. HelloWorldProvider) to get a handle to the Web service port. Finally you use the port object to invoke the sayHello() method which will make a remote call to the Web service provider. The invocation of port.sayHello(World)sends a SOAP request message to the listening Web service provider shown in Listing 1. The service provider then sends a SOAP response message back to the client. Lets examine what these SOAP request and response messages look like via the built-in TCP/IP Monitor view provided by Rational Application Developer. Back to top

Test and verify the consumer and provider

TCPMON is also available with the WebSphere installation. You can use the following command to invoke it: java cp com.ibm.ws.webservices.thinclient_7.0.0.jar com.ibm.ws.webservices.engine.utils.tcpmon After you have the server-side and client-side up and running, it is generally a good idea to test and verify things. Rational Application Developer provides a TCP/IP Monitor view to display the SOAP message as it is transferred from the client to the server and back. To use this view, we need to configure the TCP/IP Monitor to listen on an unused TCP/IP port, and then update your client proxy code to point to this TCP/IP port. The following section demonstrates how to do this. 1. In Rational Application Developer, select Window > Show View > Other. Then locate the TCP/IP Monitor view in theDebug folder and click OK. 2. Right-click in the first entry box and choose Properties as shown in Figure 13. Figure 13. TCP/IP Monitor view

3. Click the Add button to configure a new monitor to intercept the Web service request
and response in order to display the SOAP message. 4. Enter an unused TCP port for the Local monitoring port field. (e.g. 9081)

5. Enter localhost for the Host Name field. 6. Enter the TCP port for the Web service provider (check the WSDL in
the HelloWorldConsumer project). (e.g. 9080). You should have values similar to Figure 14: Figure 14. New Monitor settings

7. Click the OK button. 8. Now select your newly defined TCP/IP Monitor and click the Start button as shown in
Figure 15: Figure 15. Start TCP/IP Monitor

Now that the TCP/IP Monitor is running and listening for Web service calls, you need to change your client proxy to connect to the listening port of the TCP/IP monitor instead of connecting directly to the service provider. You can accomplish this by

changing the port number in the WSDL that was saved locally to the client project as a result of clicking the Generate portable client checkbox in Figure 10. 9. Right-click the HelloWorldProviderService.wsdl file located in the HelloWorldConsumer project under the src > META-INF > wsdl folder path and choose Open With > WSDL Editor. 10. Change the port number to match the TCP/IP Monitor listening port (e.g. 9081) as shown in Figure 16, then save and close the WSDL file. Figure 16. WSDL Editor (see enlarged Figure 16)

11. Right-click the ClientTest.java file and choose Run As > Java Application. The
results should appear in the TCP/IP Monitor view as shown in Figure 17. Figure 17. ClientTest results (see enlarged Figure 71)

At this point, you have developed a JAX-WS Web service provider (i.e. server-side) and a JAX-WS Web service consumer (i.e. client-side) and demonstrated the results of the consumer invoking the provider. In the next section, you configure the policy sets to add message-level security to your little HelloWorld example, and once again view the results in the TCP/IP Monitor view to verify that the SOAP message is being passed securely.

Section 4. Policy sets

Policy sets provide a declarative way to define qualities of service (QoS) for Web services. This simplifies the management of multiple Web services as policy sets can be reused across them. Lets discuss the differences in policy set terminology: Policy A policy describes a configuration that defines qualities of service (QoS) for Web services. Examples include WS-Security and WS-Addressing. Policy sets A policy set is a collection of policies.

Policy set attachment In order to apply policy sets to Web services, they need to be attached. Bindings Policy sets are meant to be reused across Web services and thus do not contain environment specific settings such as key stores or passwords. Instead, a binding contains these environment specific values.

Figure 18. Example of policy sets (see enlarged Figure 18)

WebSphere Application Server V7 comes prepackaged with 18 policy sets (see Figure 18) to simplify getting started. They are production-level policy sets that you can begin using immediately. WebSphere Application Server V7 also comes with 4 sample bindings, but these are for demonstration purposes only. For production Web services, you should customize the policy set bindings as shown in this tutorial. Rational Application Developer 7.5.2 also comes prepackaged with a set of policy sets. Rational Application Developer 7.5.2 fully supports configuration of the client-side bindings required for policy sets. However, you must configure server-side policy set bindings from the WebSphere Application Server V7 server. WebSphere Application Server V7 does support exporting policy sets and policy set bindings such that you can import them into Rational Application Developer 7.5.2. After importing into Rational Application Developer, you can attach the policy sets and policy set bindings to the service provider (i.e. server), as well as the service consumer (i.e. client), using the wizards in Rational Application Developer.

Setting up asymmetric keys

Public-key cryptography, also known as asymmetric cryptography, is a form of cryptography in which the key used to encrypt a message differs from the key used to decrypt it. In public key cryptography, a user has a pair of cryptographic keysa public key and a private key. The private key is kept secret, while the public key may be widely distributed. Incoming messages would have been encrypted with the recipient's public key and can only be decrypted with his corresponding private key. The keys are related mathematically, but the private key cannot be practically derived from the public key. (http://en.wikipedia.org/wiki/Public-key_cryptography)

To secure your Web services, you can use asymmetric keys. In this section, you learn how to create a set of cryptographic keys that you then use to secure your Web service. Before you get started, it may be helpful to review the following terminology: Public key The key that is used by others to encrypt data for you. Private key The key that matches your public key and is used to decrypt data that others have encrypted with your public key. This key should not be shared with others. Certificate authority For others to trust that your public key really belongs to you, you normally request a CA (e.g. Verisign, GeoTrust, GoDaddy) to sign your key. Since others do the same thing, you can trust others by the CA vouching for you and them. Digital certificate To share your public key with others and for them to trust that you are who you say you are, you create a digital certificate which contains your public key along with your identity information (e.g. your name) and send this digital document to a CA to sign for you. Key store A place to store your keys. Also called a key ring. Signer certificate After your digital certificate has been signed by a CA, it becomes a signer certificate. Digital certificate, public key certificate, and signer certificate are often used synonymously. Back to top

Creating service provider keys

There are a number of tools for creating public key/private key pairs, but for this tutorial you use the keytool command provided by the Java Development Kit (JDK), since it will be available with standalone clients as well as with WebSphere Application Server. First, you create the server-side keys that will be used by your service provider (i.e. serverside) running on WebSphere Application Server V7. Then you create the client-side keys for your service consumer running as a standalone client from Rational Application Developer V7.5.2. We purposely separate the server-side keys from the client-side keys to delineate the differences and to mimic the more likely production environment where the consumer and provider are often distributed on different physical hardware. In other words, the private key stays with the owner and should not be distributed. The first thing you need to do is create a key store to hold your public and private keys. This can be accomplished with the following keytool command: 1. In Microsoft Windows, select Start > Run, then enter cmd in the Open field of the dialog box and click OK. 2. In the Command Prompt window, change directories to where WebSphere Application Server V7 is installed. (e.g. cd c:\Program Files\IBM\SDP\runtimes\base_v7) 3. Now run the following keytool command:
java\bin\keytool.exe -genkey v -alias server1 -keyalg RSA -keystore helloServerKeys.jks -storepass f00bar -dname "cn=server1,O=IBM,C=US" -keypass passw0rd

This command generates a public key and private key pair that will be accessed via the server1 alias. Additionally, this command self signs the public key. Both private and public keys are stored in the helloServerKeys.jks file, which is password protected. 4. Next, you need to export your server1 certificate to be imported into your client-side key ring later on, with the followingkeytool command:
java\bin\keytool.exe export -v -alias server1 file c:\temp\server1.cert rfc -keystore helloServerKeys.jks storepass f00bar

For someone (or some computer) to encrypt messages for you, they need your public key. Then you can decrypt the message using your private key. However, you must somehow extract your public key from your key ring into some format and send it to the party with which you wish to securely communicate. The export argument of the keytool does just that, and in the above command saves the public key into an X509 digital certificate format and stores it in the text file c:\temp\server1.cert. This public key certificate will then be imported into the service consumers (i.e. client-side) key store such that the service consumer will know how to encrypt messages for the service provider. Figure 19 shows the commands used for creating the service provider keys: Figure 19. Service Provider Key setup

Back to top

Creating service consumer keys

Now that you have created the server-side keys, next you create a client-side key store. Note that this is a completely different set of keys and has no relationship to the server-side keys. Only when you exchange public keys with each key store is a trust relationship established. In fact, our keys use a different organization name (i.e. server1 at IBM and myclient at ACME) to demonstrate that your keys can be from completely different organizations and that the client and server need not have keys created by one certificate authority. As with the server-side keys, you can use the keytool command to create the client-side key ring. Note that you will use thekeytool command that comes with Rational Application Developer V7.5.2 and not the WebSphere Application Server keytoolas evident by the different directories from which you run this command: 1. In Microsoft Windows, select Start > Run, then enter cmd in the Open field of the dialog box and click OK. 2. In the Command Prompt window, change directories to where Rational Application Developer 7.5.2 is installed. (e.g. cd c:\Program Files\IBM\SDP) 3. Now run the following keytool command:
jdk\bin\keytool.exe -genkey v -alias myclient -keyalg RSA -keystore myclientKeys.jks -storepass g00ber -dname "cn=myclient,O=ACME,C=US" -keypass p@ssword

Just as the service provider used this command to generate a public key and private key pair, we now use the same command to create the service consumers key ring with a corresponding set of public key/private key that is accessed via

the myclient alias. Likewise with the service provider keys, this command creates a self-signed public certificate that contains the public key. However, note that the service consumer (i.e. client-side) keys are stored in themyclientKeys.jks file. 4. To build that trust level between the service provider and service consumer, you need to export the client certificate to be imported into the service providers key store. This is done with the following keytool command:
jdk\bin\keytool.exe export -v -alias myclient file c:\temp\myclient.cert rfc -keystore myclientKeys.jks storepass g00ber

This command imports the public key certificate into the service providers (i.e. server-side) key store so that the service provider will know how to encrypt messages for the consumer. 5. Next you import the server-side public key into the client-side keys using the following keytool command:
jdk\bin\keytool.exe import -v noprompt -alias server1 file c:\temp\server1.cert -keystore myclientKeys.jks storepass g00ber

Recall above that you exported the public key of the server1 alias, which is the key pair that is associated with your service provider. Therefore, you need to import this public key into the client-side key store (i.e myclientKeys.jks). Then, when the service consumer (i.e. client-side) wants to encrypt a message for the service provider, the WS-Security configuration associated with the client will specify the server1 alias public key in the clients key store. Figure 20 shows all of the commands listed above required to create the client-side keys: Figure 20. Creating client-side keys with keytool

Back to top

Importing service consumer keys

Recall during the service provider key creation, you had not yet created the service consumer keys with which to export and import into the service providers key ring. Now that you have created the client-side keys and certificates and exported the public key to be used by the service consumer, you can now import this key into the service provider key ring. 1. The following keytool command lets you import the public key into the key ring:

java\bin\keytool.exe import -v noprompt -alias myclient file c:\temp\myclient.cert -keystore helloServerKeys.jks storepass f00bar

Make sure you run this command from the WebSphere Application Server V7 directory (i.e. c:\Program Files\IBM\SDP\runtimes\base_v7) Now that the service providers key ring is ready, you copy it to the cell configuration directory of the WebSphere Application Server V7 runtime so that your keys will be available on all nodes of a cluster for a clustered environment. This location will also work for a standalone server configuration. In your policy set bindings configuration below, you will point to this key store. 2. From the WebSphere Application Server V7 directory, copy the service providers key ring to the following directory:
copy helloServerKeys.jks profiles\<profile name>\config\cells\<cell name>

On my machine the path is C:\Program Files\IBM\SDP\runtimes\base_v7\profiles\was70profile1\ config\cells\griffith-t60pNode01Cell\MyKeys. Now you have the client keys and the server keys both with an imported certificate from the other. You will use these keys in the configuration of the WSSecurity policy set to provide encryption and signing. Back to top

Creating a policy set

WebSphere Application Server V7 allows creating policy sets from scratch to provide maximum flexibility, but WebSphere Application Server V7 also comes with many preconfigured policy sets to simplify their creation. Very often the preconfigured policy sets are more than adequate for most needs and thus copying one of the built-in policy sets and modifying it is often easier than starting from scratch it is also the recommended approach. In this tutorial, you will copy the Username WSSecurity default policy set. The Username WSSecurity default policy set comes with a WSSecurity policy and a WSAddressing policy. Within these policies, you specify message integrity by digitally signing the message body, the timestamp, the addressing headers, and the username token. Message confidentiality is achieved by encrypting the message body, the signature, and the username token. Finally, these policies specify message authentication by using the username token. All of the work of specifying what parts of the message to sign and encrypt are already done for you by copying the Username WSSecurity default policy set. Rational Application Developer 7.5.2 allows attaching policy sets and customization of clientside bindings, but does not allow customization of policy sets. To create and customize a policy set, you need to open the Administration Console of WebSphere Application Server. In this tutorial, you use the WebSphere Application Server that we installed inside of Rational Application Developer. 1. From Rational Application Developer, right-click your WebSphere Application Server V7 runtime in the Servers view and choose Administration > Run administrative console, as shown in Figure 21. Ensure your WebSphere Application Server V7 runtime is started or Run administrative console will be grayed out. Figure 21. Launching Administration Console from Rational Application

Developer

2. From the Administrative Console, select Services > Policy sets > Application
policy sets as shown in Figure 22. Figure 22. Application policy sets (see enlarged Figure 22)

3. Click the checkbox next to the Username WSSecurity default, then click
the Copy button. The Username WSSecurity default policy set encrypts the SOAP body, the signature, and the Username token. Additionally, the Username WSSecurity default policy set signs the SOAP body, the timestamp, the addressing headers, and the Username token. Message authentication is provided using the Username token. As this policy set provides defaults that are likely to be used frequently in real-life scenarios, you will use this policy set for this tutorial.

Figure 23. Copy policy set (see enlarged Figure 23)

4. Enter HelloWorldPolicySet as the name for your new policy set and any
description youd like in the description field. Click the OK button. Back to top

Exporting a policy set

As discussed previously, Rational Application Developer does not allow customization of policy sets and thus you used the Administration Console of WebSphere Application Server to create the policy set. You can then export the policy set to allow the consumer to use the same policy set. Additionally, you may attach the policy set to the service provider or service consumer using Rational Application Developer such that the policy set will get attached when deployed from Rational Application Developer. 1. From the Administration Console, select Services > Policy sets > Application policy sets as shown in Figure 22. 2. Click the checkbox next to the HelloWorldPolicySet then click the Export button. Figure 24. Exporting policy sets (see enlarged Figure 24)

3. Click the HelloWorldPolicySet.zip link as shown in Figure 24 and save the file
to c:\temp. Click the OK button to save the file. Back to top

Creating a policy set binding

The policy set defines the policies to attach to your service provider, but you need to assign a binding to specify the service-specific settings to use, such as key stores. Rather than starting from scratch, you copy the provider sample bindings and then customize it, as this is usually easier and considered a best practice.

1. In the Services menu, expand the Policy sets folder and select the General
provider policy set bindings link. This link displays the list of provider policy set bindings. 2. Click the checkbox next to the Provider sample policy set bindings, then click the Copy button. 3. Enter HelloWorldProviderBindings as the name for the new bindings and any desired text for the description field (optional), as shown in Figure 25. Figure 25. Copy policy set bindings for customization (see enlarged Figure 25)

4. Click OK.
Back to top

Configuring service provider policy set binding

The provider sample that you started with is for demonstration purposes only, and you must change the keys to provide production-level security. Therefore, you now need to customize your new policy set binding by changing the sample keys to use the real keys that you generated above. To customize the policy set binding to specify which certificates you trust: 1. Navigate to the Keys and certificates policy bindings by clicking HelloWorldProviderBindings > WS-Security > Keys and certificates. 2. Scroll down the page to the Trust anchor section and click the New button. 3. Enter HelloServerTrustStore in the name field then click the External keystore radio button. 4. Enter ${USER_INSTALL_ROOT}\config\cells\<yourCellName> \helloServerKeys.jks for the full path to the external key store. For simplicity in this tutorial, we use the hard-coded path to the key store. Normally, you would create a new WebSphere variable (e.g. MY_KEY_STORE) that would point to the absolute path so that you wouldnt need to change your policy set bindings when moving from one cell to another. 5. Select JKS as the key store type. 6. Enter f00bar as the key store password. Your screen should look something like Figure 26.

Figure 26. New trust anchor

On my machine the external key store path is C:\Program Files\IBM\SDP\runtimes\base_v7\profiles\was70profile1\config \cells\griffith-t60pNode01Cell\helloServerKeys.jks. 7. Click the OK button to save the changes. In this step, you customized the policy set binding to specify which certificates you trust. This step lets you verify that the public certificate that is used to encrypt messages is a trusted certificate. In this tutorial, you use your server-side key store as your trust store to simplify things. Normally, your trust store would contain trusted CAs (e.g. Verisign, GeoTrust) that have signed the public keys. Now that you have specified your trust store, you can customize the signing token for inbound messages to use this trust store. This token essentially verifies that the key used to sign the message is a trusted key. To customize the signing token for inbound messages to use this trust store: 1. Navigate to the Authentication and protection bindings by clicking HelloWorldProviderBindings > WS-Security > Authentication and protection. This step displays a window like the one in Figure 27.

Figure 27. Customizing policy set bindings (see enlarged Figure 27)

2. Select con_signx509token > Callback handler. Change the Certificate store to

be (none) instead of DigSigCertStore. Then choose HelloServerTrustStore next to the Trusted anchor store label as shown in Figure 28. Figure 28. Changing certificate store (see enlarged Figure 28)

3. Click the OK button to save the callback handler customizations. 4. Click the OK button again to save the consumer signature token customizations,
which should now bring you back to theAuthentication and protection page shown in Figure 27. Now that you have specified what trust store to use for verifying the signature for incoming messages, you need to customize the token to be used for signing outgoing messages: To customize the token for signing outgoing messages:

1. Select gen_signx509token > Callback handler. Then choose Custom from the
drop-down in the Key store section and click the Custom keystore configuration link. 2. Change the values to match this table:

Field Keystore path

Value
${USER_INSTALL_ROOT}\config \cells\<yourCellName> \helloServerKeys.jks JKS f00bar cn=server1,o=IBM,c=US server1 passw0rd

Keystore type Keystore password Key name Key alias Key password
3.

4. Note that since you use the private key of server1 for outgoing signatures, you must
specify the password for the private key. 5. Click the OK button to save the key store configuration changes. 6. Click the OK button to save the callback handler changes. 7. Click the OK button to save the token changes. At this point, you should be back at the Authentication and protectionpage shown in Figure 27. Now that you have customized the binding for signatures, next you customize the binding for encryption and decryption protection. You will begin with the con_encx509token token, which is used to decrypt incoming messages. To customize the binding for encryption and decryption protection: 1. Select con_encx509token > Callback handler. Then choose Custom from the drop-down in the Key store section followed by clicking the Custom keystore configuration link. 2. Change the values to match this table:

Field Keystore path

Value
${USER_INSTALL_ROOT}\config \cells\<yourCellName> \helloServerKeys.jks JKS

Keystore type

Keystore password Key name Key alias Key password

3.

f00bar cn=server1,o=IBM,c=US server1 passw0rd

4. Notice that you have to enter the keys password in addition to the key store password since you are accessing the private key. 5. The results should look similar to Figure 29.

6.

Figure 29. Key store for consumer decryption

7. Click the OK button to save the key store configuration changes. 8. Click the OK button to save the callback handler changes. 9. Click the OK button to save the token changes. At this point, you should be back at
the Authentication and protectionpage as in Figure 27. To customize the token used for encrypting outgoing messages: 1. Click gen_encx509token > Callback handler. Then choose Custom from the dropdown in the Keystore section and click the Custom keystore configuration link. 2. Change the values to match this table:

Field Keystore path

Value
${USER_INSTALL_ROOT}\config \cells\<yourCellName> \helloServerKeys.jks

Keystore type Keystore password Key name Key alias

3.

JKS f00bar cn=myclient,o=ACME,c=US myclient

4. Notice that in this case you do not need to provide a password for the key alias because you are using the clients public key to encrypt the outgoing response message. 5. Click the OK button to save the key store configuration changes. 6. Click the OK button to save the callback handler changes. 7. Click the OK button to save the token changes. At this point, you should be back at the Authentication and protectionpage as in Figure 27. So far you have created a custom policy set and a custom policy set binding and customized to use custom keys. While WebSphere Application Server V7 provides the ability to attach policy sets and bindings to services in the Administrative console, for this tutorial, you will use Rational Application Developer V7.5.2 to accomplish this task. Therefore, you now need to export the policy set and bindings to import them into Rational Application Developer. Back to top

Exporting a policy set binding

Just as you exported the copied policy set above, you can also export the policy set bindings. Because this policy set binding is only for the service provider (i.e. server-side), it isnt necessary to export this policy set binding. However, doing so allows you to attach the binding to the service provider in Rational Application Developer, which simplifies policy set attachment during development. 1. In the Services menu, expand the Policy sets folder. Select the General provider policy set bindings link to display the list of provider policy set bindings. 2. Click the checkbox next to the HelloWorldProviderBindings policy set bindings, then click the Export button. 3. Click the HelloWorldPolicySet.zip link as shown in Figure 30 and save the file to c:\temp. Click the OK button to save the file. Figure 30. Export policy set bindings

Section 5. Securing the service provider

Now that you have created a custom policy set and policy set binding (which you exported to c:\temp) you need to import them into the HelloWorldProject to attach them to the service provider. Recall that policy sets provide a declarative way to provide qualities of service (QoS) for Web services. By attaching a policy set and binding to a Web service, you are declaratively specifying what QoS to use. 1. From the main menu of Rational Application Developer choose File > Import > Web services > WebSphere Policy Sets. Now click the Next button, which displays a dialog box like the one in Figure 31. 2. Click the Browse button and choose the HelloWorldPolicySet.zip file that you exported to c:\temp above. 3. The wizard reads the zip file and lists the policy sets included in the file. Click the checkbox next to HelloWorldPolicySet,then click the Finish button. Figure 31. Import policy set

4. As in the steps above, right-click HelloWorldProject and choose Import > Import >
Web services > WebSphere Named Bindings. Now click the Next button, which displays a dialog box like the one in Figure 32. 5. Click the Browse button and choose the HelloWorldProviderBindings.zip file that you exported to c:\temp above. 6. Again, the wizard reads the zip file and list the policy set bindings included in the file. Click the checkbox next toHelloWorldProviderBindings, then click the Finish button.

Figure 32. Import policy set bindings

Once the policy set and bindings have been imported into Rational Application Developer, you can attach them to the service provider. 7. In Rational Application Developer, drill into the HelloWorldProject > Services > {http://dwexample.ibm.com}HelloWorldProviderService then right-click and choose Manage policy set attachmentas shown in figure 33: Figure 33. Attaching policy set and bindings

8. Click the Add button add a policy set and binding to an endpoint. 9. Leave the scope set to the entire service and choose HelloWorldPolicySet from the
drop-down for the policy set andHelloWorldProviderBindings from the drop-down for the binding as shown in figure 34.

Figure 34. Customizing policy set bindings

10. Click the OK button to save this association. 11. Click the Finish button to close the policy set attachment dialog box.
Now that you have attached the policy set and bindings to the service provider, you will deploy the service provider onto the WebSphere Application Server runtime and verify that our policy set and bindings have been attached. There are a variety of ways to deploy the service provider onto the WebSphere Application Server, but in this tutorial we will use the Add and Remove Projects menu item available in the Rational Application Developer Servers view. To deploy the service provider: 1. Right-click WebSphere Application Server v7.0 at localhost (or whatever your server is called if different) and chooseOpen. This will bring up the server configuration settings page as shown in Figure 35. Figure 35. WebSphere Application Server V7.0 server configuration (see

enlarged Figure 35)

2. Ensure Run server with resources on Server is selected in the Publishing settings
for WebSphere Application Server section. 3. Save and close the server configuration file. The Run server with resource on Server setting will ensure that the policy set and bindings attachment show up in the WebSphere Application Server Administrative Console. In order to ensure a clean deploy, you will remove the HelloWorldProjectEAR from the server, then re-add it. 4. Right-click the HelloWorldProjectEAR project under WebSphere Application Server v7.0 at localhost in the Servers view and choose Remove as shown Figure 36. Figure 36. Remove HelloWorldProjectEAR from server

Now that the project has been removed, you will add it back, which will cause a fresh deploy. 5. Right-click WebSphere Application Server v7.0 at localhost (or whatever your server is called if different) and chooseAdd and Remove Projects as shown in Figure 37. 6. Click the HelloWorldProjectEAR project from the Available projects field and click the Add > button to move it to the Configured projects field then click the Finish button. Figure 37. Deploy Service Provider to WebSphere Application Server

7. When the server finishes deploying and publishing, use the Administrative Console
to verify that the service provider was successfully deployed to WebSphere Application Server and that the policy set and bindings have been attached. Once again right-click WebSphere Application Server v7.0 at localhost, but this time choose Administration > Run Administrative console. 8. Login to the admin console and select Services > Services providers. You should see the HelloWorldProviderServicelisted in the service providers. 9. Click the HelloWorldProviderService to drill into this service. 10. You should now see the HelloWorldPolicySet attached as the policy set and HelloWorldProviderBindings attached for the binding as shown in Figure 38.

Figure 38. Verify policy set and bindings attached (see enlarged Figure 38)

If you do not see the HelloWorldProviderService in the service providers window, then logout of the Adminstrative Console and then log back in to refresh the console such that you see the policy set and bindings attached to the service provider as shown in Figure 38. Since you copied the Username WSSecurity default policy set, this policy set defines authentication through the username token. As a result, you need to enable security on the WebSphere Application Server server such that authentication can occur. To enable security on WebSphere Application Server: 1. In the Administrative Console, navigate to Security > Global security and verify that Enable administrative security andEnable application security are selected as shown in Figure 39.

Figure 39. Enable application security (see enlarged Figure 39)

2. If security was not enabled before, you need to restart WebSphere Application Server for the security settings to take effect.

Section 6. Consuming a secure service At this point in the tutorial, you should have the service provider running on WebSphere Application Server V7 with the customized HelloWorldPolicySet and bindings attached. If you were to rerun the service consumer as developed above, the service provider would reply with a SOAP fault indicating that the consumer does not adhere to the policy set attached to this provider. Therefore, you need to attach a policy set to the consumer (i.e. client-side) and customize the consumer bindings to match up with the expectations of the service provider. One way to ensure the consumer adheres to the policy of the service provider is to use the same policy set, which is what well do in this tutorial. Since you imported the HelloWorldPolicySet into Rational Application Developer to attach it to the service provider, it is also available to be attached to our service consumer. Attaching a policy set In a similar fashion to attaching the policy set to the service provider, you do the same thing with the service consumer. The following sections describe this process. To configure the consumer-side binding for signatures:

1. Drill down to HelloWorldConsumer > Services > Clients > {http://dwexample.ibm.com}HelloWorldProviderService. Right-click and choose Manage policy set attachment 2. Click the Next button followed by the Add button of the Application section, which presents the dialog box shown in Figure 40. Figure 40. Attaching policy set

3. Select HelloWorldPolicySet for the policy set drop-down. 4. Type HelloWorldConsumerBinding in the drop-down binding field and click OK. 5. Select the WSSecurity policy type in the bindings configuration section. Click the Configure button, which presents the WSSecurity Binding Configuration dialog as shown in Figure 41.

Figure 41. WSSecurity Binding Configuration (see enlarged Figure 41)

6. Select the Digital Signature Configuration tab, and then click the Key Store Settings button of the Outbound Message Security Configuration section. 7. Enter the values in the following table for the Key Store Settings dialog shown in Figure 42. Field Keystore path Value

C:\Program Files\IBM\SDP \myclientKeys.jks Keystore passwordg00ber JKS Keystore type

Key alias Key Password 8.

myclient p@ssword

Figure 42. Outbound signature key settings

9. Notice that you are specifying that you want to sign the outbound (i.e. service request) message using the private key of the myclient alias. 10. Click the OK button. 11. In the Inbound Message Security Configuration section, uncheck the Trust Any Certificate, because we only want to trust the signature if the response is from the server. 12. Click the Key Store Settings button, then enter the values in the following table: Field Keystore path Value
C:\Program Files\IBM\SDP \myclientKeys.jks Keystore passwordg00ber JKS Keystore type

13. 14. Click the OK button. 15. Enter C:\temp\server1.cert as the value for the Certificate Path field. Now you have configured the consumer-side binding for signatures. Next, you will configure the keys to use for encryption. To configure the keys to use for encryption:

1. Select the XML Encryption Configuration tab, and then click the Key Store Settings button of the Outbound Message Security Configuration section. 2. Enter the values from the following table for the Key Store Settings dialog shown in Figure 43. Field Keystore path Value
C:\Program Files\IBM\SDP \myclientKeys.jks Keystore passwordg00ber JKS Keystore type server1 Key alias

3.

Figure 43. Outbound encryption key settings

4. Since you are encrypting the service request for the service provider, which is associated with the server1 certificate, you specify the public key of server1 in Figure 44. 5. Click the OK button. To configure how to decrypt the inbound message (i.e. the response): 1. On the XML Encryption Configuration tab, click the Key Store Settings button in the Inbound Message Security Configuration section. 2. Enter the values from the following table for the Key Store Settings dialog shown in Figure 44. Field Keystore path Value
C:\Program Files\IBM\SDP

Keystore passwordg00ber JKS Keystore type myclient Key alias p@ssword Key password 3.

\myclientKeys.jks

Figure 44. Inbound encryption key settings

4. When the providers response comes back, it will be encrypted with the clients public key. Therefore, you need to decrypt the message using the clients private key, which is what we have specified in Figure 44. 5. Click the OK button. Recall that the Username WSSecurity default policy set that you copied included authentication using a username token. Somehow you need to get a valid username token in the SOAP header for the server to verify that you are authenticated before executing the service provider Web service. The Token Authentication tab provides two such methods. You will choose the UNTGenerateCallbackHandler. 6. Select the Token Authentication tab then choose the com.ibm.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHand ler as the callback handler, as Figure 45 shows. 7. Enter a valid user name and password that matches the user repository of your WebSphere Application Server (e.g. admin/admin). 8. Click the Add Timestamp checkbox. 9. Click the Add Nonce checkbox.

10. Click the OK button, and then click the Finish button. Figure 45. Token authentication (see enlarged Figure 45)

If the dialog box as shown in Figure 45 does not include checkboxes for Add Timestamp and Add Nonce, you will need to ensure you are using Rational Application Developer 7.5.2 . Section 7. Testing secure JAX-WS In section 3 of this tutorial, you tested the service provider and consumer and viewed the SOAP messages as they traveled between the client and server. In section 3, you had not yet enabled message-level security through the attachment of policy sets, and thus the SOAP messages were sent in clear text (i.e. not encrypted) as shown in Figure 17. As one of the goals with message- level security is to ensure confidentiality (i.e. only the intended recipient can see the data inside the SOAP message), you now need to rerun the test and verify that the SOAP messages contain encrypted data that isnt visible to anyone except the intended recipient (not even the TCP/IP Monitor that is acting as an intermediary). 1. Ensure the TCP/IP Monitor is started as shown in Figure 15, then right-click the ClientTest.java file of the HelloWorldConsumer project and choose Run As > Run Configurations. This should present a Run Configurations dialog box as shown in Figure 46.

Figure 46. Setting ClientTest arguments (see enlarged Figure 46)

2. Since the consumer needs to use a Java Authentication and Authorization Service (JAAS) to pass in the Username credentials, you need to specify the following VM argument:
-Djava.security.auth.login.config= C:\Program Files\IBM\SDP\runtimes\base_v7 \profiles\was70profile1\properties\wsjaas_client.conf

3. Next click the Run button and view the results in the TCP/IP Monitor view, which looks something like Figure 47. Figure 47. Viewing the SOAP messages with XML encryption (see enlarged

Figure 47)

Notice that the Console shows the output from the consumer after unencrypting the message. If you view the WebSphere Application Server console log, you see a similar message, which demonstrates that the service provider received the message. Section 8. Conclusion In this tutorial, we demonstrated how to create a Web service provider using JAX-WS annotations. Then we showed you how to build a matching consumer and how to test the client- to-server communications. Next, we demonstrated how to create a custom policy set, which we showed you how to customize with personalized asymmetric keys, before once again testing the client and server pair. Additionally, we showed you how to monitor the data flowing between the client and the server, and verify that in fact the SOAP messages are being encrypted and protected by the customized policy set you created and associated with the service consumer and provider pair. While this tutorial was designed to teach and instruct, the steps taken are valid production-level configuration options that employ strong cryptography for encryption and protection. Acknowledgements Special thanks to Zina Mostafa and Indran Naick for reviewing this tutorial.