This section demonstrates capability of WSStub and WSConsumer (4.0) to send/receive secured SOAP messages using Encrypt Web Service Security action.

Scenario

Expose a simple Web Service using WSStub. Using Encrypt WS-Security mechanism, configure the WSStub component to encrypt messages from sender (WebserviceConsumer 4.0) of SOAP requests. Similarly, using Encrypt mechanism, configure the WebserviceConsumer component to decrypt messages from sender (WSStub) of SOAP responses.

Encryption/Decryption in WS-Security is usually done using public and private keys. For a sender (WSConsumer in this case) to encrypt, public key of receiver is needed. For a receiver (WSStub) to decrypt, it should have its own private key. Similarly, while sending response, WSStub should have WSConsumer’s public key and WSConsumer should have its own private key. These public and private keys can be stored in a keystore to use in the components. Generating private key and self-signed certificate is explained in the following sections.

Components used

• WSStub
• WebServiceConsumer 4.0
• Feeder
• Display

Basic Encryption settings

Create Password Callback Class

Password Callback Class is required for Encrypt security action to specify password for private keys in keystore. Private keys will be used to sign and/or decrypt a message.  To specify password, an implementation of javax.security.auth.callback.CallbackHandler is needed. A fully qualified class name of this implementation should be provided in Configuration Property Sheet (CPS).

Refer Creating Password Callback Class handler to create a Password Callback Class.

Generating Keystore

Keystore used for encryption and signature can either have self-signed or Ceritificate Authority (CA) signed certificates.

To generate a private key and a self-signed certificate, JDK’s keytool may be used.

Command to use to generate a single entry keystore which acts both as a private key and also a corresponding self-signed certificate containing the public key is as below.

Save this keystore file with name 'fiorano'

Creating Encryption Properties file

Create a text file with the following content and save it with name 'crypto':

Using the attributes (created files) in Web Service components

The below components contents need to be used in the manner as explained further:

• Keystore (fiorano.keystore)
• Encryption Properties file (crypto.properties)

WSStub

Copy the files mentioned above to the following location:

%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\classes

Figure 1: Encryption Files saved under classes for the components to access

WSConsumer

Add the files as resource by editing WSConsumer properties in the ServiceDescriptor.xml section in eStudio.

Setting up the Example

Configuring WSStub component

When WSStub receives a message secured by Encryption, it will verify the username and password. To verify, Encrypt action must be enabled in WSStub Configuration Property Sheet (CPS).

To configure WSStub component, perform the following action in eStudio:

1. Add a new Event Process with name 'WSSecurity_Example'.
2. Drag the WSStub component from the WebService category in the Micro Service Palette to the Fiorano Orchestrator.
   
   
   Figure 2: Adding WSStub component to Fiorano Orchestrator
    
3. Double-click the WSStub component in the orchestrator to open Configuration Property Sheet (CPS).
4. In the Configuration screen, click WSDL Configuration  button
   
   
   Figure 3: WSDL Configuration
    
5. In the WSDL Configuration dialog box, select Auto_created_Operataion present in the left pane to enable input (request) and output (response).
   
   
   Figure 4: Selecting Auto_created_Operation
    
6. Under Input tab, perform the below actions:
   1. Click Add button to add Name 'PartName1'.
   2. Click the Ellipsis button to open Select Type/Element dialog box. Select string option to configure the WSStub component to send a string message and then click OK.
      
      
      Figure 5: Adding Input attributes under Auto_created_Opretaion
       

7. Perform the same actions (as performed under Input tab) under Output tab to add a part 'PartName1' and 'string' under Name and Type/Element respectively and click OK in the WSDL Configuration dialog box.
   

   Icon

   Fiorano Mapper will be used to configure Route Transformation between Input and Output. This is explained in Configuring Route Transformation section.

8. Click Next to navigate to Security Configuration screen. Under WS-Security Configuration section, click WS-Security button to configure WS-Security settings.
   
   
   Figure 6: Security Configuration
    

9. In the Request WS-Security tab, perform the following actions:
   1. Under Security Actions section, select Encrypt check box, and clear the UsernameToken check box if it is selected.
   2. In Encryption Properties File text field under Encrypt section, provide name of the file (crypto.properties) where keystore properties are saved (refer the Creating Encryption Properties file section).

   3. In Password Callback Class under Username Token section, provide the class name (PWCallback).
      

      Icon

      If the class hav a package, then provide absolute class, that is, if the password Callback Class name is 'PWCallback' in package com.wsSecurity package, then absolute class name is 'com.wsSecurity.PWCallback'. This class will provide the necessary password which will then be added along with the User in Security Header of the message.

      
      Figure 7: Security settings in Request WS-Security

      Icon

      • Other actions such as the following can also be used:
        • UsernameToken as illustrated in the previous example Using UsernameToken Security Action.
        • A Timestamp value can be added to Request/Response to carry Created and Expires values indicating when a request or response is created and when it will expire. While adding timestamp to security header, Created element will have current time in GMT and Expires element will have current time + time to live in GMT.
        • Signature configuration is similar to that of Encryption. Here, client should have a keystore which has its own private key and server should have a keystore with client’s public key in it.
      • When more than one action is chosen, the order of actions can be managed by selecting the action and using the scroll buttons on the right side.

       

10. In Response WS-Security tab, select Encrypt check box (clear the UsernameToken check box if it is selected) under Security Actions section and provide the following values under Encrypt section:

    1. Encryption User: Value of org.apache.ws.security.crypto.merlin.keystore.alias (refer the Creating Encryption Properties file section) which is the encryption user name.
    2. Encryption Properties File: Name of the file (crypto.properties) where keystore properties are saved.

    3. Encryption Key Identifier: Set to 'DirectReference' since any self-signed certificate will not likely be present at the server and setting this option will send the certificate containing public key along with the request.

       
       Figure 8: Security settings in Response WS-Security

       Icon

       It is possible to encrypt certain elements in the request XML than the entire request. These elements can be configured using Encryption Parts property. Please refer to WSStub help for more information on this. For this example, leave it empty to encrypt the whole request.

        

11. Click OK to save WS-Security settings and click Finish to save WSStub component configuration.

12. In the three ports that get generated after WSStub configuration, connect the output port 'REQUEST' to the input port 'RESPONSE'.
    
    
    Figure 9: Connecting WSStub output port to input port

Configuring Route Transformation

To configure transformation between input and output port, perform the following actions in the Fiorano Orchestrator:

1. Right-click route1, point to Configure Transformation and select Mapper Project to open Fiorano Mapper editor.
   
   
   Figure 10: Opening Mapper Project editor
    
2. In the Output Structures panel in Mapper Project, click PartName1 element as it appears in Funclet View.
   
   
   Figure 11: Adding PartName1 to Funclet View
    
3. In the Funclet View panel, drag the function element Constant to the Funclet easel and double-click it to change the name to 'Secure_ACK' to give a logical meaning to the scenario (acknowledgement message of secured/encrypted message received).
   
   
   Figure 12: Adding Constant and renaming it
    
4. Connect the Source node of the constant 'Secure_ACK' to the destination node of PartName1.
   
   
   Figure 13: Connecting the Constant with PartName1
    
5. Click Save icon (or File >Save) to save the transformation configuration and close the Mapper Project editor.

Launching Web Service

To launch the webservice, perform the following actions:

1. Click Check Resource and Connectivity  icon (or press ALT+SHIFT+C) to check resource and connectivity.
2. Click Run Event Process  icon (ALT+SHIFT+R).
3. Right-click WSStub component and click Copy WSDL URL to copy the URL to clipboard, which is used in the next section.
   
   
   Figure 14: Copying WSDL URL to clipboard

Configuring WebSeriveConsumer component

