Introduction

Web services security encompasses the following key aspects:

• Authentication
• Confidentiality – message encryption
• Integrity – digital signature

This article will describe how authentication is enabled between two services by using the Username token. It will also describe the use of Secure Sockets Layer (SSL) to transport SOAP messages between a client and a web service over HTTP. In WebSphere Process Server V7 (hereafter called Process Server), we use policy sets and binding to standardize the way security and other quality of service parameters are configured. This enables reuse of configuration and an exchange of configuration information in a standardized manner. This also enables policies to be applied dynamically on the server instead of having to define them during development using deployment descriptors.

• Policy type: This is a single type of Quality of Server (QoS) defined by a set of assertions. Examples of policy types are:
  • WS-Security
  • WS-Transaction
  • HTTPs
  • WS-Addressing
• Policy: This is a named configured instance of a policy.
• Binding: This is a topology-specific configuration of a QoS. It contains environment and system specific configuration parameters, such as persistence store information or key store information.

In Process Server, authentication is supported by the following four mechanisms:

• Username token (1.1 and 1.0)
• X.509 certificates
• LTPA token
• Custom

The use of the WS Security Username token profile is common and enables a user name and password to be encapsulated in a security token.

Back to top

Setting up the security configuration

For purposes of illustration, we will use two simple web-services called "HelloWS" and "HelloBackend" (Figure 1). The service invocation of HelloBackend by HelloWS is secured by a username token and SSL. When HelloWS invokes HelloBackend, the client policies associated with that invocation are calculated and applied.

"HelloWS" is a simple Service Component Architecture (SCA) module with a web service export and contains a Java™ component with a method called “helloMethod”. This is the web service client that invokes HelloBackend securely. You will configure the client to generate the Username token headers and insert them in the SOAP message request. The client is deployed on Process Server.

"HelloBackend" is a simple SCA module with a web service export and contains a Java component with a method called “operation1”. The web service is deployed in Process Server. You will configure the web service to accept the SOAP headers and authenticate the identity passed in the UsernameToken. The authentication is done by Process Server using an internal file repository as the user registry, and requires that the SOAP requestor messages contain the user name and password in the SOAP header.

For simplicity, you can deploy HelloWS and HelloBackend into the same Process Server instance that is included in WebSphere Integration Developer.

Prerequisites

The sample scenario was tested with WebSphere Process Server V7.0. To run the sample, you need the following:

• WebSphere Integration Developer V7.0. Ensure that the integrated test environment with WebSphere Process Server V7.0 is available.
• WebSphere global security is enabled on Process Server with administrative and application security also enabled.
• The user account repository is set to a federated repository with the default Internal File Repository. Ensure that the user ID “jdoe” with a password of “jdoe” are created in the file registry. Use the administrative console to create this user.
• Download the zip files included in this article and extract them to your C: drive. This creates a directory called WPS7UsernameTokenArticle and places the following files in the directory:
  • HelloBackendApp.ear
  • HelloWSApp.ear
  • WSS-UNT-SamplePI.zip

Back to top

Overview of steps

The basic steps required to run our scenario are:

1. Deploy the client-side and service-side applications.
2. Configure SSL:
   • Create a server-side SSL configuration.
   • Create the server-side key store.
   • Create the server self-signed certificate.
   • Export the signer certificate.
   • Create the client-side SSL configuration.
   • Create the client-side trust store.
   • Import the server’s certificated into the client trust store.
3. Create the service-side application policy set for the Username token.
4. Attach a policy set and binding to the service.
5. Create the client-side application policy set for the Username token.
6. Define a client binding.
7. Attach a policy set and binding to the client.
8. Configure the service end-point on the client side.
9. Create a virtual host and enable SSL on the specified port.
10. Testing the web services.

Back to top

Deploying the client-side and service-side applications

1. Import the sample project interchange file included with this article into WebSphere Integration Developer. The file contains the following projects:
   • HelloBackend
   • HelloUtil
   • HelloWS
   • HelloWSLib
2. To deploy the applications, use the administrative console and deploy HelloBackendApp.ear and HelloWSApp .ear. No security configuration is required at this stage.

Back to top

Configuring SSL

Create a server-side SSL configuration

1. Log into Process Server administrative console and click SSL certificate and key management > SSL configurations > New. Enter the name of the configuration as ServerSSL and click OK and save the configuration. All other values are kept as defaults.

Create a server-side key store

1. Go to SSL certificate and key management > SSL configurations > ServerSSL > Key stores and certificates and click New.
2. Enter the values as shown in Figure 2.
   
   Figure 2. Creating a server key store
   
   
   

   Use the WebSphere environment variable, such as CONFIG_ROOT, to indicate the path to the key store. Provide a password for the key store and select the default type as PKCS12.

3. Click OK to create the key store and save it the master configuration.

Create a self-signed certificate

1. For the demonstration, we will use self-signed certificate for transferring the key from the server to the client. Go to SSL certificate and key management > SSL configurations > ServerSSL > Key stores and certificates > ServerKeyStore. Click Personal Certificates under Additional Properties. Click Create > Self-signed Certificate as shown in Figure 3.
   
   Figure 3. Creating self-signed certifcate
   
   
   
2. Enter the values for the self-signed certificate as shown in Figure 4.
   
   Figure 4. Server signed certificate
   
   
   
3. Enter the fully qualified host name for the Common name. Click OK and save to the master configuration.

Export the self-signed certificate

1. Go to the certificate created in the above step. SSL certificate and key management > SSL configurations > ServerSSL > Key stores and certificates > ServerKeyStore > Personal certificates and click Extract.
2. Enter the location where the certificate will be extracted to, as shown in Figure 5.
   
   Figure 5. Export signed certificate
   
   
   
3. Click OK. The self-signed certificated is saved in the indicated location.

Create the client side SSL configuration

1. On the client side, log into the Process Server administrative console and click SSL certificate and key management > SSL configurations > New. Enter the name of the configuration as ClientSSL and click OK and save the configuration. All other values are kept as default.

Create the trust store

1. You need to create the trust store into which the extracted self-signed server certificate will be imported. Go to SSL certificate and key management > SSL configurations > ClientSSL > Key stores and certificates and click New.
2. Enter the values as shown in Figure 6.
   
   Figure 6. Creating the client trust store
   
   
   
3. Enter the path to the trust store. Use WebSphere environment variables and a path specific to your Process Server installation. Provide a password for the trust store. Click OK and save to the master configuration.

Add the server certificate to the client trust store

1. Go to SSL certificate and key management > SSL configurations > ClientSSL > Key stores and certificates > ClientTrustStore > Signer certificates and click Add. Enter values as shown in Figure 7.
   
   Figure 7. Adding certificate to client trust store
   
   
   
2. Provide the location of the file, which was extracted from the server in Figure 5. Click OK and save to the master configuration. Now the client and server can communicate securely using SSL.

   In the following steps, you will configure the Username token and enable the service to authenticate the client.

Back to top

Creating the service-side application policy set for the Username Token

1. Go to Services > Application Policy Sets and click New. Enter the name for the policy Set as WSS Username Token Service and add a description for the policy set.
2. Click Add > WS-Security as shown in Figure 8.
   
   Figure 8. Creating the service side application policy set
   
   
   

   The WS-Security policy is now added to the policy set as shown in Figure 9.

   
   
   Figure 9. Setting WS-Security policy
   
   
   
3. Click WS-Security and then Main Policy. Uncheck Message Level Protection as shown in Figure 10. For now, you will not enable the message level security such as message encryption or digital signatures (for data integrity).
   
   Figure 10. Main policy definition
   
   
   
