Configuring WS-Security for JAX-RPC web services in WebSphere Process Server V7

Calling secure web services remotely from different WebSphere cells

This tutorial shows you how to configure WS-Security and the WebSphere® environment so that a JSP client in one WebSphere cell can call a JAX-RPC Web service in WebSphere Process Server in a different cell.

Share:

Samir Nasser (snasser@us.ibm.com), Senior Managing Consultant, Certified IT Specialist, IBM

Photo of Samir NasserSamir Nasser is a Senior Managing Consultant and Certified IT Specialist with the IBM Software Services for WebSphere team in Durham, North Carolina. He is currently architecting and developing SOA solutions based on the WebSphere family of products.



12 January 2011

Also available in Chinese

Before you start

This tutorial walks you through all the steps needed to configure WS-Security for a JAX-RPC web service to run in WebSphere Process Server V7 in one WebSphere cell, and a JSP client to run in a different WebSphere cell. It also provides all the steps needed for single sign-on across WebSphere cells.

Although WS-Security addresses message-level authentication, confidentiality, and integrity, the scope of WS-Security in this tutorial is limited to propagating credentials through the use of Lightweight Third Party Authentication (LTPA) tokens. Other means of propagating credentials in the WS-Security envelope are supported in WebSphere Application Server.

Objectives

The objective of this tutorial is to make it easy for WebSphere users to configure WS-Security for a JSP client to run in a WebSphere cell and a JAX-RPC web service to run in a WebSphere Process Server cell.

Prerequisites

To follow the steps in this tutorial, you need WebSphere Integration Developer V7 to configure WS-Security for the JSP client and the JAX-RPC web service. The WebSphere Process Server test environment that comes with WebSphere Integration Developer is adequate to run the test, but you need to create another WebSphere cell for the JSP client to use the single-sign on capability through LTPA.

System requirements

  • WebSphere Integration Developer V7
  • WebSphere Process Server V7 test environment that comes with WebSphere Integration Developer
  • Another WebSphere cell

Duration

2 hours

Download files

You can download the following project interchange files from the Download section:


Introduction

WebSphere Process Server (hereafter called Process Server) provides a runtime environment for a number of different types of SCA services, such as a BPEL process, a Java™ component, and a business rules group. These services are exposed in a number of different ways that enable clients to call them. One of the ways to expose services in Process Server is a web service. Process Server V7 supports SOAP 1.1/HTTP, SOAP 1.2/HTTP, SOAP 1.1/JMS, and SOAP 1.1/HTTP using JAX-RPC. It is a common scenario to have a client running in one WebSphere cell that needs to securely call a web service in Process Server in a different WebSphere cell.

This tutorial provides the steps needed to configure WS-Security on both the JSP client and the JAX-RPC web service running in different WebSphere cells. The tutorial also provides the LTPA configuration steps needed on both cells to enable single sign-on across the WebSphere cells. The user is prompted to enter the user ID and password when accessing the JSP client. With the right credentials, the user has to log in only once through the JSP client. These credentials flow from the JSP client WebSphere cell to the web service WebSphere cell. Once successfully authenticated, the user can invoke the web service.

Here are the high-level steps to configure WS-Security on the JSP client and the web service and to configure single sign-on across WebSphere cells via LTPA:

  1. Set up two WebSphere cells with one application server in each cell.
  2. Exchange LTPA keys between the WebSphere cells. This way, credentials encrypted in one WebSphere cell are decrypted and validated in another WebSphere cell. The default file-based user registry that comes with WebSphere will work for our tests in this tutorial.
  3. Restart all WebSphere environments for the LTPA security changes to take effect.
  4. Configure WS-Security for the JAX-RPC web service.
  5. Configure WS-Security for the JSP client.

To follow the steps in this tutorial, you only need the Integration Developer tool, the Process Server test environment, and a WebSphere cell that you can create from the Process Server code base available with Integration Developer. The screen shots shown in this tutorial are taken from Integration Developer V7. If you want to perform the steps in this tutorial, start with the PI_Start.zip project interchange that is available in the Download section. Alternatively, you can download PI_Final.zip, which has all the specified configurations.


Configuring single sign-on

By default, single sign-on in a WebSphere environment is supported via LTPA. The user logs in once through one of the WebSphere servers. Then, the user's credentials flow from one server to another as needed without having the user log in again. This is the default behavior if the user's request flows within one WebSphere cell. If the user's request crosses from one WebSphere cell to another, both WebSphere cells must be configured for single sign-on. Otherwise, the user needs to log in again when the request calls a secure resource in the other WebSphere cell.