Setting up the Security Configurations in WebServiceConsumer component, corresponding to the WSStub security configurations, is essential to access the webservice. To configure the component, perform the following actions:

1. Drag the WebserviceConsumer component from the WebService category in the Micro Service Palette to the Fiorano Orchestrator.
   
   
   Figure 15: Adding WebServiceConsumer to Orchestrator
    
2. Double-click the WebserviceConsumer component in the orchestrator to open Configuration Property Sheet (CPS).
3. In the Managed Connection Factory, click WSDL Ellipsis button. In Wsdl dialog box, paste the copied WSDL URL in the URL text field and click OK.
   
   
   Figure 16: Pasting the copied WSDL URL
    
4. Click Next. In the Interaction Configurations page, click WebService Operation Ellipsis button and select the operation with prefix 'Auto_created_Operation' from OperationName dialog box. Click OK to configure Web Service Security settings.
   
   
   Figure 17: Selecting Auto created operation
    
5. To verify the credentials, Encryption action must be enabled in WSConsumer too (as configured in WSStub). So, scroll down the screen and provide the following values under Security – Request section:
   1. Encryption User (fiorano)
   2. Encryption Properties filename (Request) (crypto.properties)

   3. Encryption Key Identifier (DirectReference)

      Icon

      • Provide same values as provided in the Response WSSecurity section in WSStub section.
      • Leave Encryption Parts property blank to encrypt the entire request.
      • Clear Is Password Required check box if it is selected.

      
      Figure 18: Security Request settings

       

6. Scroll down the screen and provide the following values under Security – Response section:

   1. Select Encrypt WS-Security (Response) check box.
   2. Encryption Properties filename (Response): Same value as provided in Encryption Properties filename (Request) above (crypto.properties).
      
      
      Figure 19: Security Response settings
       
7. Click Finish to save WebServiceConsumer component configuration.

Composing the Event Process and Configuring Feeder component

Drag a Feeder component and Display component from Util category in the Micro Service Palette to the WSSecurity_Example Fiorano Orchestrator.

1. Connect the components in the below manner:
   1. Feeder output port to WebServiceConsumer input port.
   2. WebServiceConsumer output port to Display input port.
      
      
      Figure 20: Connecting Feeder and Display to WebServiceConsumer component
       
2. Double-click Feeder component and perform the following actions to configure it:
   1. In the Message Type Configuration page, retain Output Message Format option as 'XML' and click the Connected Port Schemas button.
   2. In the Connected ports dialog box, select IN_PORT to enable connection between output port of Feeder and input port of WebServiceConsumer component. Click OK and then click Next.
      
      
      Figure 21: Enabling connection between input and output ports
       
   3. In the Message Details Configuration page, click the Generate Sample button to load sample input.
   4. Under No.of Repeatable elements to be generated section in the XSD Sample Generation Dialog window, replace max value '3' with '1' so that only one output is generated, and click OK.
      
      
      Figure 22: Reducing maximum number of output to '1'
       
3. Click Finish to save Feeder configuration.
   
   
   Figure 23: Loading Sample Input

Running the Example

To run the example, perform the following actions in the WSSecurity_Example event process:

1. Click Synchronize Event Process  icon to apply the modifications made to the event process that is already running. Two windows get opened for Feeder and Display components.
    
2. In the Feeder, click the Send button to send the message "PartName1".
   
   
   Figure 24: Sending message from Feeder
    
3. In the Display window, click the second tab () at the lower-left part of the window.
   EncryptKey header indicates that Username Token security action is enabled on response in WSStub and that WebserviceConsumer authenticates using values provided under Security-Response. PartName1 'SecureACK' can also be found.
   
   
   Figure 25: Message received in Display with the UsernameToken header and PartName1

Reference

Please note that the component options used in this example are specific to WS-Security. To explore other options present in WSStub and WebServiceConsumer components, refer the sections WSStub and WebServiceConsumer 4.0 respectively.