4. Click OK and save to the master configuration.
5. Add the request token policy. Click Man Policy again and select Request token policies. Select Add Token Type and Username Token. Provide a token name as shown in Figure 11.
   
   Figure 11. Adding the username token policy to the Main policy
   
   
   
6. Click OK and save to the master configuration.

Back to top

Attaching a policy set and binding to the service

1. Before you attach the policy set and binding, create a new binding for the service consumer.
2. Go to Services > General provider policy set bindings. Click New.
3. Enter the name of the binding as ServerBinding. Click OK and save.
4. Go to Services > General provider policy set bindings > ServerBinding.
5. Click WS-Security amd then select Authentication and protection.
6. Under Authentication tokens, select New Token and then Token Consumer.
7. Provide a name for the token consumer as untconsumer. Select Username Token v1.0 as the token type.
8. Click Apply and save the changes.
9. Again, go to Services > General provider policy set bindings > ServerBinding.
10. Click WS-Security and click Caller.
11. Click New to enter a new caller. Provide a name for caller as Caller as shown in Figure 12.
12. Enter the caller identity local part as:

    http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile- 1.0#UsernameToken

    
    
    
    Figure 12. Adding a caller
    
    
    
13. Click OK and save. By defining the caller, you are enabling WebSphere to create the security credential and principal, using the Username token credentials.
14. Go to Services > Service providers > helloBackendExport1_helloBackendHttpService. Select helloBackendExport1_helloBackendHttpService, click the Attach button and select WSS Username Token Service policy set as shown in Figure 13.
    
    Figure 13. Attaching the policy to the service
    
    
    
15. Now select helloBackendExport1_helloBackendHttpService again and click the Assign Binding button and select ServerBinding as shown in Figure 14.
    
    Figure 14. Assigning the binding to the service
    
    
    
16. Save the configuration.
17. The policy set attachment for the service provider HelloBackend looks similar to Figure 15.
    
    Figure 15. Attaching the policy and assigning the binding to the service
    
    
    

Back to top

Creating the client-side application policy set for the Username token

You will now define a Username policy on the client side as well so that the client can pass the credentials while invoking the service. There are four different scenarios on how a client can obtain the policy while it invokes the web service provider:

• There is no policy.
• Client policy: The policy is calculated based on the policy set, which is a static client policy configuration.
• Provider policy: This policy is based on dynamically acquired provider policy. In this scenario, the policy configuration is based on the provider’s requirements.
• Client and provider policy: In addition to the provider policy, the client can configure the restrictions as to what is applicable.

For our service configuration, we will choose the client policy since we have defined the client policy set.

To define the WS Security policy set for the client side:

1. Go to Services > Application Policy Sets and click New. Enter the name for the policy set as WSS Username Token Service and add a description for the policy set.
2. Click Add > WS-Security.
3. Click WS-Security and then Main Policy. Uncheck Message Level Protection as shown. For the present, you will not be enabling message level security such as message encryption or digital signatures (for data integrity).
4. Click OK and save to the master configuration.
5. Add the request token policy. Click Man Policy again and select Request token policies. Select Add Token Type and Username Token. Provide a token name as WSS Username Token Client with the WS-Security version as 1.0.
6. Click OK and save to the master configuration.

Back to top

Defining a client binding

Bindings provide specific details related to the policy set that is selected at runtime. In the context of the Username token policy, you can provide the specific JAAS Callback Handler to be used.

1. Go to Services > General client policy set bindings and select Client sample. Click the Copy button and provide a name for the binding as ClientBinding, as shown in Figure 16.
2. Now select the newly created ClientBinding. These policies are already associated with this binding. You will need to configure the SSL transport and WS-Security policies.
   
   Figure 16. Define client side binding
   
   
   
3. Now select WS-Security and then select Authentication and protection.
4. Go to Authentication tokens > gen_signunametoken with the Usage mentioned as Outbound and click it (Figure 17).
   
   Figure 17. Authentication token
   
   
   
