# Step 6: Web Service Security

In this task you will use Web Service Security, sometimes referred to with the acronyms "WS-Security" or simply "WSSE", to secure the communications between the Investigate Web Service and a client web service TestClient.jws. (TestClient.jws is located in the folder WebServiceTutorialWeb/WSSETestClient/.) The two web services communicate through SOAP messages, as shown in the following diagram.

The communication will be secured by enhancing the SOAP messages with username/password tokens and encryption, as shown in the following diagram. TestClient's requests for a credit report will include a username and password, allowing the Investigate web service can authenticate TestClient. The credit report returned by Investigate will be encrypted before it is sent out over the wire, ensuring that the credit report is confidential.

These security enhancements are specified in a web service security policy file, or "WSSE file". WSSE files are XML files that specify the security behavior of your web service or web service control.

Note: that WSSE security is not the only option for securing a web service. SSL and Basic Authentication are other important options; for an example, see Java Control Tutorial Step 7: Transport Security.

The tasks in this step are:

- To associate the WSSE policy file with Investigate web service
- To associate a WSSE policy file with the Investigate control file
- To Test the Investigate web service

To Associate a WSSE Policy with the Investigate Web Service

In this task you will apply a web service security policy file (WSSE file) to the Investigate web service. This policy file specifies how incoming and outgoing SOAP message should be treated.

Before you begin this task, on the Application tab, double-click the file WebServiceTutorialWeb/investigateJWS/Investigate.wsse to view the file.

WSSE files contain two main elements. (1) The <wsSecurityIn> element specifies the kinds of security requirements that must be met by incoming SOAP messages. (2) The <wsSecurityOut> element specifies the sorts of security enhancements that should be added to outgoing SOAP messages.

The <wsSecurityIn> specifies that incoming SOAP messages must be accompanied by a valid username and password pair. If a SOAP message is sent to Investigate.jws without a valid username/password pair, then the SOAP message will be rejected by the web service and go unprocessed. The reason for setting up this security requirement is that it is important to know who is asking for credit reports: the Investigate web service doesn't want to be sending out credit reports to anonymous users. Note that this security strategy requires a registration mechanism to be fully implemented. This registration mechanism is outside the scope of this tutorial. But it would go something like this: candidate users would be required to provide some information about themselves: an email, a phonenumber, etc., and, upon verification of this information, the user would be given a username/password with which to login to the Investigate web service. For testing purposes we will use a test user already known to the WebLogic Security framework.

The <wsSecurityOut> element specifies that outgoing SOAP messages are to be encrypted before they are sent out over the wire. This will ensure that the credit report will remain confidential and can only be read by the intended recipient.

The <keyStore> element points to a Java KeyStore file (JKS file). This file contains the message recipient's public key with which the SOAP messages are encrypted. When data is encrypted in this way, only the matching private key, known only to the message recipient, can successfully decrypt the message, ensuring confidentiality of communication.

The follow diagram shows how Investigate.wsse controls the SOAP traffic coming into and out of Investigate.jws.

1. From the Window menu select Investigate.jws.
2. Click the Design View tab.
3. In Design View, select the picture of the Investigate web service. You can select the web service by clicking the picture's title bar, as shown below.
4. On the Property Editor tab, in the section labeled ws-security-service, on the right side of the file property. Click the ellipses button.
5. In the Property Text Editor dialog, enter Investigate.wsse, and click Ok.
6. On the Property Editor tab, in the section labeled ws-security-callback, on the right side of the file property, click the ellipses button.
7. In the Property Text Editor dialog, enter Investigate.wsse, and click Ok.
8. Press Ctrl+S to save your work.
9. Click the Source View tab.
10. Hover the mouse pointer over the green wavy line underneath "@jws:ws-security-service file="Investigate.wsse"
    Notice the tool tip that appears. This tool tip is warning you that your WSSE files are not encrypted. When you deploy a WSSE file to a production server, the passwords within the WSSE files appear in plain text. By leaving the passwords in plain text, you run the risk of allowing anyone with local access to the production server to view those passwords. To mitigate this risk, WebLogic Workshop has provided utilities to encrypt the passwords within WSSE files. (For detailed information on these utilities see the Help topic Securing WS-Security Passwords.) Note that it is not possible to successfully encrypt and run a WSSE file within a development environment, so we will ignore these warnings.

To Associate a WSSE Policy with the Investigate Web Service Control

In this task you will place a security policy on InvestigateControl.jcx, not on TestClient.jws. The reason you place a policy on the control file is because you are primarily interested in changing the way that TestClient.jws communicates with the particular web service Investigate.jws, but you are not interested in changing the way TestClient.jws communicates with any and all web services. This is a typical pattern in WSSE: to secure the communication between a client web service and its target web service, you place security policies on the target web service and on the target web service control file used by the client web service, but you leave the client web service without a policy of its own.
Before you complete this task double-click the file WebServiceTutorialWeb/WSSETestClient/InvestigateControl.wsse to view the file.

Notice that InvesigateControl.wsse has a security policy to complement Investigate.wsse. Incoming SOAP messages must be encrypted; and outgoing SOAP messages are enhanced with a username and password before they are send out over the wire. The following diagram shows how InvestigateControl.wsse controls the SOAP traffic coming into and out of the control file InvestigateControl.jcx.

1. On the Application tab, double-click the control file WebServiceTutorial/WebServiceTutorialWeb/WSSETestClient/InvestigateControl.jcx.
2. If InvestigateControl.jcx is not displayed in Design View, click the Design View tab.
3. On the Property Editor tab, in the section labeled ws-security-service, on the right side of the file property, click the ellipses button.
4. In the Property Text Editor dialog, enter InvestigateControl.wsse, and click Ok.
5. On the Property Editor tab, in the section labeled ws-security-callback, on the right side of the file property, click the ellipses button.
6. In the Property Text Editor dialog, enter InvestigateControl.wsse, and click Ok.
7. Press Ctrl+S to save your work. Press Ctrl+F4 to close the InvestigateControl.jcx file.

To Test the Investigate Web Service

In this task you will perform two tests. First you will test to see if the right passwords result in successful communication, then you will test to see if the wrong passwords result in failed communication.

Testing for Successful Communication

1. On the Application tab, double-click TestClient.jws.
2. Press Ctrl+F5 run TestClient.jws.
Your web service compiles and the Workshop Test Browser launches.
3. In the Workshop Test Browser, in the taxID field, enter the 9 digit number 222222222.

   Note: Use one of the following (9 digit) taxID's to test your web service throughout the tutorial:

   123456789, 111111111, 222222222, 333333333, 444444444, and 555555555.
4. Click the requestCreditReport button.
5. Click Refresh until the Message Log shows an entry for callback.onCreditReportDone.

Testing for Failed Communication

1. On the Application tab, double-click InvestigateControl.wsse.
2. Edit the the <wsSecurityOut> element to look like the following. Edit the code appearing in red. Note that you are intentionally entering the wrong password.

        <wsSecurityOut>
            <userNameToken>
                <userName>weblogic</userName>
                <password type="TEXT">wrong_password</password>
            </userNameToken>
        </wsSecurityOut>

3. On the Application tab, double-click TestClient.jws.
4. Press Ctrl+F5 to run TestClient.jws
5. In the Workshop Test Browser, in the taxID field, enter the 9 digit number 222222222.
6. Click the requestCreditReport button.
   Note that the invocation of the Investigate web service fails with the following exception.
7. Remember to re-edit the InvestigateControl.wsse file so that it sends the correct password.

Related Topics

Click one of the following arrows to navigate through the tutorial: