Offload WebSphere web services security tasks to IBM WebSphere DataPower SOA Appliances: Part 5: Configuring a web service proxy to interoperate with WCF .NET client using Kerberos Tokens with or without secure conversation

WebSphere DataPower SOA Appliance firmware 3.8.0 interoperates with WCF .NET 3.5 framework and supports several WCF system bindings. This article describes the WCF-DataPower interoperability using Kerberos tokens. It is the part 5 in the series "Offload WCF Web Service Security Policies to IBM WebSphere DataPower Appliance".

Share:

Krithika Prakash (krithika@ca.ibm.com), Software Engineer, IBM  

Krithika is Software Engineer with a total seven years of experience in the IT industry. She specializes in software development in the areas of networking, security, Web services security and XML/XSLT technologies. After having worked for Novell Inc. for 4 years, Krithika joined IBM as a L3 specialist for WebSphere DataPower. She is currently working as a developer in the Security team of WebSphere DataPower.



Fred (Xiangfu) Chen (chenfr@us.ibm.com ), Engineer, IBM

Fred (Xiangfu) Chen is an engineer in the IBM WebSphere DataPower Security group for DataPower's security appliance with message level security and access control. He works on the features for user Authentication, Authorization and Auditing and Accounting; the XML or Web Service security features as specified by different standard bodies such as OASIS WS-Security, XACML, SAML, WS-SX (WS-SecureConversation, WS-Trust and WS-SecurityPolicy), WS-I BSP and LDAP. He also takes the lead on the implementation to make sure DataPower's msg security interoperable with other products such as MS WCF and WebSphere. Before joining DataPower, Fred worked for CA's SiteMinder and Sun's JDK.



Allis Kuo (Allis_Kuo@tw.ibm.com), Developer, IBM

Allis Kuo is a developer working on DataPower at IBM China Development Lab in Taipei . Prior to development in DataPower, Allis also works as DataPower SQA and WPS development and interests in SOA integration and middleware related topics.



01 March 2010

Also available in Russian Portuguese Spanish

Introduction

Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Implementing WS-Security for Java web services

This article describes the WCF-DataPower interoperability using Kerberos tokens. It is the part 5 in the series "Offload WCF Web Service Security Policies to IBM WebSphere DataPower Appliance". I would like to acknowledge the contribution from Shiu F. Poon in reviewing this article and providing valuable feedback.


Basic scenario

Using WCF .NET 3.5 framework, we need to configure the web services client to use windows authentication and message security using Kerberos tokens and interoperate with DataPower which proxies a web service. Figure 1 depicts the Basic Scenario.

Figure 1. Basic Scenario
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

Requirements

  • WebSphere DataPower 3.8.0 or later
  • Windows 2003 Server with Active Directory
  • Windows Client computer which is part of the Active Directory domain
  • Microsoft .NET 3.5 framework
  • Visual Studio 2008 (Optional. But makes life easier)

Configuration steps

Let's see in detail the following three major configuration areas:

  1. Creating Principals and Keytabs in Active Directory
  2. Configuring the WCF Client
  3. Configuring the DataPower Device

Creating principals and keytabs in Active Directory

Setting up Active Directory and IIS

If you already have Active Directory and IIS up and running in your setup, skip this section and move on to the next section Configuring the WCF Client.

  • Install Active Directory (Domain Controller)
    Learn more about [InstallActiveDirectory] or [InstallActiveDirectoryDNS] to install and configure the domain controller in the resources section.
  • Install IIS (Application server)
    Learn more about [InstallIIS] in the resources section. That will help you with installing the IIS. Also, check out the Trouble Shooting section for issues like “IIS hosted service fails”.

Create a SPN to represent the service proxied by WebSphere DataPower in Active Directory