5. Select the default Token type as Username Token v1.0. Click Callback Handler at the bottom of the screen. Select Use custom callback handler class and provide the class name as com.ibm.raadss.security.UNTCustomCallbackHandler (Figure 18). It is not required to provide the user name and password under the Basic Authentication section.
   
   Figure 18. Defining the custom callback handler on the client side
   
   
   

   Note: Using the custom call back handler will provide better features and the ability to pass the username and password dynamically from the client’s session context. Refer to Configuring the custom JAAS callback handler for further details.

6. Click OK and save to the master configuration.
7. To configure the SSL transport for this client binding, select General client policy set bindings > ClientBinding > SSL transport. Under Outbound service requests, select ClientSSL and under Inbound service responses, select ClientSSL as shown in Figure 19.
   
   Figure 19. Defining an SSL transport in the client policy set binding
   
   
   
8. Click OK and save to the master configuration

Back to top

Attaching a policy set and binding to client

1. Go to Application > Service clients > helloBackendExport1_helloBackendHttpService. Select helloBackendExport1_helloBackendHttpService and click the Attach Client Policy Set button and select WSS Username Token Client as shown in Figure 20.
   
   Figure 20. Attaching the client policy set
   
   
   
2. Now assign the binding associated with this policy set by selecting the Assign Binding button and select ClientBinding, as shown in Figure 21.
   
   Figure 21. Assigning the client binding
   
   
   

Back to top

Configuring the service end-point on the client side

1. Go to Applications > SCA Modules > HelloWS. Under the module components, expand Binding as shown in Figure 22.
   
   Figure 22. Configuring the service end point
   
   
   
2. Select the binding and change the default endpoint of the service. Click Edit beside Target Endpoint address and enter: https://localhost:6444/HelloBackendWeb/sca/helloBackendExport1.

In this sample, we have chosen port 6444 as the SSL enabled port where the service will be available. We need to enable port 6444 to accept SSL communication and bind it to our service by defining a new virtual host on that port.

Back to top

Creating a virtual host and enable SSL on the specified port

1. First, you will define a new transport chain on the server. Go to Servers > Websphere Application Server. Select the server and go to Web container transport chains under Web container settings. Click New. Provide a name for the transport chain as ServiceInboundSecure, as shown in Figure 23. Select the Transport chain template as WebContainer-Secure and click Next.
   
   Figure 23. Creating a new virtual host for SSL
   
   
   
2. Provide the name of the port as ServiceSecure and the port number as 6444. Click Next and then Finish to create the new transport chain. Save to the master configuration.
3. Go to Environment > Virtual Hosts and click New. Provide a name to the new virtual host as SecureVH. Click OK and save.
4. Go to Environment > Virtual Hosts > SecureVH > Host aliases and click New. Enter 6444 as the port number.
5. Now go to Applications > Enterprise Applications > HelloBackendApp and select Virtual hosts under Web Module properties. From the drop down under Virtual Host, select SecureVH . Click OK and save to the master configuration.

You have now completed the configuration steps required for this sample and you are ready to test it. Restart Process Server so that the transport chain and SSL are activated.

Back to top

Testing the web services

Before testing the web services, ensure that the callback handler is available in the Process Server classpath. Refer to Configuring the custom JAAS callback handler for further details. To verify that the message from the client to server is encrypted and not in clear text, the TCP Monitor can intercept and forward the request. You will use TCP as the transport for this.

1. In Websphere Integration Developer, start the TCP Monitor. Go to Windows > Preferences > Run/Debug > TCP/IP Monitor.
2. Select Add and provide the details as shown in Figure 24. Click OK.
   
   Figure 24. TCP Monitor selection to monitor SSL
   
   
   
