In 2002, a small group of IBM colleagues met with a team from Microsoft write a document describing a phased rollout of XML security technology specifications with a vision to support a variety of security scenarios for web services. Today, most would agree that the bottom of the stack is solid. SOAP and WS-Security are recognized and implemented standards. WS-Policy and WS-Trust, have also become standards in W3C / OASIS respectively and are common features in web services security environments. WS-Privacy, WS-Federation and WS-Authorization have encountered market competition. The web services model was intended to provide SOA application developers a common set of security services to utilize independently or in a composite application, rather than having each application/service code its own security. Two other pieces of the roadmap have recently been standardized-- WS-SecureConversation and WS-Security Policies. WS-Secure Conversation describes how to establish session keys, derived keys, and per-message keys so that 2 parties can communicate securely over a long running transaction or conversation as an optimization over negotiating per message security. Secure Conversation was intended to allow a long running exchange building on WS-Security and WS-Trust. The roadmap document defined a set of scenarios that are enabled by Secure Conversation (Enabling Federation , Supporting Validation Services , Delegation , Access Control) and the work described here by the WebSphere DataPower development and field organizations is evidence of its reality.
Today, most would agree that the bottom of the stack is solid. SOAP and WS-Security are recognized and implemented standards. WS-Policy and WS-Trust, have also become standards in W3C / OASIS respectively and are the common components in most web services security environments. WS-Privacy, WS-Federation and WS-Authorization have encountered market competition from a range of initiatives related to solutions for Single Sign On, and identity centric programming models like Liberty/SAML. Also the continuing evolution of Web applications from static Web pages to REST and AJAX based access patterns with dynamic content have encouraged Web/cloud developers to explore alternative security strategies such as OAuth, OpenID. The web services model was intended to provide SOA application developers a common set of security services to utilize independently or in a composite application, rather than having each application/service code its own security via APIs. However, there are still a lot of APIs and strategies for developers and with the continuing demand for social networking Web applications, the choice of "Web application" paradigm vs "web service" paradigm continues.
Recently two other pieces of the roadmap have been standardized, WS-SecureConversation and WS-Security Policies. WS-Secure Conversation describes how to establish session keys, derived keys, and per-message keys so that 2 parties can communicate securely over a long running transaction or conversation as an optimization over negotiating per message. Secure Conversation was intended to allow web services to describe how a service can securely exchange context (some collection of claims about security attributes and related data) building on the concepts of security token issuance and exchange mechanisms defined in the basic WS-Security and WS-Trust specifications. Using these mechanisms a web service can enable a long running exchange and might layer this “conversation” on an existing http transport level protocol. This allows a long running exchange to use symmetric cryptographic operations to protect the messages during an established session. Symmetric cryptographic operations are efficient than a standard asymmetric cryptographic operations.
There are many scenarios that require the security capabilities of Secure Conversation. The roadmap document defines a set of these that are enabled by Secure Conversation:
- Enabling Federation
- Supporting Validation Services
- Access Control
Use case for Secure Conversation
The following use case is based on technical and business input from Rene’ Kiessling, Manuel Rohmann, Matt McLarty, and Gari Singh. In this article we explore a scenario in which trust is established between the WebSphere DataPower’s STS [which acts as an proxy to a Service Provider, SP] and the Microsoft Identify Provider, IdP, to facilitate a Federated Secure Conversation. For WebSphere DataPower, this is an illustration of how to implement a customer scenario using WebSphere DataPower’s policy frameworks with a Microsoft client using a Microsoft’s wsFederationHttpBinding. The WebSphere DataPower SOA appliance is also used to enforce the security policy of the web service that requires the secure conversation. The scenario was implemented on:
- Microsoft WCF .Net 3.5 framework
- WebSphere DataPower Firmware Release 22.214.171.124 or above
- Any Application Server for the backend, in this instance, we will use WebSphere Application Server as the backend application server
The Application expresses a requirement for a Secure Conversation (this can be implemented by attaching a security policy to the application WSDL) between the application provider and the client. In order to establish a Secure Conversation, the WebSphere DataPower SOA appliance requires:
- Ability to authenticate the client by validating a SAML 1.1 signature, for this example. Additional customized processing can occur for dealing with special scenario, see the [Other Considerations] at the end of the article.
- Ability to trust the IdP that issues the SAML token (the Microsoft IdP).
- Ability to generate a secure conversation token that WebSphere DataPower and the Microsoft WCF client can use to secure the messages exchanged.
The exchange between the parties include the following interactions:
- A Microsoft WCF .Net 3.5 Client will contact an Identity Provider, IdP to acquire a SAML 1.1 token [this is an implementation of a “federation” scenario].
- The IdP issues a SAML1.1 token to the Microsoft WCF .Net 3.5 client
- The issued token is signed by the MS IdP.
- A Microsoft WCF .Net 3.5 Client will access a web service via WebSphere DataPower.
- In the actual application message flow, WebSphere DataPower, acting as a STS, will issue a Secure Conversation Token for Microsoft WCF .Net 3.5 client.
- The traffic is protected with the Secure Conversation Token obtained from step 4.
- Once the Client has completed the application message exchange during a secure conversation session, the client will issue a Cancel operation to WebSphere DataPower to indicate the termination of the secure conversation session.
Figure 1. Message exchange during a secure conversation session
Step 1. Configuring the client
For the client [WCF], the corresponding app.config is needed:
Listing 1. app.config for configuring client
<bindings> <wsFederationHttpBinding> <binding name="EchoUserWithoutTlsNego" closeTimeout="00:05:00" openTimeout="00:05:00" receiveTimeout="00:30:00" sendTimeout="00:05:00"> <security mode="Message"> <message issuedTokenType= "http://docs.oasis-open.org/wss/ oasis-wss-saml-token-profile-1.1#SAMLV1.1" negotiateServiceCredential="false" > <issuer address="http://localhost:6000/SimpleActiveSTS" binding="wsHttpBinding" bindingConfiguration= "http://localhost:6000/SimpleActiveSTS"> <identity> <userPrincipalName value="DEMOSERVER\Administrator" /> </identity> </issuer> <issuerMetadata address="http://localhost:6000/SimpleActiveSTS/mex" /> <claimTypeRequirements> <add claimType="http://schemas.xmlsoap.org/ws/ 2005/05/identity/claims/name" /> <add claimType="http://schemas.datapower.com/E8/ 2008/09/Identities/RZUserId" /> </claimTypeRequirements> </message> </security> </binding> </wsFederationHttpBinding> <wsHttpBinding> <!-- communctaion to local STS service --> <binding name="http://localhost:6000/SimpleActiveSTS" closeTimeout="00:05:00" openTimeout="00:05:00" receiveTimeout="00:30:00" sendTimeout="00:05:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="524288" maxReceivedMessageSize="65536" messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true" allowCookies="false"> <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384" /> <reliableSession ordered="true" inactivityTimeout="00:30:00" enabled="false" /> <security mode="Message"> <transport clientCredentialType="Windows" proxyCredentialType="None" realm="" /> <message clientCredentialType="Windows" negotiateServiceCredential="true" algorithmSuite="Default" establishSecurityContext="true" /> </security> </binding> </wsHttpBinding> </bindings> <client> <!-- endpoint DNS name "datapower" configured within local hosts file  --> <endpoint name="EchoUser.DataPower" address="http://datapower:8000/EchoService" binding="wsFederationHttpBinding" bindingConfiguration="EchoUserWithoutTlsNego" contract="DataPower.CC.DCWebService.Common.EchoUser"> <identity> <certificateReference storeName="TrustedPeople" storeLocation="CurrentUser" x509FindType="FindBySubjectName" findValue="datapower" /> </identity> </endpoint> </client>
Step 2. Configuring the SOA appliance
The WS-Secure Conversation spec documents there are 3 ways to establish a security context between two parties. In this scenario, the trust established between the SOA appliance follows the first of these patterns. The Microsoft IdP has issued an authentication token, and WebSphere DataPower recognizes this IdP as a trusted party. The appliance, therefore acts as an STS for a SP, and it creates a security token for the exchange between the authenticated initiator and the application.
MMC is the tool provided by Microsoft for managing key materials, it can be used to export the key material from Microsoft. After all the key materials are exported from Microsoft, they must be imported into WebSphere DataPower so that the key materials can be used to decrypt and verify the messages during initial RST/RSTR traffic between Microsoft .Net client and WebSphere DataPower.
To establish trust relationships, WebSphere DataPower supports importing certificates [or public key] into the appliance with format DER, PEM, PKCS#7, or PKCS#12. In order to import private key to the appliance, the format of the file must be DER, PEM, PKCS#8, or PKCS#12. Microsoft exports key in pfx format, and to convert the pfx format, openssl can be used. E.g. openssl pkcs12 –in cert.pfx –out cert.pem -nodes.
To configure a secure conversation on the WebSphere DataPower SOA appliance for a WSDL service, a new operation must be added to handle the RequestSecurityToken operation. This WSDL defines a wsdl:operation for “RequestSecurityToken” with soap12 namespace. The namespace should match the SOAP namespace of the wsdl:operation.
New features in WebSphere DataPower 3.7.3
There are also some new features in the 3.7.3 release that allow us to configure WebSphere DataPower to participate in this scenario.. Note: Support of Secure Conversation with WS-Security Policy in WebSphere DataPower.
- Only "enforce" mode is supported
- "Renewal" of token is not supported
- Two fields have been added to the Web Service Proxy to provide increased support for EncryptedKeySHA1 KeyIdentifier and to preserve the decrypted key material.
WSProxy > Proxy Settings > “EncryptedKeySHA1 Cache Lifetime” and “Preserve EncryptedKey Chain”. The GUI is illustrated below in figure 2.
Figure 2. 3.7.3 GUI updates
EncryptedKeySHA1 Cache: Cache lifetime in second on how long to cache the decrypted “Encrypted Key” material. This is needed to generate a response with EncyrptedKeySHA1 Key Identifier, or decrypt future traffic which is protected with EncryptedKeySHA1 Key Identifier.
Preserve EncryptedKey Chain: By default, DataPower will remove the key material after decryption. Setting this to "on" will preserve the key material for future operation [e.g. when the request message is signed and encrypted by the same key material, and after the message is decrypted, the same key material is required to verify the signature of the message]
- A new policy parameter. Additional Transform Action During BootstrapPolicy, is added to allow customized transform during Bootstrap process. Any stylesheet specified in this parameter will be executed at the end of STS RST actions, and before any actions for RSTR are performed. This is illustrated in Figure 2.
Figure 3. 3.7.3 Policy parameter
- A new miscellaneous context, transaction-misc, is added to dp:aaa-set-context-info and dp:aaa-get-context-info for storing miscellaneous information associates with a context. There is a 512 bytes limit on the size of data this context can hold.
- Change in behavior on what the policy should be attached to wsdl:operation, RequestSecurity Token in 3.7.3.
- Before 3.7.3, wsdl:operation name="RequestSecurityToken" used bootstrap binding, the one associate with sp:BootstrapPolicy, in the PolicyReference element, as in the following example:
<wsdl:operation name="RequestSecurityToken"> <wsp:PolicyReference URI="local:///policy.xml#bootstrap-binding" /> <wsdl:input message="tns:RequestSecurityToken" /> <wsdl:output message="tns:RequestSecurityTokenResponse" /> </wsdl:operation>
- With 3.7.3.x, wsdl:operation name="RequestSecurityToken" must use application binding in the PolicyReference element, as in the following example:
<wsdl:operation name="RequestSecurityToken"> <wsp:PolicyReference URI="local:///policy.xml#application-binding" /> <wsdl:input message="tns:RequestSecurityToken" /> <wsdl:output message="tns:RequestSecurityTokenResponse" /> </wsdl:operation>
- Before 3.7.3, the location of the PolicyReference element in the WSDL file was flexible. In 3.7.3, it must immediately follow the operation element whose name attribute is RequestSecurityToken, as in the preceding example.
In the WebSphere DataPower 3.7.3 release, a new template is included to address this use case. The template can be found at: store:///policies/templates/dotnet/wsp-sp-1-2-wsFederationHttpBinding.xml and the process of configuring the service to use this binding is explained below.
Configure SOA appliance to handle wsFederationHttpBinding
- Upload the key materials exported from Microsoft to the WebSphere DataPower SOA appliance
Control Panel > Keys and Certicates Management > [Keys][Certificates][Crypto Profile >
Identification Credentials][Crypto Profile > Validation Credentials]
Keys : datapower
[from the key material specified in app.config -> "<client/> section"]Certificates : datapower
[from the key material specified in app.config -> "<client/> section"]Identification Credentials : datapower
[created with the key and certificate above][optional] Validation Credentials : sts
[from the key material that the Identifier Provider used to sign the SAML 1.1]
- For WS-Proxy, if the soap:Body of the input message is encrypted, WSProxy will
automatically decrypts the soap:Body before WSProxy will dispatch to the proper
wsdl:operation. There are 2 ways to specify a key for decryption :
1. WSProxy > Proxy Settings > Decrypt Key
2. Create an “Identification Credential” to relate the public and private key [this is the preferred method, and we will use this method for this use case]
Figure 4. List of crypto certificate
Figure 5. List of crypto key
Figure 6. Identification Credentials
Figure 7. Validation Credentials
- Retrieve the WSDL from the application server. In this case, with http://<server>:<port>?wsdl.
- Modify the wsdl directly to attach the input and output message policy to the wsdl:Input and wsdl:Output.
- Attaching policy to "Message Policy Subject", http://www.w3.org/TR/ws-policy-attach/, from the WebGUI is not supported.
<wsdl:binding name="EchoUser" type="i0:EchoUser"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="getCurrentUser"> <wsp:PolicyReference URI= "store:///policies/templates/dotnet/ wsp-sp-1-2-wsFederationHttpBinding.xml#BindingPolicy”/> <soap12:operation soapAction= "http://schemas.xmlsoap.org/ws/2005/02/trust/RST/SCT" style="document"/> <wsdl:input name="getCurrentUserRequest"> <wsp:PolicyReference URI= "store:///policies/templates/dotnet/ wsp-sp-1-2-wsFederationHttpBinding.xml#InputPolicy"/> <soap12:body use="literal"/> </wsdl:input> <wsdl:output name="getCurrentUserResponse"> <wsp:PolicyReference URI= "store:///policies/templates/dotnet/ wsp-sp-1-2-wsFederationHttpBinding.xml#OutputPolicy"/> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding>
- Create a WSProxy with the WSDL from step 3.
- Create a WS-Policy Parameter Set, secpol-param
- Microsoft’s wsFederationHttpBinding uses, WS-Security Policy 1.1, http://schemas.xmlsoap.org/ws/2005/07/securitypolicy, while ws2007FederationHttpBinding uses http://docs.oasis-open.org/ws-sz-ws-securitypolicy/200702. The naming implies that the security policy namespace is version 1.2; however, it is using namespace of version 1.1 and impacts in how the Security Policy Parameter is associated with the WS-Security Policy. Hence the 2 set of Policy Parameters are defined for both the 2 namespaces below, Security Policy 1.1 and Security Policy 1.2.
- 3 parameters are set, Interoperable with, WS-SecureConversation Version and Verification Valcred.
- Select "Enforce" as "WS-Policy Enforcement Mode"
- Click "Next"
Figure 8. Policy Parameters
Figure 9. Web Service Proxy WSDLs
- Add "HTTP Front Side Handler"
- Name : http8000
- Port Number : 8000
Figure 10. HTTP Front Side Handler
Figure 11. Configure HTTP Front Side Handler
Figure 12. WSDL Source Location
- Specify the Remote server IP address, port and URI of the application service. For this example, the Host’s IP address is 126.96.36.199 and 8000 as the port and /EchoService as the URI.
- Add in the WSDL, ws-wssecconv.wsdl, to handle STS’s RequestSecurityToken
- Make sure the correct security policy is attached to the proper Policy Subject in ws-wssecconv.wsdl
. . . . . . <wsdl:portType name="Test"> <wsdl:operation name="RequestSecurityToken"> <wsp:PolicyReference URI= "store:///policies/templates/dotnet/ wsp-sp-1-2-wsFederationHttpBinding.xml#BindingPolicy"/> <wsdl:input message="tns:RequestSecurityToken"/> <wsdl:output message="tns:RequestSecurityTokenResponse"/> </wsdl:operation> </wsdl:portType> . . . . . . <wsdl:input> <wsp:PolicyReference URI= "store:///policies/templates/dotnet/ wsp-sp-1-2-wsFederationHttpBinding.xml#InputPolicy"/> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <wsp:PolicyReference URI= "store:///policies/templates/dotnet/ wsp-sp-1-2-wsFederationHttpBinding.xml#OutputPolicy"/> <soap12:body use="literal"/> </wsdl:output>
- Use the same "Local Endpoint Handler" as in step 5.
- Use the same "URI" as in step 5.
- Enable WSProxy to support "EncryptedKeySHA1" and preserve the key material by
editing setting in "Proxy Settings"
- EncryptedKeySHA1 Cache Lifetime : 100 [any value > 0 sec]
Preserve EncryptedKey Chain : on [to preserve the key material which is needed to verify the signature inside the message]
Figure 13. Configure Web Service Proxy
- [optional] Attach policy to the application operation. In this example, we attach
the policy directly in the WSDL. Another option is to utilize the WebGUI to
attach the policy
- Select "Yes" on "Show portType and binding nodes:"
Figure 14. Show portType and binding nodes
- Select "WS-Policy" of portType to attach the policy to that given Policy Subject
- Attach store:///policies/templates/dotnet/wsp-sp-1-2-wsFederationHttpBinding.xml#BindingPolicy
Figure 15. Additional Policy Sources
- The output response is signed and encrypted. Once the message is encrypted, it will fail the schema validation if schema validation is enabled.
- STS > RequestSecurityToken
- Uncheck "Schema validate request messages" and "Schema validate response messages"
- Application > EchoServices
- Uncheck "Schema validate response messages"
Figure 16. Uncheck "Schema validate response messages"
- Add 2 user rules, request and response to EchoUserServiceWCF.wsdl to handle WS-Addressing by use "Add Rule".
- Request [Client > Server]: add a transform for getMessage.xsl, see
- This will save the necessary wsa:xxxx information in a context variable
- Direction : Client to Server
- Input : INPUT
- Output : NULL
- Response [Server > Client]: add a transform for setMessage,xsl, see
- This will create a <soap:Header/> element with the necessary WS-Addressing information from Step 10 above
- Direction : Server to Client
- Input : INPUT
- Output : PIPE
** setMessage.xsl assumes the response from the server does not contain a soap:Header. It will add a soap:Header with the necessary information. However if the backend sends a response containing a soap:Header, setMessageIdWithoutAddingSoapHeader.xsl should be used instead.
Figure 17. Action: Transform
- Click "Apply" to apply all the changes and save the configuration for the WSProxy.
Testing the connection
At this point, you should modify the Microsoft .Net WCF 3.5 client to access the WebSphere DataPower SOA appliance.
Figure 18. Established a secure conversation
You have successfully established a secure conversation with Microsoft WCF 3.5 using wsFederationHttpBinding.
To ensure the exchange is correct with the WebSphere DataPower SOA appliance, turn on the probe and monitor the traffic. If the probe is turned on, you will notice 3 sets of network traffic. The following is an example:
Tran # 41121 : STS RequestSecurityToken. This established the SecurityContextToken. Notice the outbound-url, the appliance acts as an STS, and it issued the Secure Conversation Token for the application traffic, and hence the traffic does not have a valid outbound-url.
Tran # 41409 : Application Traffic. One thing to keep in mind, on the response’s application traffic, the first round of checking is for soap:Fault, and if all goes well, you will notice a failure of that check, follows by another set(s) of application traffic. This is the expected behavior. * soap:Fault can have its own Security Policy attached to it, and it does not follow the Security Policy attached to the application traffic, and hence if the application work successfully without returning a soap:Fault, you will notice a failure as a first check.
Tran # 45170 : STS RequestSecurityToken’s Cancel operation, this shutdown the secure conversation session. Notice the outbound-url, the appliance acts as STS to cancel the Secure Conversation Token it issued in Tran #41121, and hence the traffic does not have a valid outbound-url.
Figure 19. Transaction List for EchoService
With the Microsoft’s wsFederationHttpBinding, the initial RST/RSTR contains an identity token, SAML1.1 token in this case. This SAML token is used for the initial exchange, and it will not be sent in the subsequent application traffic. The following is an example to show case how one can preserve this information for future traffic. This is for demonstration purpose only.
Given SAML 1.1 is only sent in once, and it must be preserved for future application transaction. A new security policy parameter is added, Additional Transform Action During BootstrapPolicy. With this parameter, a stylesheet can be used to run after the RST is processed, but before DataPower SOA Appliance generates a RSTR. This stylesheet will keep information of this SAML1.1 information in a cache for future traffic.
Figure 20. Additional Transform Action During BootstrapPolicy
Three stylesheets are included in this article to provide an example on how to use ‘Additional Transform Action During BootstrapPolicy’ in conjunction with ‘dp:aaa-set-context-info’. Together, they will associate the SAML token with a given secure conversation transaction.
- Create the above policy parameters for Bootstrap’s RST/RSTR traffic [see
- The stylesheet saves a subset of SAML information in a context variable
- In the user’s rule of the Bootstrap’s RST/RSTR, call dp:aaa-set-context-info to
associate the SAML information with the Secure Conversation context. Please note
that the miscellaneous information is limited to 512 bytes long. [see
- Make sure the input of this transform is INPUT
- Make sure the output of this transform is NULL
- Result Action that follows this transform should have ‘INPUT’ as its input
- On the request traffic of the user’s rule on the application traffic
- Use a transform action with dp:aaa-get-context-info to access the SAML information stored in 1. [see GetSAMLFromRST.xsl]
- Make sure the input of this transform is INPUT
- Make sure the output to this transform is NULL
- Result Action that follows this transform should be set accordingly, it is most likely to be INPUT
- Participate in the discussion forum.
- Get more information about WebSphere DataPower SOA Appliances. These purpose-built, easy-to-deploy network devices simplify, help secure, and accelerate your XML and web services deployments while extending your SOA infrastructure.
- About "WebSphere DataPower SOA Appliances firmware and documentation.
- XML security technology specifications
- WS-Secure Conversation 1.3
- WS- Trust 1.3
- Web Services Policy Attachment 1.5
- WS-Security Policy
- SAML specification
- Play in the "IBM SOA Sandbox! Increase your SOA skills through practical, hands-on experience with the IBM SOA entry points.
- The"SOA and web services zone on IBM developerWorks hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop web services applications.
Dig deeper into SOA and web services on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.