Offload WebSphere web services security tasks to IBM WebSphere DataPower SOA Appliances: Part 3: Using WebSphere DataPower Policy Framework

This article will cover how to use WebSphere DataPower SOA Appliances as the enforcement point of the WS-Security Policy. As well as discuss in detail how to offload Web Service Security Policy from WebSphere Application Server to WebSphere DataPower by using Policy Framework in the device. We will cover the Policy Framework which is currently supported in DataPower 3.7.2 and different ways to debug the Policy Framework. This article is part 3 of a series; the previous sections detailed the steps you have to perform to offload Web Services Security functionality to the WebSphere DataPower SOA Appliance.

Shiu Fun Poon (shiufun@us.ibm.com ), Senior Technical Lead, IBM

Shiu Fun Poon is an Engineer/Technical lead within the IBM WebSphere DataPower Security group. She is interested in all aspects of SOA.  She works on features that provide support of Web Services Security according to OASIS, W3C,WS-Security Policy and other additional security related features on the IBM WebSphere DataPower Appliance. She also contributes to the improvement of Reliable Availability Serviceability [RAS] of the appliance.  Before joining DataPower, she was the Tech Lead on the Domino Security Team.



Sid Misra (smisra@us.ibm.com), Software Test Specialist, IBM

Sid Misra is a Software Engineer in IBM WebSphere Business Events group in Bedford, Massachusetts. Prior to joining the WBE group, Sid was the SQA Team Lead at IBM DataPower where he worked on WS-Security Policy, WS-Policy and other security features. He holds a Masters of Science degree in Computer Science from Worcester Polytechnic Institute.



01 April 2009

Also available in Chinese Russian Portuguese Spanish

Prerequisites

To follow along with this article, make sure you have:

  • WebSphere Application Server 6.1 with Web Services Feature Pack (WSFP)
  • WebSphere DataPower XML Security Gateway XS40 or WebSphere DataPower Integration Appliance XI50, with firmware version 3.7.1 or greater
  • Security credentials for the Web Services Security in the form of JCEKS key stores or the private keys/public certificates required for the specified cryptographic operations

In this article

This article covers:

  • An overview of Policy Framework in DataPower
  • Configuring a WebSphere DataPower SOA Appliance using a Policy Framework to perform the Web Service Security processing for a WebSphere Application Server deployed Web Service
    - The Security Policy to be offloaded from the WebSphere Application Server is “WSSecurity Default”
  • Different methods in WebSphere DataPower to attach a Security Policy
  • Use of Policy Parameters screen to provide runtime credentials needed to enforce Security Policy
  • Information for the available Security Policy Parameters
  • Troubleshooting

Introduction

WebSphere DataPower SOA Appliance, firmware version 3.7.1, extends its support of WS-Security Policy. WS-Security Policy provides a policy language useful in a governance model. It binds both service consumer and provider on a set of security requirements to ensure the message exchange patterns between the 2 parties meet the integrity and confidentiality required. WS-Security Policy is a set of metadata used to express a combination of security requirements. WebSphere DataPower supports WS-Security Policy with a Web Service Proxy. We will cover steps on how to configure a Web Service Proxy to enforce a WebSphere Application Server’s Security Policy.

Both WebSphere Application Server 6.1 with WSFP and WebSphere DataPower 3.6.1 or greater support WS-Security Policy. WebSphere DataPower firmware 3.6.1 or greater supports 3 namespaces of WS-Security Policy.

WebSphere DataPower supports two process modes for a web service Security Policy, filter and enforce. In filter mode, the message will not be altered by the device, and only the syntax of the message is checked. In enforce mode, the message may be altered to verify whether the message meets the security requirement. The following table provides a contrast of different mode and direction of the traffic.

Since WebSphere DataPower SOA Appliances bridges between the front side caller and the back-end service, the direction of the message also impacts the actions taken by the device to conform to a WS-Security Policy Assertion.

Table 1. Filter versus Enforce Mode
WS-Security Policy AssertionFilter ModeEnforce Mode
RequestResponseRequestResponse
Integrity Assertion
sp:SignedElements
Reject client’s request if the specified element is not signed with the specified algorithmReject server’s response if the specified element is not signed with the specified algorithmFilter + Reject the client’s request message is signature is not verified.Filter + Sign the element in server’s response message if it is not signed by the server.
Confidentiality Assertion
sp:EncryptedElements
Reject client’s request if the specified element is not encrypted with the specified algorithm. Since WebSphere DataPower will not decrypted incoming request in filter mode, the check is to make sure the element does not exist in the clear.*Reject server’s response if the specified element is not encrypted with the specified algorithm. WebSphere DataPower will not decrypted incoming request in filter mode, the check is to make sure the element does not exist in the clear.Filter +Reject the client’s request message if WebSphere DataPower cannot decrypt the message or the element does not exist in the decrypted request message.Filter +Encrypt the element in server’s response if the element is not encrypted already.

* In a Web Service Proxy, if the soap:Body of the incoming request message is encrypted, WebSphere DataPower will automatically decrypt the message, in order to receive a decrypted soap:Body. Information from soap:Body is used to determine the encrypted wsdl:operation message.

WebSphere Application Server 6.1 with WSFP provides a list of policy sets for supporting different integrity and confidentiality requirements of the Web Service application. In this exercise, the WebSphere DataPower SOA appliance will be used to offload the process intensive security requirement of “WS-Security Default policy set”. This allows the WebSphere Application Server 6.1 to handle the resource intensive application and business logic. And to that end, WebSphere DataPower will be hosting the web service end point. The device will only forward the message to the back-end Application Server once the security requirement on the requested message is satisfied. WebSphere DataPower will perform any necessary transformation on the response data from Application Server, according to the WS-Security Policy, before it sends the response back to the caller.

Figure 1. Data Traffic before offloading WS-Security Default policy set to a WebSphere DataPower SOA Appliance
Data Traffic before offloading WS-Security Default policy set to DataPower
Figure 2. Data Traffic after offloading WS-Security Default policy to a WebSphere DataPower SOA Appliance
Figure 2 : Data Traffic after offloading WS-Security Default policy set to DataPower

WAS “WS-Security default policy set” contains the following list of security requirements:

  • Both request and respond message must be signed/encrypted with X509v3 token
    - The certificate used for signing must be referenced with DirectReference
  • Algorithm to be used for signing and encrypting : SHA1, AES128
  • wsse:Timestamp must exist in both request/response message, and Signature must cover the wsse:Timestamp element
  • The message must be signed first. The signed message will be encrypted.
  • The following elements must be signed: wsse:Timestamp, any Header elements with WS-Addressing, and soap:Body
  • The following elements must be encrypted: dsig:Signature and soap:Body

Prerequisite for offloading the WS-Security Default Policy Set

Before we can offload the WS-Security default policy and bindings from WAS to a WebSphere DataPower SOA Appliance, the following is required:

  • A working application between a WAS client and a WAS server using WS-Security default policy. The WS-Addressing Policy needs to disabled. This is accomplished by making a copy of the “WSSecurity default”, and remove WS-Addressing support.
Figure 3. Disabling WS-Addressing
Figure 3. Disabling WS-Addressing

Click to see larger image

Figure 3. Disabling WS-Addressing

Figure 3. Disabling WS-Addressing
  • Using the WSDL file for the web service from above application. We are going to use the EchoService from WAS
  • The public and private key used by WAS application server for signing the message. The private key is used to decrypt the request message
  • The public key of the WAS client which is used for encrypting the response message, and it is also used to verify the request message

Configure WebSphere DataPower for the WS-Security Default Policy Set

  1. Login into the DataPower SOA Appliance using WebGUI Management Interface (https://[ip]:9090)
  2. Select Web Services Proxy
Figure 4. Control Panel
Figure 4. Control Panel
  1. Create new web service proxy, click the “Add” button
Figure 5. Configure Web Service Proxy "Add"
Figure 5. Configure Web Service Proxy Add
  1. Use “EchoService” as proxy name. Select “Create Web Service Proxy”
Figure 6. Configure Web Service Proxy
Figure 6. Configure Web Service Proxy
  1. File in Basic information for “Configure Web Service Proxy”
  2. Web Service Proxy WSDLs : Add WSDL (no change from default)
  3. WSDL File URL
    - Select “Upload” to upload the WDSL file
Figure 7. Upload WSDL File
Figure 7. Upload WSDL File
  1. Use WS-Policy References : on
  2. WS-Policy Parameter Set : Select ‘+’ to create a new WS-Policy Parameter Set
    - WebSphere DataPower will offload WAS security functionality, so for WS-Security
    - By default, the following parameters are required:
    - Signing Key/Signing Certificate : they are used to generate a signed response on the response message
    - Encryption Certificate : it is used to encrypt the response message
    - Verification Valcred : it is used to verify the signature on the request message
    - Remove Security Header : given the device will manage all the security aspect of the message, the WS-Security Header has to be removed from the SOAP Message before it is sent to WAS. If this is not completed, WAS will try to validate the message based on the WS-Security Header.
Figure 8. Policy Parameters
Figure 8. Policy Parameters

* If parameter is not provided for enforcing a given Security Policy Assertion, the WebSphere DataPower Framework will automatically convert the enforcement for that Security Policy Assertion to filter mode. For example, in order to *enforce* sp:SignedParts on the response side of the traffic, ‘Signing Certificate’ and ‘Signing Key’ should be specified. If they are not provided, then the device will convert the execution mode for sp:SignedParts to filter. So if back-end server does not provide a signed response per sp:SignedParts requirement, the response will be rejected by the device and it will not forward to the calling client.

  1. WS-Policy Enforcement Mode : enforce and Select "Next"
Figure 9. WS-Policy Enforcement Mode
Figure 9. WS-Policy Enforcement Mode

Click to see larger image

Figure 9. WS-Policy Enforcement Mode

Figure 9. WS-Policy Enforcement Mode
  1. Next is to set up the “Front Side Handler” and back-end endpoint for the Web Service Proxy
Figure 10. Front Side Handler
Figure 10. Front Side Handler

Click to see larger image

Figure 10. Front Side Handler

Figure 10. Front Side Handler
  1. Select ‘+’ under “Local Endpoint Handler” -> Select “HTTP Front Side Handler”
Figure 11. Select “HTTP Front Side Handler”
Figure 11. Select “HTTP Front Side Handler”
  1. Select port 8855 (Name : http8855 & Port Number : 8855)
  2. Select “Apply”
Figure 12. Configure “HTTP Front Side Handler”
Figure 12. Configure HTTP Front Side Handler
  1. Select “Add” to add the “Local Endpoint Handler”
Figure 13. Add "Local Endpoint Handler"
Figure 13. Add Local Endpoint Handler
  1. Fill in the Remote information:
    - Protocol : http
    - Hostname (IP Address) : WAS Server’s IP address (9.33.82.80)
  2. Select “Next”
Figure 14. Remote Data
Figure 14. Remote Data
  1. At this point, the Web Service Policy should be up. Now we have to attach the policy to this Web Service Policy. Select “Policy” Tab.
Figure 15. Policy Tab
Figure 15. Policy Tab
  1. The policy that matches the WAS WS-Security Default is “wsp-sp-1-1-was-wssecurity-default.xml”. This policy contains 3 policy fragments, binding-policy, request_parts and response_parts. We will take advantage of the fact that both request_parts and response_parts are the same. WS-Security Policy specification is very specify about which binding can be used in which Policy Subject. If you are going to deviate from the following steps, please make certain you are attaching the policy assertion to the right policy subject. Select “yes” to “Show portType and binding nodes:”.
Figure 16. Show portType and Binding Nodes
Figure 16. Show portType and Binding Nodes

Click to see larger image

Figure 16. Show portType and Binding Nodes

Figure 16. Show portType and Binding Nodes
  1. Attach wsp-sp-1-1-was-wssecurity-default.xml#binding-policy to Endpoint Policy Subject. In this case, we will attach it to wsdl:portType element
Figure 17. Additional Policy Sources #binding-policy
Figure 17. Additional Policy Sources
  1. Attach wsp-sp-1-1-was-wssecurity-default.xml#request_parts to Operation Policy Subject, such that both wsdl:input and wsdl:output will use the same policy. In this case, we will attach it to wsdl:operation
Figure 18. Additional Policy Sources #request_parts
Figure 18. Additional Policy Sources
  1. At this point, we will turn off the schema validation for the response message. According to the WS-Security Default policy, the response message has to be encrypted, and thus it will failed the schema validation done by Web Service Proxy. There are 2 ways to handle this, one is with exception map, and another is to disable the schema validation for the response. We will use the second option. This can be done by clicking on checkbox in the WebGUI. Uncheck “Schema validate response messages”.
Figure 19. Disable Schema Validation Response Message
Figure 19. Disable Schema Validation Response Message
  1. Click "Done"
  2. Create an ID Credential to relate both the was-server public and private key for WAS.
  3. From the Control Panel; select Keys & Certs Management
  4. Identification Credentials - for identifying self
  5. Select "Add"
    - Name : was-server
    - Crypto Key : was-server
    - Certificate : was-server
    - Select "Apply"
Figure 20. Crypto Identification Credentials
Figure 20. Crypto Identification Credentials

Due to Web Service Proxy has to decrypt the soap message for soap:Body, before it can determine which operation to route the incoming traffic to. There are 2 ways to provide key information that Web Service Proxy can use for the auto decryption. And creating an identity credential is the preferred method.

  • Define an identity credential which will related a public certificate to its corresponding private key
  • Specify a “Decrypt Key” in “Proxy Settings” of Web Service Proxy
Figure 21. Decrypt Key
Figure 21. Decrypt Key

Disable WS-Security Default Policy on WAS web service Provider

Please make certain you have stopped the Service Provider and start the Service Provider. This is to ensure the Service Provider is not running with any WS-Security Default Policy or binding.

Figure 22. Service Providers
Figure 22. Service Provider

Modify the Test Program to use WebSphere DataPower

Again, please make certain you have stop the Service Provider and start the Service Provider. This is to ensure the Service Provider is not running with any WS-Security Default Policy or binding.

Figure 23. Service Providers
Figure 23. Service Provider

Modify the testing program to use WebSphere DataPower as the Service URI

  • Modify “Service URI:” to the Web Service endpoint which is hosted by DataPower.
  • Click “Send Message”
  • The request message echo response appears
Figure 24. General Message Response
Figure 24. General Message Response

Click to see larger image

Figure 24. General Message Response

Figure 24. General Message Response
Table 2. List of runtime parameters for WS-Security Policy for Web Service Proxy
Parameter NameDescriptionWS-Security Policy Assertion
Kerberos Client Principal[response] Use to sign messagesp:KerberosToken
Kerberos Server Principal[request] Use to verify signature on the messagesp:KerberosToken
Kerberos Keytab[request/response] Keytab file for Kerberossp:KerberosToken
Verification Valcred[request] Use to verify the signature which is signed with asymmetric algorithmsp:SignedParts
sp:SignedElements
sp:SignedSupportingTokens
sp:SignedEncryptedSupportingToken
sp:OnlySignEntireHeadersAndBody
Signing Certificate[response] For generating KeyInfo for the Signing Key, the corresponding Signing Keysp:SignedParts
sp:SignedElements
sp:SignedSupportingTokens
sp:SignedEncryptedSupportingToken
sp:OnlySignEntireHeadersAndBody
Signing Key[response] For signing the response messagesp:SignedParts
sp:SignedElements
sp:SignedSupportingTokens
sp:SignedEncryptedSupportingToken
sp:OnlySignEntireHeadersAndBody
Encryption Certificate[response] For encrypting the response messagesp:EncryptedParts
sp:EncryptedElements
sp:ContentEncryptedElements
sp:EncryptedSupportingToken
sp:SignedEncryptedSupportingToken
Decryption Key[request] For decrypting incoming request message. Given Web Service Proxy will auto-decrypt the message when soap:Body is encrypted. The use of this parameter is limited to other encrypted elements which are encrypted with different keysp:EncryptedParts
sp:EncryptedElements
sp:ContentEncryptedElements
sp:EncryptedSupportingToken
sp:SignedEncryptedSupportingToken
AAA Policy[response] For generating a required token for response messagesp:UsernameToken
sp:SamlToken
sp:SecurityContextToken
sp:SecureConversationToken
sp:SignedSupportingTokens
sp:EncryptedSupportingTokens
sp:SignedEncryptedSupportingToken
Remove Security Header[request] This removes WS-Security Header, wsse:Security, from request message before the device sends the message to back-end server-
Timestamp Expiration Override Period[response] This overrides the default Timestamp expiration during signing, default is 300 secondssp:SymmetricBinding
sp:AsymmetricBinding
sp:TransportBinding
Interoperable with[request/response] This toggles vendor specified code for interoperable concern-
WebSphere DataPower Specific Features[request] Does not verify timestamp during signature verification

[response] Use Dynamic Signing Certificate – this use the signing certificate from the request message to encrypt the response message
-

Debugging

  • Turn on probe for the Web Service Proxy

The figure below shows a probe capture of a transaction (#68802), in which both input and output message contain UsernameToken11.

There were two calls under request. Each call represented an alternative in the policy. The first call is checking for UsernameToken10. Given that the message contains a Uernametoken11, the message failed the policy. After the message fails the first alternative (call), the policy framework automatically triggers the second alternative (call). The second alternative is checked for UsernameToken11. And so it succeeded.

Under the response, there were 3 calls. The first call was a check for soap fault. Given the message was not a SOAP fault; it failed this check. (Note that on the response side, the first call is always a check for SOAP fault, such that if a SOAP fault is returned from the back-end, no policy is applied to the SOAP fault, and the SOAP fault can be returned to the caller intact.) The message also failed the second call due to checking for UsernameToken10. However the message passed the third call, which checked for UsernameToken11.

Figure 25. Transaction Listing
Figure 25. Transaction Listing
  • Use the Command Line

Use the show policy-config command to retrieve the multiple rules and actions that are created for the policy that is associated with the Web Service Proxy. Invoke this command with the following format for a specific execution: show policy-configexecution number

Without execution number the command returns details about all of the runtime rules and actions that are created to fulfill a policy requirement.

You can also use the show policy-attachment and show policy-parameter commands to retrieve the configuration details for the Policy Attachments and Policy Parameter objects, respectively.

To determine the execution number, use the WebGUI. From the WebGUI, select STATUS -> Web Services -> Web Services WSDLs. In this case, we are interested in 85.

Figure 26. Show Policy
Figure 26. Show Policy

Click to see larger image

Figure 26. Show Policy

Figure 26. Show Policy

Output from show policy-config 85 is listed below. There are multiple rules and actions created for the policy associated with the WSP.

  • Rule operation_85_1-2-process-resp is on for the response side of the traffic
  • Rule operation_85_1-2-req is on the request side
  • Action operation_85_1-1-1-request-rule-UsernameToken is a filter, the filter checks for a UsernameToken on the request side
  • Action operation_85_1-1-1-response-rule-filter is a filter check on the response side

From the highlighted portion of the name, you can tell that there is a naming convention that conveys the directional information about the generated rule or action.

Listing 1. Show policy-config Output
xi50[ws-security-policy](config)# show policy-config 85
Rule Name         Details
  ---------         -------
  operation_85_1-2-process-resp [up] --- type: response ---
                    filter INPUT store:///required-elements-filter.xsl NULL
                    results INPUT    


  Rule Name         Details
  ---------         -------
  operation_85_1-2-req [up] --- type: request ---
                    filter INPUT store:///required-elements-filter.xsl NULL
                    results INPUT    

	...............  More generated rule ............

action: operation_85_1-1-1-request-rule-UsernameToken [up]
-----------------------------------------------------
 admin-state enabled
 type filter
 input INPUT
 transform store:///required-elements-filter.xsl
 output NULL
 named-inouts default
 parameter RequiredElementXPaths "/*[local-name()='Envelope' and 
   (namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' or 
namespace-uri()='http://www.w3.
 transactional off
 soap-validation body
 sql-source-type static
 asynchronous off
 results-mode first-available
 retry-count 0
 retry-interval 1000 msec
 multiple-outputs off
 iterator-type XPATH
 timeout 0 msec

action: operation_85_1-1-1-response-rule-filter [up]
-----------------------------------------------
 admin-state enabled
 type filter
 input INPUT
 transform store:///required-elements-filter.xsl
 output NULL
 named-inouts default
 parameter RequiredElementXPaths "/*[local-name()='Envelope' and 
  (namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' or 
namespace-uri()='http://www.w3.
 transactional off
 soap-validation body
 sql-source-type static
 asynchronous off
 results-mode first-available
 retry-count 0
 retry-interval 1000 msec
 multiple-outputs off
 iterator-type XPATH
 timeout 0 msec

	...............  More generated action ............

Output from the show policy-attachment command is listed below. Policy attachment lists out the externally attached policy to a given Web Service Proxy Service. In the following example, policy, wsp-sp-1-1-sign-parts.xml, is attached to {urn:GoogleSearch}GoogleSearchService. This implies that all of the messages that are associated with {urn:GoogleSearch}GoogleSearchService must conform to this policy, and that the action must use the enforce mode.

Listing 2. Show policy-attachment Output
policy-attachments: test_GoogleSearch.wsdl [up]
------------------------------------------
 admin-state enabled
 enforcement-mode enforce
 policy-references on
 external-policy service {urn:GoogleSearch}GoogleSearchService   
store:///policies/templates/wsp-sp-1-1-sign-parts.xml

policy-attachments: SecPolicyAttachment-enforce [up]
-----------------------------------------------
 admin-state enabled
 enforcement-mode enforce
 policy-references on
 ignore-attachment-point service {tns1}service

policy-attachments: SecPolicyAttachment-filter [up]
----------------------------------------------
 admin-state enabled
 enforcement-mode filter
 policy-references on
 ignore-attachment-point service {tns1}service

Output from the show policy-parameter command is listed below. Policy parameters are needed for enforcement.

Listing 3. Show policy-parameter Output
policy-parameters: SecPolicyParameterAliceCertificate [up]
-----------------------------------------------------
 admin-state enabled
 parameter {http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512}
ws-secpol-Certificate name:secpol-cert-alice
 parameter {http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702}
ws-secpol-Certificate name:secpol-cert-alice

policy-parameters: SecPolicyParameterAliceDecryptKey [up]
----------------------------------------------------
 admin-state enabled
 parameter {http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512}
ws-secpol-DecryptKey secpol-key-alice
 parameter {http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702}
ws-secpol-DecryptKey secpol-key-alice

Resources

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 SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services, WebSphere
ArticleID=379710
ArticleTitle=Offload WebSphere web services security tasks to IBM WebSphere DataPower SOA Appliances: Part 3: Using WebSphere DataPower Policy Framework
publish-date=04012009