3. Click Start to activate the TCP Monitor.
4. Change the service endpoint port for the service invocation. Log on to the Process Server administration console. Navigate to Application > SCA Modules > HelloWS. Under Imports, expand Binding and click the binding that is displayed. Edit the port number and set it to 2444 and click OK and save the configuration.
5. The service request is directed to port 2444 and then forwarded to port 6444 by the TCP Monitor.
6. Use a web service testing tool, such as web services explorer or SOAP UI, to invoke HelloWS. Since you have configured authentication and SSL between HelloWS and HelloBackend, you will verify the proper invocation of the HelloBackend service by viewing entries in the log file indicating this. Enter a value for input1 element as jdoe. This user ID was registered in the internal file user registry as a prerequisite to this exercise (Figure 25).
   
   Figure 25. Invoking HelloWS web service client
   
   
   
7. View the TCP Monitor. It does not show you any text as it is encrypted.
8. View the SystemOut.log file (Figure 26) on Process Server, indicating the communication between the client and server.
   
   Figure 26. Viewing SystemOut.log file
   
   
   
9. Now re-invoke this service with the input1 element set to a user ID not available in the internal file user registry. You will see an error indicating that the service failed to check the given username and password in the user registry.

Back to top

Configuring the custom JAAS callback handler

WebSphere provides a default username token callback handler that passes the username, password, and the username token properties while a service requestor invokes a web service. However, you can develop a custom callback handler to pass the user ID and password dynamically. This is configured in the client policy set binding for WS-Security in Process Server.

The requirements for the custom callback handler are as follows:

1. The callback handler must implement the javax.security.auth.callback.Callback interface.
2. This callback handler implements the handle (Callback callbacks[]) method in the interface.
3. The handle method needs to support four types of callbacks: NameCallback, PasswordCallback, PropertyCallback, and UNTGenerateCallback
4. The callback handle must have a constructor, which takes a Map<Object,Object> object as input.

Download the sample callback implementation. Compile and export the Java class in a JAR file and place it in the Process Server classpath.

The callback handler class has two thread local variables that can store the user ID and password from the client instance. This is referred in the handle method of the callback handler. The client will use the setThreadIdentity to pass the credentials to the callback handler.

Back to top

Conclusion

Message level security is an important component in SOA. In the sample, you used transport level security because the password would otherwise be in clear text. In addition, you also explored the use of policy sets and bindings in WebSphere Process Server V7.0 to configure WS-Security and transport level security.

Back to top

Acknowledgements

The author would like to thank S Saravanan and Naveen Reddy for their valuable comments and reviews.

Back to top

Downloads

Information about download methods

Resources

• WebSphere Process Server V7.0 Information Center
  
  
• OASIS Standard: Web services security: UsernameToken Profile 1.0
  
  
• IBM Redbook: WebSphere Application Server V7.0 Web Services Guide
  
  

About the author

Parasuram Balakrishnan is an IT Specialist at IBM and works for Software Labs Services, Business Process Management practice. Parasuram has over 13 years of experience in developing custom applications as well reusable software assets built upon IBM products and technologies.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Setting up the security configuration
• Overview of steps
• Deploying the client-side and service-side applications
• Configuring SSL
• Creating the service-side application policy set for the Username Token
• Attaching a policy set and binding to the service
• Creating the client-side application policy set for the Username token
• Defining a client binding
• Attaching a policy set and binding to client
• Configuring the service end-point on the client side
• Creating a virtual host and enable SSL on the specified port
• Testing the web services
• Configuring the custom JAAS callback handler
• Conclusion
• Acknowledgements
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

WebSphere Portal can help your small and midsize business achieve better website security, along with faster time to value with easily deployable and customizable example Web sites.

---

• Try: Download a free trial version of IBM WebSphere Portal Express V6.1, which offers collaboration, document management, and secure Web content management.
• Article: This article provides an overview of the WebSphere Portal security architecture, including internet security, and secure connections between clients.
• Tutorial: This tutorial take you through the steps to develop and test your first portlet WebSphere Portal Test Environment.
• Demo: These demos show Web 2.0 features available today within WebSphere Portal, as well as several features planned for the future.
• Buy: IBM WebSphere Portal Express

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers