Securing a Web Service

• Overview
• Creating a Security Policy
• Applying a Security Policy
• Adding a User
• Testing a Security Policy
• Chaining Policies Together
• Troubleshooting

Overview

This topic explains how to use Policy Studio to create a simple security policy, how to assign this policy to the ComInfoService Web Service, and how to add a new user. It then shows how to test this security policy using Service Explorer. Finally, this topic shows how to chain policies together and assign them using Service Manager.

Policy Studio enables you to perform the full range of Enterprise Gateway configuration and management tasks (for example, create and assign policies, import Web Services, optimize configuration settings, and manage deployments). Service Manager enables you to use your browser to perform a subset of the tasks performed in Policy Studio (for example, reuse policies created in Policy Studio, and assign them to imported Web Services).

This topic assumes that you have already performed the steps described in the following topics:

1. Starting the Enterprise Gateway
2. Registering a Web Service
3. Monitoring a Web Service

Creating a Security Policy

To create a simple WS-Security authentication policy using Policy Studio, perform the following steps:

1. Click the Policies button on the left to view the Policies tree.
2. In the Policies tree, right-click the Policy Library node, and select Add Policy.
3. In the Policy dialog, enter WS-Security UsernameToken AuthN in the Name field.
4. Select Security from the Category drop-down list.
5. Click OK. The new policy is added to the tree and displayed as empty on the blank Policy Studio canvas.
6. Click the Authentication category on the right of the canvas, and scroll down to select the WS-Security Username Token filter.
7. Drag and drop the WS-Security Username Token filter on to the canvas.
8. Enter the following details in the Configure a new WS-Security Username Token filter dialog:

Actor	Select Current actor/role only from the drop-down box.
Drift	Specify a value of 5 seconds drift time to allow for a difference between the clock on the machine hosting the Enterprise Gateway and the machine hosting the Web Service.
Validity Period	Specify a value of 5 mins.
Repository Name	Select Local User Store from the drop-down box.

9. Click Finish. The new filter is added to the policy on the canvas.
10. Right-click the filter, and select Set as Start. This sets the WS-Security Username Token filter as the start of this simple policy circuit.

Applying a Security Policy

To apply the newly created WS-Security authentication policy to the ComInfoService Web Service using Policy Studio, perform the following steps:

1. In the Policies tree on the left, expand the Generated Circuits node, and select the Service Handler for 'ComInfoServiceService' to display the service handler on the canvas.

   ComInfoService Handler

2. Double-click the service handler to open it.
3. Click the Message Interception Points tab.
4. On the 1. Request from Client tab, click the button on the right to choose a policy to execute before the operation-specific policy.

   Configure Service Handler

5. In the dialog, select the WS-Security UsernameToken AuthN policy.
6. Click OK.
7. Click Finish.

You can also use Service Manager to assign policies to Web Services. For details, see Managing Web Services.

Adding a User

To add a sample user to the local Enterprise Gateway user store to test the WS-Security UsernameToken AuthN policy, perform the following steps:

1. Click the Users button at the bottom left to view the Users tab.
2. Select the User Store node to display the Users tab on the right.
3. In the Users tab, click the Add button.
4. In the Add User dialog, enter an example User Name and User's Password, and confirm the password. You need to remember this password for the next step.
5. Click OK.
6. Click the Deploy button in the toolbar to deploy these updates to the Enterprise Gateway. Alternatively, press F6.

Testing a Security Policy

If you have Service Explorer installed, you can test the WS-Security UsernameToken AuthN policy as follows:

1. Click the triangular green send button to send the message to the virtualized Web Service through the Enterprise Gateway. The Response tab displays an HTTP 500 ERROR and a MessageBlocked SOAP fault. The Real-time monitoring console also displays the message as blocked. This is because the request message now requires a WS-Security UsernameToken, and without this token the message is blocked by the Enterprise Gateway.
2. Select Security -> Insert WS-Security UserName.
3. In the Insert WS Security UserName dialog, specify the following settings in the Credential details:

User name	Enter the user name that you added in Policy Studio.
Include Password	Select this checkbox.
Password	Select this radio button. In the text box, enter the password that you specified in Policy Studio.
Clear	Select this radio button.

4. Click Finish to insert the WS Security UserName token into the request message.
5. Click the send button to send the message to the virtualized Web Service through the Enterprise Gateway. The Response tab should display an HTTP 200 OK message and the desired response message. The Real-time monitoring console also displays the message as passed.

The following example shows the SOAP header with the WS-Security UsernameToken that is inserted into the request message in Service Explorer:

<soap:Header>
  <wsse:Security
    xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
     oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
       oasis-200401-wss-wssecurity-utility-1.0.xsd"
      wsu:Id="Id-000001289118bc76-0000000000a2f435-2">
      <wsse:Username>joeuser</wsse:Username>
      <wsse:Nonce EncodingType="utf-8">
           pp69a0hHBz0msnYiZ5rTAQ==
      </wsse:Nonce>
      <wsse:Password
        Type="http://docs.oasis-open.org/wss/2004/01/
         oasis-200401-wss-username-token-profile-1.0#PasswordText">
           joepwd
      </wsse:Password>
      <wsu:Created>2010-05-13T09:57:17Z</wsu:Created>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>      

The following example shows the WS Security UserName Token filter displayed in the message path in the Real-time monitoring console:

Chaining Policies Together

You can use Service Manager to chain policies together into a composite policy. This is equivalent to a policy shortcut chain in Policy Studio. To create a composite ComInfoSecurity policy using Service Manager, perform the following steps:

1. Enter your Service Manager login details to reconnect to the Enterprise Gateway server.
2. Click Discard to obtain the latest Enterprise Gateway configuration.
3. In the Policies window on the right, right-click the Policy Library node, and select Add Policy.
4. In the Policy Details below, on the Settings tab, enter ComInfoSecurity in the Name field.
5. Select Security from the Category drop-down list.
6. Click the Sub-Polices tab, and drag and drop the XML Threat Policy and WS-Security UsernameToken AuthN policies from the Policy tree.
7. Click Deploy to deploy this configuration to the Enterprise Gateway.
8. Click Yes.

Alternatively, you can also use Policy Studio to create a policy shortcut chain. For details, see Policy Shortcut Chain.

Assigning the Policy in Service Manager
To assign the composite ComInfoSecurity policy to the ComInfoService Web Service using Service Manager, perform the following steps:

1. In Web Services window on the left, double-click the ComInfoServiceService node.
2. In the Edit Web Service section below, click the Policies tab.
3. Drag and drop the ComInfoSecurity policy from the tree in the Policies screen on to the Request interception point in the diagram or in the table below. This replaces the WS-Security UsernameToken AuthN policy previously assigned in Policy Studio.
4. Click Deploy to deploy this configuration to the Enterprise Gateway.
5. Click Yes.

The ComInfoSecurity policy is now assigned to the ComInfoService Web Service, and is run on the request received by the Enterprise Gateway from the client. For more information on using Service Manager to assign polices to Web Services, see Managing Web Services.

Testing the Policy in Service Explorer
If you have Service Explorer installed, you can also test the composite ComInfoSecurity policy using the steps outlined in Testing a Security Policy. In the Service Explorer Request tab, delete the existing wsse:UsernameToken before inserting the new WS-Security UsernameToken.

The following example shows the composite ComInfoSecurity policy displayed in the message path in the Real-time monitoring console:

Switching between Service Manager and Policy Studio
When you deploy updates to the Enterprise Gateway in Service Manager, you must reload the active Enterprise Gateway configuration in Policy Studio to view updates made in Service Manager. For example, when you close and reload the active configuration in Policy Studio, the ComInfoSecurity policy should be displayed under the Policy Library node in the Policies tree in Policy Studio. It should also be displayed under the Generated Circuits node in the Service Handler for 'ComInfoServiceService'. When you double-click the Service Handler, the ComInfoSecurity policy should be displayed on the Message Interception Points tab as the Request from Client policy.

Similarly, when you deploy updates to the Enterprise Gateway in Policy Studio, you must reconnect and discard your configuration in Service Manager to view these updates made in Policy Studio. This ensures that Service Manager is synchronized with the active Enterprise Gateway configuration.

Troubleshooting

When you have completed these steps to secure the example Web Service, the next steps are to learn how to configure tracing for the Enterprise Gateway, and how to configure logging for specific message filters. For details, see Troubleshooting.