In order for the client to obtain a Kerberos ticket to generate the Kerberos token, you need to create a SPN (Service Principal Name) for the target. You will need access to the Active Directory Users and Computers console as well as the "setspn.exe" utility (for Windows 2003 you can download this from Microsoft or find it on the Windows 2003 tools CD).

  1. Create an AD pseudo-user which will be used to map the SPN. For this example, create an AD user "wcfservice".
  2. Create an SPN mapped to the "wcfservice" user create above:
    setspn –a dpbox/wcfservice wcfservice
    where "dpbox" is any arbitrary prefix and "wcfservice" is the name used to represent the WebSphere DataPower device.
    NOTE: The SPN is a string and you could choose any name or format. For eg. The SPN could be "HOST/hostname:port" or "HOST/hosname", etc,..
  3. Check to make sure the SPN was correctly registered:
    setspn -l wcfservice
    You should see the SPN listed.

Generate a Kerberos Keytab for the SPN

In order for Kerberos to work, you will need to map the SPN to the user and create a Kerberos keytab which will later be used with WebSphere DataPower. To do this, you will use the "ktpass" utility. Learn more about [InstallKTPass] in the resources section to get it installed.

For the sample user 'wcfservice' and the sample realm "WPS.CSUPPORT.COM", the ktpass command would look like:

ktpass -out c:\temp\wcfservice.keytab -princ dpbox/wcfservice@WPS.CSUPPORT.COM -mapUser wcfservice -mapOp set -pass <passwordforuser> -crypto RC4-HMAC-NT [–ptype KRB5_NT_PRINCIPAL] [ –kvno <kvno>]

NOTE:

  1. It is important to specify the -crypto option to be RC4-HMAC-NT in order to make this work. (DES is weaker and may not interoperate with WebSphere DataPower).
  2. –ptype KRB5_NT_PRINCIPAL is optional.
  3. –kvno <kvno> is only required when you want to override the key version number to a specific value say, "-kvno 1". A very common issue seen with the keytab generated is the "kvno mismatch error". Please check the Troubleshooting section on related issues and what error messages to expect from WebSphere DataPower when there is a kvno mismatch.

You will have to copy this keytab file "c:\temp\wcfservice.keytab" to DataPower. See section Configuring DataPower Device.


Configuring the WCF client

Download the WCF samples

In this article, we try to demo the interoperability of the WCF samples and the WebSphere DataPower configured to use windows authentication and message security using Kerberos tokens. As a first step, we need to make sure we have a working WCF samples client and service (without WebSphere DataPower yet in the picture). If you already have a WCF client, skip this section and move on to the next section Modify app.config file.

  1. Install the WCF samples [WCFSamples]. Make sure you don't have any warnings or error messages.
    Note: You should have installed Active Directory and IIS as explained in the section Setting up Active Directory and IIS.
  2. We are going to use the project "WCF_SAMPLES\WCF\Basic\Binding\WS\Http" to build the solution in Visual Studio 2008.
  3. Verify that the service is running by browsing to http://localhost/servicemodelsamples/service.svc?wsdl

Modify app.config file

  1. Disable the use of the default SPNEGO tokens.

Once you have a working WCF client and a service, you can go ahead and modify the app.config, such that you disable the use of the default SPNEGO tokens and enable Kerberos tokens instead. (In order to interoperate with DataPower, the WCF client should be using Kerberos tokens to sign and encrypt the requests). This can be done by setting negotiateServiceCredential="false" in the app.config

Listing 1. Disable the use of the default SPNEGO tokens
<security mode="Message">
    <transport clientCredentialType="Windows" proxyCredentialType="None"
                            realm="" />
    <message clientCredentialType="Windows" negotiateServiceCredential="false"
                            algorithmSuite="Basic128" establishSecurityContext="false" />
</security>
Listing 2. Modify the algorithmSuite to Basic128
<security mode="Message">
    <transport clientCredentialType="Windows" proxyCredentialType="None"
                            realm="" />
    <message clientCredentialType="Windows" negotiateServiceCredential="false"
                            algorithmSuite="Basic128" establishSecurityContext="false" />
</security>

We disabled negotiateServiceCredential in the previous step. This results in modifying the algorithmSuite to Basic128, instead of the default Basic256. This is required because of the fact that the Kerberos tickets are issued with 128 bit keys by design of Active directory. If you are interested in the details, refer the Troubleshooting section.

You can enable or disable secure conversation with the parameter "establishSecurityContext". Setting it to "false", disables secure conversation. Setting it to "true", enables secure conversation.

Listing 3. Disable/Enable secure conversation
<security mode="Message">
    <transport clientCredentialType="Windows" proxyCredentialType="None"
                            realm="" />
    <message clientCredentialType="Windows" negotiateServiceCredential="false"
                            algorithmSuite="Basic128" establishSecurityContext="false" />
</security>

When secure conversation is enabled, the WCF client sends an initial request "RequestSecurityToken", along with the Kerberos tokens. WebSphere DataPower on receiving this request will validate the Kerberos tokens and will generate a SCT (Security Context Token) and send it to the client. All further transactions between WebSphere DataPower and Client will be signed/encrypted using this SCT.

Note that, if you enable secure conversation on the WCF client, you will have to configure DataPower to handle the initial secure conversation requests. Refer the section To handle Secure Conversation.

Next, include an 'identity' element with the service principal name created above. (In both the client's and the service's configurations).

Listing 4. Disable/Enable secure conversation
<identity>
    <servicePrincipalName value="dpbox/wcfservice@WPS.CSUPPORT.COM"/>        
</identity>

Note that the service principal specified here should be the same as specified in the ktpass command described in the section Generate a Kerberos Keytab for the SPN.

Next, you will be configuring a WebSphere DataPower Http Front Side Handler to handle all the incoming requests from the WCF client. Modify the app.config to the point to the WebSphere DataPower hostname and port. Make sure you have the right URI.

Also, before modifying the endpoint, you can try to rerun the WCF client and service (without WebSphere DataPower yet in the picture) to make sure that you have a working WCF client/service setup which uses Kerberos tokens instead of the default Spnego tokens.

Your modified app.config should look as shown in Listing 5.

Listing 5. WCF Client App.config
<?xml version="1.0 encoding="utf-8"?>
<configuration>
    <system.serviceModel>
        <bindings>
            <ws2007HttpBinding>
                <binding name=WS2007HttpBinding_ICalculator" closeTimeout="00:01:00"
                    openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01: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" maxTableCharCount="16384"/>
                    <reliableSession ordered="true" inactivityTimeout="00:10:00" 
                                enabled="false"/>
                    <security mode="Message">
                        <transport clientCredentialType="Windows" 
                                proxyCredentialType="None" realm=""/>
                        <message clientCredentialType="Windows" 
                                negotiateServiceCredential="false" 
                                    algorithmSuite="Basic128" 
                                    establishSecurityContext="true"
                    </security>
               </binding>
           </ws2007HttpBinding>
        </bindings>
        <client>
        <!-- endpoint DNS name "datapower" must be configured within local hosts file -->
            <endpoint address="http://datapower:8009/WS2007HttpKrbSC/service.svc"
                binding="ws2007HttpBinding" bindingConfiguration="WS2007HttpBinding_ICalculator"
                contract="ICalculator" name="WS2007HttpBinding_ICalculator_DP">
                <identity>
                <servicePrincipalName value="dpbox/wcfservice@WPS.CSUPPORT.COM"/>
                </identity>
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

Configuring WebSphere DataPower

Configure a WS-Proxy

A web services proxy should be configured, such that it enforces the policies required for wsHttpBinding/ws2007HttpBinding and requires that the transactions be signed/encrypted using Kerberos tokens. The following needs to be completed:

  1. Add the service wsdl
  2. Attach the required WS-Security Policy
  3. Attach the required 'Policy Parameter Set'
  4. Configure the 'Proxy Settings' tab for decryption

This article assumes that you are familiar with the basic configuration of web services proxy – adding a wsdl, configuring the http front side handler, providing the right URI and configuring the backend service. Note that the WebSphere DataPower configuration in the attachment includes all these configurations for a number of sample WS-Proxies.

1. Add the service wsdl

The wsdl for the sample calculator service (for w2007HttpBinding) can be obtained by browsing to http://localhost/servicemodelsamples/service.svc?wsdl on the .NET service where you have installed the WCF samples. If you are planning to import this wsdl to WebSphere DataPower, you may have to copy additional schema files to DataPower and also modify the wsdl import URI, as shown:

<wsdl:import namespace = "http://Microsoft.ServiceModel.Samples" location =
        "local:///CalculatorServiceDefinition.wsdl"/>

Also make sure to remove the policy elements from the wsdl file. You will be adding the WebSphere DataPower provided template polices as reference elements as explained in the later sections.

Figure 2. Add the service wsdl
Add the service wsdl

In this example, the backend is a loopback XML firewall which fetches a static AddResponse.xml file. Typically this will be substituted with a backend web server.

The Local URI should match with what is specified in the client's app.config's endpoint.

2. Attach the required WS-Security Policy

WebSphere DataPower has provided a number of templates files in the "store://policies/templates/dotnet" directory. One should pick the right template file and the right wsu:id within it and add it to the wsdl. Let’s see how to pick the 'right' template file and the wsu:id.

In this example, the WCF client is configured to use ws2007HttpBinding with Kerberos tokens and it has disabled secure conversation. Also note the AlgorithmSuite in the app.config in the client file. It is set to Basic128. Hence the following are the parameters that we should consider, when choosing the template file in the 'store://policies/templates/dotnet' directory.

Template file: wsp-sp-1-2-ws2007HttpBinding.xml
Binding: symmetric
Token: Kerberos
AlgorithmSuite: Basic128 
Secure Conversation: No

Hence the policy reference element should be like:

<wsp:PolicyReference URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml#symmetric-kerberos-basic128"/>.

The input and output policies also should be added as shown in Listing 6.

Listing 6. Add PolicyReference to service wsdl
<wsdl:import namespace = "http://Microsoft.ServiceModel.Samples" location =
"local:///CalculatorServiceDefinition.wsdl"/>
<wsdl:types/>
<wsdl:binding name = "WS2007HttpBinding_ICalculator" type = "i0:ICalculator">
    <wsp:PolicyReference
URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml
                                            #symmetric-kerberos-basic128"/>
    <soap12:binding transport = "http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="Add">
        <soap12:operation soapAction =
"http://Microsoft.ServiceModel.Samples/ICalculator/Add" style = "document"/>
        <wsdl:input>
            <wsp:PolicyReference
URI="store:///policis/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml#input"/>
            <soap12:bosy use = "literal"/>
        </wsdl:input>
        <wsdl:output>
            <wsp:PolicyReference
URI="store:///policies/templates/donet/wsp-sp-1-2/ws2007HttpBinding.xml#output"/>
            <soap:12body use = "literal"/>
        </wsdl:output>
    </wsdl:operation>       
</wsdl:binding>
<wsdl:service name = "CalculatorService">
    <wsdl:port name = "WS2007HttpBinding_ICalculator" binding =
"tns:WS2007HttpBinding_ICalculator">
        <soap12:address location = "http://wcfnet/ServiceModelSamples/service.svc"/>
        <wsa10:EndpointReference>
            <wsa10:Address>http://wcfnet/ServiceModuleSamples/service.svc</wsa10:Address>
            <Identity xmlns =
"http://schemas.xmlsoap.org/ws/2006/02/addressingidentitiy">
                <Spn>HOST/wcfnet</Spn>
            </Identity>
        </wsa10:EndpointReference>
    </wsdl:port>
</wsdl:service>

Also make sure you enable the "WSDL-Embedded Policy References" in the policy tab as shown in the figure below.

Figure 3. Enable WSDL-Embedded Policy References
Enable WSDL-Embedded Policy References

Note that instead of modifying the wsdl, you can retain the original service wsdl and attach the policy references in the "policy" tab from webgui as shown in Figure 4. But there is one limitation. You cannot use the webgui to attach the policy to the 'Message Policy Subject'. Hence in this example, in addition to what is shown in Figure 4, you still have to add the input and output policy references in the service wsdl:

<wsdl:input>
    <wsp:PolicyReference URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml
                           #input"/>   
    <soap12:body use = "literal"/>
</wsdl:input>
<wsdl:output>
    <wsp:PolicyReference URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml
                            #output"/>  
    <soap12:body use = "literal"/>
</wsdl:output>
Figure 4. Attach policy to service wsdl using WebGUI
Attach policy to service wsdl using webgui

3. Attach the required ‘Policy Parameter Set

In the Policy Parameter Set, configure the parameters for a Kerberos Token shown in Figure 5.

Kerberos Server Principal - this will be the SPN created earlier in Generate a Kerberos Keytab for the SPN. e.g. dpbox/wcfservice@WPS.CSUPPORT.COM

Kerberos Client Principal – The principal name of the one who signed the incoming message request. In our example, it is wcfclient@WPS.CSUPPORT.COM. It is the principal name of the user who is logged into the WCF client machine and who invoked the client program. Note that the “Kerberos Client Principal” is not really used, unless you enable the "Enforce Kerberos Client Principal" parameter.

Kerberos Keytab – This is the keytab of the server-principal. If not already created, create a "Kerberos keytab object" by uploading the keytab file created using the ktpass command. See section Creating principals and keytabs in Active Directory.

Interoperable with Microsoft: You need to add this parameter whenever you need WebSphere DataPower to interoperate with any of the bindings supported by Microsoft.

Note that the policy domain should match with what is specified in the template file. In this example, you can confirm by checking the template file "store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml" where the security policy name space is specified to be "xmlns:sp = http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702". So you will have to add the policy parameters to this namespace.

Figure 5. Add 'Policy Parameter Set' to service wsdl
Add Policy Parameter Set to service wsdl

4. Configure the Proxy Settings tab for decryption

When using wsHttpBinding/ws2007HttpBinding the messages are both signed and encrypted using Kerberos tokens. In order to decrypt the incoming message, the decryption credentials must be specified in the 'proxy settings' tab of the web services proxy as shown in Figure 6. The Server Principal name should be the same as specified in the ktpass command and the keytab should the one created using the ktpass command described in Generate a Kerberos Keytab for the SPN. The client principal name here is optional.

Figure 6. Decryption credentials in the Proxy Settings tab
Decryption credentials in the Proxy Settings tab

Secure conversation

If the WCF client is configured to enable secure conversation (establishSecurityContext="true"), then WebSphere DataPower should be configured to handle that. It involves the following steps in addition to the steps explained in the previous sections.

  1. Add the STS wsdl to handle initial secure conversation requests
  2. Attach the required WS-Security Policy to the STS wsdl
  3. Attach the required 'Policy Parameter Set' to the STS wsdl
  4. Disable schema validation

1. Add the STS wsdl to handle initial secure conversation requests

In order to handle the initial secure conversation requests (RequestSecurityToken), we need to add an STS wsdl to the web services proxy. See Figure 7 below. Note the local endpoint handler and the URI. It should match with what is configured for the service wsdl.

Figure 7. Add STS wsdl to handle secure conversation
Add STS wsdl to handle secure conversation

2. Attach the required WS-Security Policy to the STS wsdl

The template file along with the correct wsu:id should also be added to the sts wsdl. Note that since Secure conversation is enabled, the policy reference element should be <wsp:PolicyReference URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml #symmetric-kerberos-sc-basic128"/> for both the STS wsdl and the service wsdl. Listing 7 shows a sample STS wsdl.

Listing 7. Add PolicyReference to STS wsdl

Click to see code listing

Listing 7. Add PolicyReference to STS wsdl

<?xml version="1.0" encoding="utf-8"?>
<wsdl:definitions targetNamespace="http://schemas.xmlsoap.org/ws/2005/02/trust"
    xmlns:tns="http://schemas.xmlsoap.org/ws/2005/02/trust"
    xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:echo="http://com/ibm/was/wassample/sei/echo/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-security-utility-1.0.xsd">

<wsdl:types>
    <xs:schema targetNamespace="http://schemas.xmlsoap.org/ws/2005/02/trust"
blockDefault="#all" elementFormDefault="qualified">
        <xs:element name="RequestSecurityToken">
            <xs:complexType>
                <xs:sequence>
                    <xs:any namespace="##any" maxOccurs="unbounded"/>
                </xs:sequence>
                <xs:anyAttribute namespace="##any" processContents="lax"/>
            </xs:complexType>                
        </xs:element>
        <xs:element name="RequestSecurityTokenResponse">
            <xs:complexType>      
                <xs:sequence> 
                    <xs:any namespace="##any"/>        
                </xs:sequence> 
            </xs:complexType>
        </xs:element>
    </xs:schema>
</wsdl:types>

<!--Message part definitions for the bootstrap request/response.-->
<wsdl:message name ="RequestSecurityToken">
    <wsdl:part name="Body" element="tns:RequestSecurityToken"/>

<!--Endpoint/operation definition for bootstrap messages Policy
        attach here must include -->

<wsdl:portType name="Test">
    <wsdl:operation name="RequestSecurityToken">
        <wsp:PolicyReference
URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml#symmetric-kerberos-sc-basic128"/>
        <wsdl:input message="tns:RequestSecurityToken"/>
        <wsdl:output message="tns:RequestSecurityTokenResponse"/>
    </wsdl:operation>
<wsdl:portType>

<wsdl:binding name="T1Binding" type="tns:Test">
    <soap12:binding style="document"
transport="http://schemas/xmlsoap.org/soap/http"/>
    <wsdl:operation name="RequestSecurityToken">
<!-- 
    <soap12:operation
soapAction="http://schemas.xmlsoap.org/ws/2005/02/trust/RST/SCT"/>
    <soap12:operation
soapAction="http://schemas.xmlsoap.org/ws/2005/02/trust/RST/SCT/Cancel"/>
-->
<!-- attach the application binding to the wsdl:input and wsdl:output, so
    the policy framework can figure out how to deal with other traffic, others
    than the Issue
-->
    <wsdl:input>  
        <wsp:PolicyReference
URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml#input"/>
        <soap12:body use="literal"/>
    </wsdl:input>   
    <wsdl:output>
        <wsp:PolicyReference
URI="store:///policies/templates/dotnet/wsp-sp-1-2-ws2007HttpBinding.xml#output"/>
         <soap12:body use="literal"/>
    </wsdl:output>
</wsdl:operation>
</wsdl:binding>

<wsdl:service name="Test">
    <wsdl:port name="BootstrapPort" binding="tns:T1Binding">
        <soap12:address location="https://www.soaphub.org/RequestSecurityToken"/>
    </wsdl:port>
</wsdl:service>
</wsdl:definitions>

3. Attach the required 'Policy Parameter Set' to the STS wsdl

Attach the same policy parameter , described in the Attach the required 'Policy Parameter Set' to the STS wsdl endpoint also as shown in Figure 8.

Figure 8. Attach Policy Parameter Set to STS wsdl
Attach Policy Parameter Set to STS wsdl

4. Disable schema validation

The response of the ‘RequestSecurityToken’ is signed and encrypted. The schema validation must be disabled for both the request and response messages for the STS wsdl and it must be disabled for the response message for the service wsdl as shown in Figure 9.

Figure 9. Disable Schema Validation
Disable Schema Validation

Differences between wsHttpBinding and ws2007HttpBinding

You might have noticed that the examples throughout this article used ws2007HttpBinding. What if you want to use wsHttpBinding? The following lists the differences:

  1. While configuring the WCF client, use the <wsHttpBinding> (instead of ws2007HttpBinding) in the app.config. A sample is shown in Listing 8.
Listing 8. Sample app.config for wsHttpBinding
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.serviceModel>
        <bindings>
            <wsHttpBinding>
                <binding name="WSHttpBinding_ICalculator" closeTimeout="00:01:00"
                    openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01: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" maxTableCharCount="16384"/>
                    <reliableSession ordered="true" inactivityTimeout="00:10:00" 
                                enabled="false"/>
                    <security mode="Message">
                        <transport clientCredentialType="Windows" 
                                proxyCredentialType="None" realm=""/>
                        <message clientCredentialType="Windows" 
                                negotiateServiceCredential="false" 
                                    algorithmSuite="Basic128" 
                                    establishSecurityContext="true"
                    </security>
               </binding>
           </wsHttpBinding>
        </bindings>
        <client>
            <!-- endpoint DNS name "datapower" must be configured within local hosts
                    file-->
                <endpoint address="http://datapower:8007/WSHttpKrb/service.svc"
                    binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_ICalculator"
                    contract="ICalculator" name="WSHttpBinding_ICalculator_DP">
                    <identity>
                        <servicePrincipalName
                            value="dpbox/wcfservice@WPS.CSUPPORT.COM"/>
                    </identity>
                </endpoint>
        </client>
    </system.serviceModel>
</configuration>
  1. While configuring DataPower wsdl file and attaching the WS Security Policy, make sure you choose the correct template file corresponding to wsHttpBinding, when adding the policy references. For example, it should be <wsp:PolicyReference URI="store:///policies/templates/dotnet/wsp-sp-1-1-wsHttpBinding.xml#symmetric-kerberos-sc-basic128"/>
  2. While Configuring DataPower Policy Parameter set, make sure you have assigned all the policy parameters to the correct policy domain corresponding to wsHttpBinding. For example, it should be http://schemas.xmlsoap.org/ws/2005/07/securitypolicy

If you are here, you are all set with the required configuration. Run the client program and see it process the response from WebSphere DataPower.


Troubleshooting

IIS hosted Service fails

By default, when IIS is setup, the ASP.NET uses 1.0 version. You need to register to 2.0 by using aspnet_regiis.exe -i in
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727

If the above step is missing, then we will not be able to deploy the sample service (described in this article) to IIS.

"Cannot parse file for Kerberos Keytab" or "Bad checksum on Kerberos AP-REQ message"

If you are seeing this error in DataPower, you have most likely hit the (in)famous kvno mismatch error or an algorithm mismatch error. Unfortunately the error/log messages in WebSphere DataPower cannot point out the exact details on the mismatch or for that matter if it really is a mismatch error. (It could possibly be a corrupted keytab file).

An algorithm mistmach error could happen when the encryption algorithm used in the AP-REQ token is different from what is specified in the keytab. You are likely to see the error "Bad checksum on Kerberos AP-REQ message". Make sure you have used RC4-HMAC-NT in the ktpass command.

A kvno mismatch error could happen when the kvno in the keytab used by DataPower is different from the kvno that the KDC is using. You can find the key version number that the KDC is using by running the [ldifde] command on the KDC:

ldifde -f c:\spn.txt -d "DC=<yourdomain>,DC=com" -l *,msDS-KeyVersionNumber -r 
                "(serviceprincipalname=<yourspn>*)" -p subtree

For the example given in this article, it would be:

ldifde -f c:\spn.txt -d "DC=wps,DC=csupport,DC=com" -l *,msDS-K
eyVersionNumber -r "(serviceprincipalname=dpbox/wcfservice*)" -p subtree

Now check the "msDS-KeyVersionNumber". This is the kvno that the KDC is using for this particular SPN.

On the other hand, you can find the kvno used in the keytab file by running the kt_util command on a linux machine:

/usr/kerberos/sbin/ktutil:
read_kt <keytabfileName>

If they donot match, regenerate the keytab file using the ktpass command with the "–kvno" parameter with the value that the KDC is using.

If you still get the error, it could be possible that things are screwed up with multiple modifications to the SPN or its user. Delete the spn (setspn –d), user and start from scratch of creating the user, create a SPN, creating the keytab using the ktpass command and copying it to DataPower. Ensure the principal names are consistent and case sensitive, besides the realm name being in upper case.

algorithmSuite=Basic256 does not work

When you disable NegotiateServiceCrendential, then the algorithmSuite=Basic256 does not work. The reason (as provided by Microsoft support) is as follows:

  1. Kerberos tickets are issued with 128 bit keys by design. Hence it will not work with any 256 keyed algorithms used by 'Basic256' algorithm suite. Resolution in this case is to use 'Basic128', which WCF uses by default when using Kerberos direct authentication i.e. when negotiateServiceCredentials is set to 'false'.
  2. The same setup works when negotiateServiceCredentails=true. That is because with negotiateServiceCredentails=true, we use SspiNegotiation (multi)instead of Kerberos direct (one shot). With SspiNegotiation, WCF generates a suitably sized cryptographic key after negotiating security details and checking compatibility on either ends. However such a freedom does not exist in case of direct Kerberos mode. Client generates 128 bit Kerberos key which falters at the service end.

Looking at the probe in WebSphere DataPower