To enable single sign-on between two WebSphere cells:

  1. Export the LTPA keys from WebSphere cell A (this could be the web service Process Server cell).
    1. Make sure all members of WebSphere cell A are running.
    2. Log on to the WebSphere administrative console of cell A.
    3. Click Security > Global security in the navigation table on the left.
    4. Click the LTPA link as shown in Figure 1. Note that administration security and application security are enabled.
      Figure 1. LTPA link
      LTPA link
    5. Select the key set group from the drop-down list that you want to generate the LTPA keys.
    6. Make sure that the LTPA keys are not generated automatically. To check if the automatic LTPA key generation is disabled, click Key set groups under the drop-down list shown in Figure 2. Click the key set group that you want to generate the LTPA keys for. Make sure the Automatically generate keys check box is unchecked as shown in Figure 3.
      Figure 2. Generate LTPA keys
      Generate LTPA keys
      Figure 3. Automatically generate LTPA keys check box
      Automatically generate LTPA keys check box
    7. Click Generate keys as shown in Figure 2. Click Save after the keys are generated.
    8. Go back to the panel that is shown in Figure 2 (Security > Global security > LTPA).
    9. Enter a password that is easy to remember in the Password and Confirm password fields. Enter a fully qualified filename for the key file in the Fully qalified key file name field as shown in Figure 4. The password is used to access the key file by both WebSphere cells so that both cells use the same LTPA keys.
      Figure 4. Exporting LTPA keys
      Exporting LTPA keys
    10. Click Export keys.
    11. Click OK and Save.
    12. Restart all members of cell A.
  2. Import the LTPA keys, exported in the previous step, into WebSphere cell B:
    1. Make sure all members of WebSphere cell B are running.
    2. Log on to the WebSphere administrative console of cell B.
    3. Click Security > Global security in the navigation table on the left.
    4. Click the LTPA link as shown in Figure 1. Note that the administration and application security are enabled.
    5. Make sure that LTPA keys are not generated automatically. To check that automatic LTPA key generation is disabled, click Key set groups under the drop-down list shown in Figure 2. Click the key set group that you want to import the LTPA keys. Make sure the Automatically generate keys check box is unchecked as shown in Figure 3.
    6. Go back to the panel that is shown in Figure 2 (Security > Global security > LTPA)
    7. Enter the password used to export the LTPA key file in the Password and Confirm password fields. Enter the fully qualified filename for the key file in the Fully qualified key file name field as shown in Figure 4. The password is used to access the key file by both WebSphere cells so that both cells use the same LTPA keys.
    8. Click Import keys.
    9. Click Save.
    10. Restart all members of cell A.

Using the sample code

There are two project interchanges in the Download section:

  • PI_Start.zip: This is a startup project interchange file without any application security configuration.
  • PI_Final.zip: This is the final project interchange file, which has all the specified security configurations.

Each project interchange has five projects:

  • An SCA module (TestWebService), which has one Java component exposed as a web service to be deployed in the Process Server cell.
  • Two dynamic web projects, version 2.4 and version 2.5 (TestClient and TestClient2.5), which have the JSP client that calls the web service.
  • Two corresponding JEE applications (TestClientEAR and TestClient2.5EAR), which are deployed in a different WebSphere cell from the web service.

If you start with PI_Start.zip, you can deploy TestWebServiceApp to the Process Server test environment, and TestClientEAR or TESTClient2.5EAR to the other WebSphere cell. Then you can call the web service successfully from the JSP client. But, no authentication is done. Typically, in a production environment, both the JSP client and the web service are secure resources and the user must be authenticated and authorized to gain access to a resource. In the next section, we start with PI_Start.zip to protect the JSP client and the web service.


Adding a security role for dynamic web module 2.4