If you have enabled Probe in DataPower, you can see the request and response messages which should come in handy for debugging.

If you have configured for secure conversation, you will see three requests shown in the figure below.

  1. Request for Security Context token.
  2. Actual service request to add two numbers.
  3. Request to cancel the Security Context token.
Figure 10. Looking at the Probe
Looking at the Probe

What's new in 3.8.0

This section lists the new contents in 3.8.0.

Policy parameter 'Disable SSL Cipher Suite Check'

This is a policy parameter which will let you disable the ssl cipher check by the web services proxy. This will come in handy, when you have configured a https front side handler and you have errors from the web services proxy as "Execution of 'store:///dp/transport-check.xsl' aborted: Invalid SSL bulk encryption key length".

Once you turn on "Disable SSL Cipher Suite check" see Figure 11, the web services proxy will not perform any validation on the SSL cipher suite that is already negotiated by the https front side handler.

Figure 11. Policy parameter 'Disable SSL Cipher Suite Check'
Policy parameter Disable SSL Cipher Suite Check

Note that you can also work around the "Invalid SSL bulk encryption key length" error by configuring your https front side handler's crypto profile to use the algorithm that the web services proxy mandates. But that would mean, you will be restricting a lot of clients who do not support that alrogithm in the SSL handshake.

Policy parameter 'Enforce Kerberos Client Principal'

The parameter "Kerberos client principal" is not really used until the parameter "Enforce Kerberos Client Principal" is enabled. Once it’s enabled, (see Figure 12) the verify actions generated by the security policy, compare the value of the "Kerberos client principal" with that of the signer of the message in the incoming request message. If it does not match, then the message is rejected.

Figure 12. Policy parameter 'Enforce Kerberos Client Principal'
Policy parameter Enforce Kerberos Client Principal

WCF Bindings and tokens supported

We support the following bindings and the attached sample files contain the web services proxy configured to each of these bindings as shown in Figure 13.

  • BasicHttpBinding - SSL enabled and SSL enabled with require client cert.
  • wsHttpBinding/ ws2007HttpBinding – Kerberos and X509 tokens with and without secure conversation.
  • wsFederationBinding and ws2007Federation Binding – SAML1 and SAML2 tokens.
Figure 13. Web Services proxy for each binding supported
Web Services proxy for each binding supported

A number of template files have been added to the store://policies/templates/dotnet directory as shown in Figure 14.

Figure 14. Template files
Template files

Each of these template files contain multiple wsu:ids. Check out the resources to learn more about how to attach the required WS-Security Policy on deciding how to pick the right template file and the wsu:id within based on the binding and the token used at the WCF client configuration.

Figure 15 shows a few sample template files along with the wsu:id defined in them. For eg. as you can see the template files are named as wsp-sp-<version>-<BindingSupported>.xml.

The wsu:ids withing each template file also follows a naming convention. For eg. the wsp-sp-1-2-ws2007HttpBinding.xml has the convention as <binding>-<token>-<is_sc_enabled>-<algorithmSuite>

Figure 15. Template files and the wsu:ids within
Template files and the wsu:ids within

Conclusion

This article described the basic scenario where DataPower and WCF .NET client can inter operate using Kerberos tokens using WSHttpBinding/WS2007HttpBinding. It explained how WebSphere DataPower can be used to off-load the security tasks from a web server. This article had three main sections where it detailed a) how to prepare the Kerberos environment, b) how to configure the .NET WCF Client and c) finally how to configure the Websphere DataPower device. It also explained how one can enable secure conversation on both the client and the DataPower device. The Troubleshooting section of this article explained the 'gotchas' and provided solutions to various issues one might encounter while configuring the Windows Client or the DataPower device. Finally the article also highlighted the new content added in the 3.8.0 release of WebSphere DataPower.


Download

DescriptionNameSize
Examplesattachment.zip18MB

Resources

Learn

Get products and technologies

Discuss

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=470449
ArticleTitle=Offload WebSphere web services security tasks to IBM WebSphere DataPower SOA Appliances: Part 5: Configuring a web service proxy to interoperate with WCF .NET client using Kerberos Tokens with or without secure conversation
publish-date=03012010