This section provides the steps to protect the JSP client so that the user must log in to gain access to TestClient resources. Perform these steps in the Business Integration perspective of Integration Developer only if you are using the 2.4 version of the test client web module.

  1. Expand the TestClient web project and double-click Deployment Descriptor: TestClient to open the web deployment descriptor. You will create one security role that can access any resource under the root context of TestClient.
  2. Click the Security tab at the bottom of the deployment descriptor editor.
  3. Click Add... in the Security Roles section to add a security role.
  4. Enter Web Service Caller in the Name field and click Finish.
  5. Click Add... in the Security Constraints section to add a security constraint.
  6. Enter Web Service Caller Constraints in the Constraint name field and click Next.
  7. Enter All Pages in the Resource name field. Click Add... in the Pattern section. Enter /* in the Name field. Click OK and click Finish.
  8. Click Add... in the Authorized Roles section. Enter Authorized Web Service Callers in the Description field and check Web Service Caller in the Role Name panel. Click Finish and save the deployment descriptor.
  9. Expand the TestClientEAR project and double click Deployment Descriptor: TestClientEAR.
  10. Click the Security tab at the bottom of the Application Deployment Descriptor editor.
  11. Click Gather.... Then click Web Service Caller and check the All authenticated users check box. Save the deployment descriptor.

If you deploy TestClientEAR, you are prompted for the user ID and password when you access the JSP client. You will also successfully call the web service. However, since the web service is not protected, the user credentials are not checked.


Adding a security role for dynamic web module 2.5

This section provides the steps to protect the JSP client so that the user must log in to gain access to TestClient2.5 resources. Perform these steps in the Business Integration perspective of Integration Developer only if you are using the 2.5 version of the test client web module.

  1. Expand the TestClient2.5 web project and right-click TestClient2.5 and click Open With > Web Application Deployment Descriptor Editor to open the web deployment descriptor. You will create one security role that can access any resource under the root context of TestClient2.5.
  2. In the editor, click Web Application and click Add.... A small window titled Add Item is launched. Click Security Role and click OK.
  3. Enter WS User in the Role name field.
  4. In the editor, click Web Application again and click Add.... A small window titled Add Item is launched again. Click Security Constraint and click OK.
  5. Click Add in the Authorization Constraint tab. Enter WS User over the highlighted New Item string.
  6. Click Web Resource Collection under Security Constraint. Click Add next to the URL Pattern box. Enter /* over the highlighted New Item string.
  7. Save the web.xml file.
  8. Right-click the TestClient2.5EAR project and click Java EE > Generate Deployment Descriptor Stub.
  9. Right-click the TestClient2.5EAR project again and click Java EE > Generate WebSphere Bindings Deployment Descriptor. The ibm-application-bnd.xml file is created and opened.
  10. Click Add... in the editor. A small window titled Add Item is launched. Click Security Role and click OK.
  11. Enter WS User in the Name field.
  12. Click Security Role under Application Bindings and click Add.... A small window titled Add Item is launched again. Click Special Subject and click OK.
  13. Select All Authenticated Users from the Type drop-down list and save the ibm-application-bnd.xml file.

If you deploy TestClient2.5EAR, you are prompted for the user ID and password when you access the JSP client. You will also successfully call the web service. However, since the web service is not protected, the user credentials are not checked.


Configuring WS-Security for the web service

This section provides steps to protect the web service so that the web service client sends the right WS-Security envelope with each web service call to invoke the web service successfully. Perform these steps in the Business Integration perspective of Integration Developer:

  1. Right-click the TestWebService project and click Open Deployment Editor.
  2. Right-click Web Service Exports and click Add > Web Services Security Extensions.
  3. Right-click Web Services Security Extensions and click Add > Web Service Description Extension. Click TestWebService and click OK.
  4. Right-click Port Component Binding and click Add > Server Service Configuration.
  5. Right-click Server Service Configuration and click Add > Request Consumer Service Configuration Details.
  6. Right-click Request Consumer Service Configuration Details and click Add > Required Security Token. Select LTPA Token and click OK.
  7. Enter LTPA in the Name field.
  8. Right-click Request Consumer Service Configuration Details and click Add > Caller Part. Select LTPA Token and click OK.
  9. Enter LTPA_Token_Con in the Name field.
  10. Right-click Web Service Exports and click Add > Web Services Binding Configuration.
  11. Right-click Web Services Binding Configuration and click Add > Web Service Description Binding, click TestWebService, and click OK.
  12. Right-click Port Component Binding and click Add > Request Consumer Binding Configuration Details.
  13. Right-click Request Consumer Binding Configuration Details and click Add Token Consumer.
  14. Enter LTPA_Token_Con in the Token consumer name field and select com.ibm.wsspi.wssecurity.token.LTPATokenConsumer from the Token consumer class list.
  15. Right-click Token Consumer and click Add > Part Reference.
  16. Enter LTPA in the Security token field.
  17. Right-click Token Consumer and click Add > Use Value Type. Select LTPA Token and click OK.
  18. Save the deployment descriptor.

Configuring WS-Security for client 2.4

This section provides all steps to configure WS-Security for the web service client in the web module V2.4. The runtime environment will construct the right WS-Security envelope with each web service call from the client. Perform these steps in the Business Integration perspective of Integration Developer only if you are using the 2.4 version of the test client web module.

  1. Expand the TestClient project.
  2. Double-click Deployment Descriptor: TestClient.
  3. Click WS Extension at the bottom of the deployment descriptor editor.
  4. Expand Request Generator Configuration > Security Token.
  5. Click Add. Enter LTPA in the Name field. Select LTPA Token from the Token type list. Click OK as shown in Figure 5.
    Figure 5. Security Token
    Security Token
  6. Click WS Binding tab at the bottom of the editor.
  7. Expand Security Request Generator Binding Configuration > Token Generator.
  8. Click Add. Make sure that you enter data as shown in Figure 6 and click OK when done.
    Figure 6. Token Generator
    Token Generator
  9. Save the deployment descriptor.

Configuring WS-Security for client 2.5

This section provides all steps to configure WS-Security for the web service client in the web module V2.5. The runtime environment will construct the right WS-Security envelope with each web service call from the client. Perform these steps in Integration Developer only if you are using the 2.5 version of the test client web module.

  1. Switch to the Java EE perspective.
  2. Click the Services browser.
  3. Right-click JAX-RPC > Clients > TestClient2.5: service. Click Show > Web Services Client Extension Editor.
  4. Follow the same steps detailed for client 2.4 after you opened its deployment descriptor.

Testing

To test the 2.4 client with the web service, deploy and start TestWebServiceApp and TestClientEAR and perform the following steps:

  1. Point the web browser to http://localhost:9081/TestClient. Change the host and port if needed.
  2. Enter a user ID and password when prompted. Enter admin for the ID and the corresponding password. You may enter another ID or password that is defined in both user registries for both WebSphere cells.
  3. If authenticated successfully, you are presented with the index.html page as shown in Figure 7.

To test the 2.5 client with the web service, deploy and start TestWebServiceApp and TestClient2.5EAR and perform the following steps:

  1. Point the web browser to http://localhost:9081/TestClient2.5. Change the host and port if needed.
  2. Enter a user ID and password when prompted. Enter admin for the ID and the corresponding password. You may enter another ID or password that is defined in both user registries for both WebSphere cells.
  3. If authenticated successfully, you are presented with the index.html page as shown in Figure 7.
    Figure 7. Test client
    Test client
  4. Enter your name in the text field and click Submit. If the web service call is successful, you see the greeting as shown in Figure 8.
    Figure 8. Web service call result
    Web service call result

If you do not see the greeting as shown in Figure 8, you most likely have some web service exception.

Listing 1 shows the SOAP request message sent from the JSP client. Listing 2 shows the SOAP response message generated sent from the web service. You can easily capture these messages using a tool such as TCP/IP Monitor in WebSphere Integration Developer.

Listing 1. SOAP request message
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
    <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/
     wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/
       oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="wsst:LTPA" 
       xmlns:wsst="http://www.ibm.com/websphere/appserver/tokentype/5.0.2"
       >IaUKTw8pTHgEuy01AUjdI72ngi6eWzpgr959Pq1FF9XYcWAPpn0gtQb2ISAjo+ 
       I7yqs7Ec7sw3Q8Tba0wKiYh/JRAWSPb/
       m+kVX7RDNdyY3rw93Ju+YPHOC3HGpmCIrVcRm38K0ZMoQUIu6+5nSiOB79K/
       uvmYKldMG3O0M10jZjOIP5t9NXlTJbtY09NmfNmsZUNPcgQvYkSfzgO802z7U1l3Ujm
       7b1sbJ8dg7KFklBm0XY0fDUXHa+hRRqFPvK82xA2RYlFg+dPRC2u09tXlqrULB/EKZj
       KMXs5mML7rffvi5KN8OuggnWkrYbEhO02eqxDwF56ewsWwUiKMYpAA/yvRf/kPrNr78
       Sg2LWc5He5H0PfM7f8ezntw4mUKp4SnT/NbsCCBHLqcJ1J5K+M3/Z35HL2kkm67lUTdMb
       BFhoIfsMT7HrMsTBgpFxcECzXpw/0rgLdQh7tKC8Tn09wEs4N2SFQQhAMuLa1K3fYyjjp
       XfaIET3akMe1QU+uAw4xE6Orr3llbYlcYWcnOyWTUrA3p7zsu49RAXylziqLp2bWSkWQVN
       PtfLoc1PZBUqUgr8/vFNB82Rket6YK0CeQWqC6Z8H6uFs2Y4N5JlEMHU6GzXDbqSzHcdlz
       Fq4vCUgfHo9ZzrIgpUZBrIIaI9GVw==</wsse:BinarySecurityToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <p449:hi xmlns:p449="http://TestWebService/TestJavaService">
      <name>Samir</name>
    </p449:hi>
  </soapenv:Body>
</soapenv:Envelope>
Listing 2. SOAP response message
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header/>
  <soapenv:Body>
    <se:hiResponse xmlns:se="http://TestWebService/TestJavaService">
      <greeting>Hi Samir</greeting>
    </se:hiResponse>
  </soapenv:Body>
</soapenv:Envelope>

Conclusion

This tutorial provided instructions on how to configure WS-Security for a JAX-RPC web service and its JSP client. The tutorial also provided all the steps to configure single sign-on between two WebSphere cells.


Acknowledgement

The author would like to thank Russell Butek for his review of this tutorial.


Downloads

DescriptionNameSize
Project interchange filePI_Start.zip48KB
Project interchange filePI_Final.zip50KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=607373
ArticleTitle=Configuring WS-Security for JAX-RPC web services in WebSphere Process Server V7
publish-date=01122011