Secure Web services with WebSphere Application Server and Microsoft Windows Communication Foundation Salim ZeitouniAdvisory Software Engineer, WebSphere Web Services Interoperability IBM, Research Triangle Park, NC Derek HoAdvisory Software Engineer, WebSphere Web Services Development IBM, Austin, Texas

Abstract

Learn how to configure a Kerberos environment to secure SOAP messages exchanged between IBM® WebSphere® Application Server and Microsoft® Windows® Communication Foundation. This article demonstrates the steps using the Service Endpoint Interface samples available in WebSphere Application Server.

© Copyright International Business Machines Corporation 2009. All rights reserved.

INTRODUCTION ........................................................................................................................................ 3 PREREQUISITES........................................................................................................................................ 3 OVERVIEW OF THE KERBEROS ENVIRONMENT........................................................................... 5

CONFIGURE MICROSOFT WINDOWS 2003 ACTIVE DIRECTORY AND KERBEROS SERVER ........................... 6 CONFIGURE KERBEROS ON THE WCF SERVICE PROVIDER........................................................................ 10 CONFIGURE KERBEROS ON THE WCF SERVICE CLIENT ............................................................................ 11

CONFIGURING APPLICATION SERVER FOR KERBEROS AUTHENTICATION .................... 11 CONFIGURE KERBEROS ON APPLICATION SERVER SERVICE PROVIDER..................................................... 11 CONFIGURE KERBEROS ON THE APPLICATION SERVER SERVICE CLIENT .................................................. 14

CREATE A POLICY SET FOR APPLICATION SERVER WEB SERVICE .................................... 15 CONFIGURE GENERAL BINDINGS FOR THE SERVICE PROVIDER......................................... 17 CONFIGURE GENERAL BINDING FOR SERVICE CONSUMER .................................................. 22 ATTACH POLICY SETS AND BINDINGS TO CONSUMER AND PROVIDER............................. 28

ATTACH POLICY SET AND BINDINGS TO THE ECHOSERVICE PROVIDER ..................................................... 29 ATTACH POLICY SET AND BINDING TO ECHOSERVICE CONSUMER CLIENT................................................ 30

CHANGING THE SIZE OF SIGNING KEYS........................................................................................ 32 TEST THE ECHOSERVICE.................................................................................................................... 34

START THE SEI SAMPLES DEMO USER INTERFACE .................................................................................... 34 TEST THE ECHOSERVICE CLIENT AND SERVICE......................................................................................... 35

CONFIGURING WCF SERVICE PROVIDER...................................................................................... 36 CONFIGURING WCF SERVICE CONSUMER.................................................................................... 37 TEST THE WCF SAMPLES .................................................................................................................... 39

START THE WCF SERVICES ...................................................................................................................... 39 RUN THE WCF CLIENT ............................................................................................................................. 39

TEST INTEROPERABILITY BETWEEN WEBSPHERE AND WCF ............................................... 40 TEST THE WCF CLIENT TO WEBSPHERE SERVICE .................................................................................... 41 TEST THE WEBSPHERE CLIENT TO WCF SERVICE .................................................................................... 41

SUMMARY................................................................................................................................................. 41 RESOURCES.............................................................................................................................................. 42

2

Introduction This article describes how to use the WebSphere Application Server V7.0.0.1 Service Endpoint Interface samples to demonstrate Kerberos interoperability with Microsoft Windows Communication Foundation V3.5. It provides step-by-step configurations for SOAP message security interoperability using the WS-Security Kerberos Token. This article is intended for Web services developers and architects who plan to develop Web services across these platforms. You should have a basic understanding of Java™ programming, Web services development, Web Services Description Language (WSDL), SOAP, and Kerberos. WebSphere Application Server (hereafter referred to as Application Server) provides Web services security support for the Kerberos token that is based on the OASIS WS-Security Kerberos Token Profile V1.1 specification. Message-level security using WS-Security allows the use of a variety of types of security tokens. One type of security token in popular use is the Kerberos token. The Kerberos token can be transmitted as the security token for Web services message-level security. It provides such protection mechanisms as authentication, message signature, and message encryption. The Application Server configuration model for the Kerberos token has support for Java APIs for XML-based JAX-WS and JAX-RPC applications. In this article, you learn how to use the JAX-WS WS-Security Kerberos implementation available in Application Server. The JAX-RPC implementation is not discussed. This article focuses on:

• Configuring the Application Server Kerberos token for authentication, message signature, and message encryption.

• Configuring a Windows Communication Foundation (WCF) sample so that it interoperates with the Application Server provider and consumer.

This article assumes that you are familiar with Kerberos and with the definitions of Kerberos-related terminology such as Key Distribution Center (KDC), keytab files, and related topics.

Prerequisites You must have the following software installed to replicate the scenario depicted in this article. Note that the scenario assumes a two-system environment (system A and system B): On System A, a Windows 2003 Server machine:

• Active Directory on a Windows Domain Controller. A Windows domain uses a Kerberos Key Distribution System (KDC) for authentication and is a component

3

of the Windows Active Directory server. (See How do I install Active Directory on my Windows Server 2003 server for details.)

• The Windows Server 2003 Service Pack 1 Support Tools. The Windows Support Tools include the setspn and ktpass Kerberos utilities needed to create required Service Principle Names (SPNs).

On System B, which serves as both the WCF Web service provider/consumer and the Application server provider/consumer.

• Microsoft .Net Framework 3.5 • Windows SDK for Windows Server 2008 and .Net Framework 3.5. The SDK

contains such utilities as svcconfigeditor, used to edit the WCF client and service custom bindings.

• WebSphere Application Server Version V7.0.0.1. Even though Application Server V7.0 supports the Organization for the Advancement of Structured Information Standards (OASIS) WS-Security Kerberos Token Profile V1.1 specification, you need Application Server Version 7.0.0.1 installed because it bundles new general bindings, policy sets, and run time used in this article.

Note that the Application Server V7 FP1 installation process does not import the new Kerberos general bindings and policy set required by this article to existing Application Server profiles. This article assumes that you create a new Application Server profile after the Application Server V7 FP1 is installed to make use of these bindings and policy set.

• The Service Endpoint Interface (SEI) samples available with Application Server

V7 FP1. The samples are located in the <Application_Server_Home>/samples/lib/JaxWSServicesSamples directory. You can install the EAR file (JaxWSServicesSamples.ear) using the Integrated Solutions Console. Once the SEI samples are installed, validate that they are running properly as noted in Test the EchoService section

• The WCF samples available with this article. Download and uncompress. The

WCFSecure folder contains two folders: WCFClient, and WCFService.

WCFClient contains: • WSWindowsClient executable – The compiled WCF Web services

client. • WSWindowClient.exe.config – The customBinding file for the

WSWindowsClient. • WSWindowsClient.cs. – The C# code for the client, which was

included to show the source code used in the WSWindowsClient.

WCFService contains: • WSWindowsService executable – The compiled WCF Web service. • WSWindowService.exe.config – The customBinding file for the

4

• WSWindowsService. • WSWindowsService.cs. – The C# code for the service, which was included to show the source code used in the WSWindowsService.

Overview of the Kerberos environment At a high level, the Kerberos protocol makes use of a trusted third-party server known as the Key Distribution Center (KDC) for authentication and the creation of a shared secret. This shared secret is then used to derive the symmetric keys used to exchange encrypted information between a client and server. To be more specific, a client first requests a Ticket Granting Ticket (TGT) from a KDC. It then uses the granted TGT to request a service ticket for a target service from the KDC. The client then sends the service ticket in the form of an Application REQuest (AP_REQ packet) to the target service to complete the authentication prior to accessing a Web service. Following the OASIS Kerberos token profile, WebSphere Web Services security captures and attaches the initial form of the service ticket to the SOAP message as a BinarySecurityToken to achieve authentication with the target Web services. For message protection, the Web services security derives signing and encryption keys from the session key stored in the service ticket. This article assumes the use of the Windows Kerberos implementation which is integrated into Active Directory. For the WCF scenario, a user must be logged onto the Windows 2003 Domain/Realm. This is essential as the user must have acquired Kerberos credentials from the Domain. For the WebSphere scenario, the user isn’t required to be logged onto the Windows Domain because the WebSphere provider and consumer implementations perform that based on service and client bindings. In a real-life scenario, you could have the various service providers and consumers and the Active Directory distributed on up to five machines. This article simplifies the scenario by only requiring two systems: a Windows Active Directory/Domain Controller on one system and both the Application Server and WCF service providers and consumers on the second system. The Application Server and WCF providers and consumers can be run on the same system as long as the user logged onto the system is associated with the SPN and has acquired Kerberos credentials from the Domain Controller; local logons will not work. In our case, this Windows user is echoprovider. Below is the Kerberos configuration needed for this article:

• Configure Microsoft Windows 2003 Active Directory and Kerberos server • WCF provider user account for the WCF service

5

• WCF consumer user account for the WCF client • Application Server consumer user account for the Application Server

client • SPNs for the Web services • Kerberos keytab for Application Server Web service provider and

consumer • Configure Kerberos on the WCF service provider

• User has acquired Kerberos credentials from the Domain Controller; local logons will not work.

• Configure Kerberos on the WCF service client • User has acquired Kerberos credentials from the Domain Controller; local

logons will not work. • Configure Kerberos on Application Server service provider:

• Keytab and Kerberos configuration files • Configure Kerberos on the Application Server service client

• Kerberos configuration files

By convention, a Kerberos SPN is divided into three parts: the service, the instance, and the Kerberos realm name. The conventional format of the Kerberos service principal name is service/<fully qualified hostname>@KERBEROS_REALM. The service name is the first part of the Kerberos SPN. The fully qualified hostname is the system name where the service is running on. The KERBEROS_REALM is the name of your Kerberos Realm. For this article, the SPN configured is echoSrvProvider/echoservice.raleigh.ibm.com @ZEITOUNI8.RALEIGH.IBM.COM. So our service name is echoSrvProvider while the hostname the service is running on is echoservice.raleigh.ibm.com. The Kerberos Realm that this article uses is ZEITOUNI8.RALEIGH.IBM.COM. As you implement this scenario, you must customize the SPN of your web service to match your system hostname and realm configuration. That is, if the system fully qualified hostname of the web service host is system1.web.com and the Windows Domain name (Kerberos realm) is MY.KERBEROS.DOMAIN, ensure the configuration is updated to specify an SPN of echoSrvProvider/system1.web.com @MY.KERBEROS.DOMAIN as you implement in your environment. Note: The Windows Domain (MY.KERBEROS.DOMAIN ) is case-sensitive and must be specified in uppercase throughout the configuration. Also, the fully qualified hostname should be a valid hostname that is resolvable by the configured Domain Name Server (DNS) or hosts file.

Configure Microsoft Windows 2003 Active Directory and Kerberos server

6

You start by creating the required WCF service provider user account on the Domain Controller. Name the service user account echoprovider and set the password to Kerberos1.

1. Start Active Directory Users and Computers wizard. 2. Under Users, create a new user account named echoprovider.

3. Set the password to Kerberos1. Do not select "User must change password at next

logon”. 4. Your account properties should look similar to the following:

7

Because you are planning to run the WCF consumer on the same machine as the WCF provider you don’t need to create a consumer user account. Now create the consumer user account to be used by the Application Server client.

1. Launch the Active Directory Users and Computers wizard. 2. Under Users, create a new user account named wasconsumer. 3. Set the password to Kerberos1. Do not select "User must change password at next

logon”.

The next step is to create the Service Principal Names (SPNs) for both the WCF and Application Server web services. This is done on the Domain Controller. The Windows Server 2003 Service Pack 1 Support Tools provides the setspn.exe and kpass.exe programs to do this. Use the kpass.exe utility, which also provides the option to export the keytab file needed by WebSphere.

1. On machine A (the Active Directory machine), start an SDK command line window by selecting Start menu > Windows Support Tools > Command Prompt as shown below.

8

2. A command window opens in the C:\Program Files\Support Tools directory where the ktpass.exe utility is located.

3. Run the ktpass.exe command with the options indicated below to create and export the keytab file. Note that there are several ktpass.exe versions available on the web and each behaves differently. This article assumes the use of the ktpass.exe the version available in the Windows Server 2003 Service Pack 1 Support Tools.

C:\Program Files\Support Tools>ktpass.exe -out c:\echoServiceProvider.keytab -princ echoSrvProvider/echoservice.raleigh.ibm.com@ZEITOUNI8.RALEIGH.IBM.COM -pass Kerberos1 -mapUser echoprovider -mapOp set -ptype KRB5_NT_PRINCIPAL -crypto RC4-HMAC-NT Option Explanation -out c:\echoServiceProvider.keytab The key is written to

this output file. -princ echoSrvProvider/echoservice.raleigh.ibm.com @ZEITOUNI8.RALEIGH.IBM.COM

The principal name. The realm must be in uppercase.

-mapUser echoprovider The key is mapped to the user, echoprovider.

-pass Kerberos1 This option is the password for the user ID.

-mapOp set This option sets the mapping.

-ptype KRB5_NT_PRINCIPAL The principal type. KRB5_NT_PRINCIPAL indicates the general principal type.

-crypto RC4-MAC-NT This option uses the

9

RC4-HMAC-NT encryption type.

4. The output should indicate that the mapping from echoSrvProvider/echoservice.raleigh.ibm.com to echoprovider was successful as shown below.

Targeting domain controller: zeitouni8.zeitouni8.raleigh.ibm.com Using legacy password setting method Successfully mapped echoSrvProvider/echoservice.raleigh.ibm.com to echoprovider. Key created. Output keytab to c:\echoServiceProvider.keytab: Keytab version: 0x502 keysize 104 echoSrvProvider/echoservice.raleigh.ibm.com@ZEITOUNI8.RALEIGH.IBM.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 10 ety pe 0x17 (RC4-HMAC) keylength 16 (0x0840d6b2208a60cc871ec8dedbbf14e2)

5. Save the echoServiceProvider.keytab as you must copy it to the Application Server service provider system later.

6. To validate that the SPN in the Active Directory registry is mapped to the correct user, you can use the setspn.exe command to list the SPN for a particular user account.

C:\Program Files\Support Tools>setspn.exe -L echoprovider Registered ServicePrincipalNames for CN=echoprovider,CN=Users,DC=zeitouni8,DC=raleigh,DC=ibm,DC=com: HTTP/echoServiceProvider

Configure Kerberos on the WCF service provider

For the Kerberos WCF provider to work, it must be running under the user account that is associated with the SPN. In our case, that user is echoprovider. The user logged into this Windows machine must have acquired Kerberos credentials from the Domain Controller by logging in to the Domain; local logons will not work. This is essential as the user must have acquired Kerberos credentials from the Domain. The WCF service consumer was tested on Windows 2003 Server Edition but a comparable Windows machine that supports the Kerberos protocol could be used.

1. Ensure that the WCF service provider system is part of your Domain. 2. For system login, specify echoprovider as the user name. 3. Specify Kerberos1 for the password. 4. Specify the name of your Microsoft Domain; in our case it is ZEITOUNI80. 5. Press OK and you should succeed in logging into your Domain Controller.

10

Configure Kerberos on the WCF service client

The same machine that you used for the Application Server and WCF service provider will be used for the WCF consumer.

Ensure that the user (in our scenario echoprovider) logged into this Windows machine has acquired Kerberos credentials from the Domain Controller by logging into the Domain; local logons will not work.

Configuring Application Server for Kerberos authentication You can configure Application Server to use Kerberos as the authentication mechanism at the Global security level. If configured, the configuration will be used not only for Kerberos WS-Security but also for J2EE security. If Kerberos Global Security is not enabled, Application Server V7 FP1 by default looks for the Kerberos-related files in the c:\winnt directory for the Windows 2003 platform. Therefore, you will not set up Global Security to use Kerberos as the authentication mechanism; rather, you will simply copy the required Kerberos file into the c:\winnt directory.

Configure Kerberos on Application Server service provider

As mentioned previously, the Kerberos implementation for Application Server V7 FP1 looks for the Kerberos-related files in the c:\winnt directory by default when using a

11

Windows 2003 platform. The Kerberos files that are required on the Application Server service are the SPN keytab file and the Kerberos configuration file (krb5.ini).

First, transfer the echoServiceProvider.keytab file created in the previous step for the echoprovider service into the c:\winnt directory of the Application Server machine.

Note: If more than one service principal exists on a host using Kerberos authentication, the contents of the keytab file can be merged into a system-wide keytab containing all the keys for services running on that machine. Because you are using only one principal on the WebSphere machine, just assign the echoprovider keytab file to the krb5.ini file.

Second, provide a Kerberos configuration file that WebSphere can use. You can create this configuration file and copy it to the proper location using the wsadmin createKrbConfigFile command.

Follow these steps to configure Kerberos for Application Server service provider:

1. Copy the echoServiceProvider.keytab file from the Active Directory system to the Application Server system and place it in the c:\winnt directory. (Create c:\winnt directory if it does not exist.)

2. Start the wsadmin utility from the WebSphere bin directory. 3. Run the $AdminTask createKrbConfigFile command with the options shown

below to create the krb5.ini file

wsadmin>$AdminTask createKrbConfigFile {-krbPath c:/winnt/krb5.ini -realm ZEITOU NI8.RALEIGH.IBM.COM -kdcHost zeitouni8.raleigh.ibm.com -dns raleigh.ibm.com –keytabPath c:/winnt/echoServiceProvider.keytab}

The command $AdminTask help createKrbConfigFile provides help for the command. You need to ensure that you specify the correct hostname and domain for your environment using the kdcHost and dns options, respectively.

4. A krb5.ini file is created in the c:\winnt directory. The following shows sample contents of this file.

[libdefaults] default_keytab_name = c:\winnt\echoServiceProvider.keytab default_realm = ZEITOUNI8.RALEIGH.IBM.COM default_tkt_enctypes = rc4-hmac default_tgs_enctypes = rc4-hmac default_checksum = hmac-md5 kdc_timesync = 0 kdc_default_options = 0x40000010 clockskew = 300 check_delegate = 0 ccache_type = 3

12

kdc_timeout = 60000 [realms] ZEITOUNI8.RALEIGH.IBM.COM = { kdc = zeitouni8.raleigh.ibm.com }

Important: Ensure that you have a common encryption type for the Kerberos configuration file, the Kerberos keytab file, the Kerberos service principal name, and the Kerberos client. For example, if the Kerberos client uses the RC4-HMAC encryption type, the target server must also support the RC4-HMAC encryption type and the Kerberos configuration file must list RC4-HMAC first in default_tgt_enctypes and default_tkt_enctypes. RC4-HMAC encryption is only supported when using a Windows 2003 Server as KDC. RC4-HMAC encryption is not supported with a Windows 2000 Server as KDC.

Now that you have the required Kerberos configuration files on the Application Server service provider system, you can use the Kerberos kinit.exe command utilities to ensure this Kerberos infrastructure is working between the Application Server machine and the Domain Controller.

1. Start a command line and cd to the <Application_Server_Home>\java\jre\bin directory.

2. Type kinit.exe -k -t c:\winnt\echoServiceProvider.keytab. If the command is successful, the output indicates authentication of the principal and gets a "Ticket granting Ticket" (TGT). Also the Kerberos credential cache is stored in the default location under c:\Documents and Settings.

C:\Websphere\AppServer\java\jre\bin>kinit.exe -k -t c:\winnt\echoServiceProvider.keytab Done! New ticket is stored in cache file C:\Documents and Settings\Administrator\krb5cc_Administrator If an error occurs, check the following:

• Make sure that the clock of the Application Server V7 machine is synchronized with the Active Directory/Key Domain Controller machines.

• Ensure that the Kerberos realm name is not all uppercase throughout the keytab and configuration files.

• Check whether the key has changed since you last updated the keytab. Regenerate the keytab file and place it in the c:\winnt directory as noted above.

3. From the <Application_Server_Home>\java\jre\bin directory, use the klist.exe

command to list the TGT currently available on the WebSphere machine.

13

C:\Websphere\AppServer\java\jre\bin>klist.exe Credentials cache: C:\Documents and Settings\Administrator\krb5cc_Administrator Default principal: echoSrvProvider/echoservice.raleigh.ibm.com@ZEITOUNI8.RALEIGH.IBM.COM Number of entries: 1 [1] Service principal: krbtgt/ZEITOUNI8.RALEIGH.IBM.COM@ZEITOUNI8.RALEIGH.IBM.COM Valid starting: Thursday, September 25, 2008 at 2:46:46 PM Expires: Friday, September 26, 2008 at 12:46:46 AM

Configure Kerberos on the Application Server service client

The only Kerberos configuration file the service consumer (the client) requires is the krb5.ini file. For our scenario, the Application Server service consumer will run on the same machine as the Application Server service provider; therefore it will use the same krb5.ini file (located in the c:\winnt directory).

To access the web service, the Application Server service consumer will use the wasconsumer ID created previously. The user ID is configured in the Application Server client general binding in the Configure general binding for Service consumer section.

In this section, you want to make sure that the wasconsumer credentials can be authenticated by the KDC server. You will use the kinit.exe utility as follows to ensure that the Application Server client Kerberos infrastructure is in place.

1. Start a command line and cd to the <Application_Server_Home>\java\jre\bin directory.

2. Run the command kinit command as shown below. (Note that the –c argument stores the wasconsumer credentials into the wasconsumer-cache file.) If successful, the command returns with no error after it has authenticated the principal.

C:\WebSphere\AppServer70\java\jre\bin>kinit wasconsumer@ZEITOUNI8.RALEIGH.IBM.COM Kerberos1 -c FILE:/wasconsumer-cache

• The command may return with an error stating status code: 24 message: Pre-authentication information was invalid. Again, the key might have changed since you last authenticated with the KDC as the password possibly changed. Reset the password for user wasconsumer to be Kerberos1 and re-issue the kinit.exe command.

14

Create a policy set for Application Server Web service Application Server V7 FP1 ships several default policy sets that are pre-configured for certain common scenarios. You will use the Kerberos V5 WSSecurity default policy set that ships with Application Server V7.0.0.1 . Important: The installation process for Application Server V7 FP1 does not import the new Kerberos general bindings and policy set required by this article to existing Application Server profiles. This article assumes that you create a new Application Server profile after the Application Server V7 FP1 is installed to make use of these Kerberos general bindings and policy set. To create a custom policy set from the shipped Kerberos V5 WSSecurity default policy set:

1. Log into the Integrated Solutions Console (for example, http://localhost:9080/ibm/console/).

2. Click on the Services link in the left navigation bar. 3. Expand the Policy sets and click on the Application policy sets link to launch

the Application policy sets panel. 4. Click Import from the collection table, and select “From Default Repository…”

from the drop-down menu. This launches the Import panel.

1

2 3

5. Select the Import a copy radio button and specify MyKerberosV5Policyset as the name of copy.

15

6. Select Kerberos V5 WSSecurity default policy set, then click OK to create the copy.

7. Save the changes. No changes are required for the MyKerberosV5Policyset policy set, but you can view this newly created policy set as follows to get an understanding of its requirements:

1. Select Services > PolicySets > Application policy sets. 2. Select MyKerberosV5Policyset. 3. Note that the WS-Security and WS-Addressing policies are enabled. 4. Select Security > Main policy.

16

5. In the Main policy dialog, note Include timestamp in security header is

checked. 6. The Security header layout is set to Strict. 7. The signature confirmation flag is selected. 8. Click Request message part protection to determine what message parts are

encrypted and signed for the request. This policy signs the Timestamp, WS-Addressing header element, and Body, and encrypts the Signature and Body

9. Click Response message part protection to determine what message parts are expected to be encrypted and signed for the response. This policy signs the Timestamp, WS-Addressing header element, and Body, and encrypts the Signature and Body.

10. Click on Symmetric signature and encryption policies > Action > Edit Selected policy to determine the Kerberos token used by this policy. Note that you are using the http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ Kerberos token type for the Local part which will enable us to interoperate with the WCF implementation.

11. Click OK, and then Save.

Configure general bindings for the service provider Now that you have a policy set for our service, ensure that you have a compatible binding for it. Application Server V7.0.0.1 ships a new version of the default provider binding that is not available in V7.0.0.0. The name of this new general binding is “Provider

17

sample V2.” Make a copy of this binding and then update it so that it can interoperate with the WCF client. The following steps show how to create a new general provider policy set binding based on the shipped default “Provider sample V2.”

1. Click on the General provider policy set bindings links in the left navigation bar under Services > Policy sets.

2. Check the Provider sample V2 checkbox. 3. Click Copy…

4. Specify MyProviderGeneralBindings as the name. 5. Click OK and save the changes.

1

2

6. Click the MyProviderGeneralBindings link in the General provider policy set bindings collection table to navigate to the general bindings detail page.

18

7. Click on the WS-Security link to navigate to the bindings detail for web service security.

19

Click on the Authentication and protection link to navigate to the detail page for:

• Protection tokens (tokens used for signing and encryption). • Authentication tokens (tokens used for authentication). • Signing information and encryption information for both request and response

messages.

20

•

The Organization for the Advancement of Structured Information Standards (OASIS), in its Web services Security Kerberos Token Profile v1.1 specification, suggests that the use of SHA1 encoded key for every subsequent message after the initial AP_REQ packet is accepted. Application Server V7.0 supports this SHA1 caching as described in the profile, by default. However, Application Server also provides the ability to generate new AP_REQ tokens for each request with the existing service Kerberos ticket. When you interoperate with the WCF Service, you do not want to use SHA1 caching; instead you want to generate an AP_REQ packet for each request.

You need to update the Kerberos protection outbound token to generate an AP_REQ packet for each request as follows:

1. Click on gen_krb5token to navigate to the Kerberos token generator for the signing and encryption of the Kerberos client request.

2. Under the Kerberos outbound token custom property section, specify com.ibm.wsspi.wssecurity.kerberos.attach.apreq in the Name field and true in the Value field as shown below.

21

3. Click Apply. 4. Click Save to save the changes to master configuration.

This is the only change needed. You can leverage this default binding as it is already configured to consume and respond to a Kerberos-protected request from a service consumer.

Configure general binding for service consumer The next step is to create a general client binding that can be used by the client to initiate requests to the service provider. Application Server V7.0.0.1 ships a new default binding for the service consumer. Use the following steps to create a new general client policy set binding based on the shipped default “Client sample V2” and modify it according to our client credentials.

1. Click on the General client policy set bindings links in the left navigation bar under Services > Policy sets.

2. Select the Client sample V2 checkbox. 3. Click Copy… 4. Specify MyConsumerGeneralBindings as the name. 5. Click OK. 6. Click Save to save the changes to master configuration.

22

1

2

7. Click the MyConsumerGeneralBindings link in the “General client policy set bindings” collection table to navigate to the general bindings detail page.

23

8. Click on the WS-Security link to navigate to the bindings detail for web service security.

24

9. Click the Authentication and protection link to navigate to the detail page for:

• Protection tokens (tokens used for signing and encryption). • Authentication tokens (tokens used for authentication). • Signing information and encryption information for both request and response

messages.

25

1. You need to update the Kerberos protection outbound token with the correct SPN of the service provider.

1. Click on gen_krb5token to navigate to the Kerberos token generator for

the signing and encryption of the Kerberos client request.

2. Under custom properties, specify the proper values for

com.ibm.wsspi.wssecurity.krbtoken.targetServiceName and com.ibm.wsspi.wssecurity.krbtoken.targetServiceHost.

3. The targetServiceName for our scenario is echoSrvProvider.

26

4. Select com.ibm.wsspi.wssecurity.krbtoken.targetServiceName. 5. Click Edit and then update with the Value field to echoSrvProvider. 6. Click Apply. 7. The targetServiceHost for our scenario is

echoservice.raleigh.ibm.com. 8. Select com.ibm.wsspi.wssecurity.krbtoken.targetServiceName. 9. Click Edit and then update the Value field to

echoservice.raleigh.ibm.com. 10. Click Apply as shown below.

As with the Application Server service provider, you need to update the Application Server client to generate an AP_REQ packet for each request so that it can interoperate with the WCF service provider:

1. Under the Kerberos outbound token, Custom properties section, specify com.ibm.wsspi.wssecurity.kerberos.attach.apreq in the Name field and true in the Value field.

2. Click Apply. 3. Click Save to save the changes to the master configuration.

27

You also need to update the Kerberos outbound protection to specify the proper client credentials.

1. Click Callback handler in the dialogue shown above. 2. Under Basic Authentication, specify wasconsumer (which you configured

previously on the Active Directory) as the username of the Application Server service consumer.

3. Specify Kerberos1 for the Password and Confirm password fields.

4. Click Apply. 5. Click Save to save the changes to the master configuration.

Attach policy sets and bindings to consumer and provider The next step is to attach the policy sets and general bindings to the EchoService of the JaxWSServicesSamples. You will attach:

1. MyKerberosV5Policyset (policy set) and MyProviderGeneralBindings (general provider policy set bindings) to the EchoService provider service.

2. MyKerberosV5Policyset (policy set) and MyConsumerGeneralBindings (general client policy set bindings) to the EchoService consumer client.

28

Attach policy set and bindings to the EchoService provider Click Services > Service providers link on the left navigation bar to list all the JAX-WS Web Service providers installed:

Click on the EchoService link in the collection table to navigate to the detail page.

1. Select the checkbox of the EchoService row as shown below. 2. Click on the Attach Policy Set menu and select MyKerberosV5Policyset from

the drop-down menu. 3. Select the checkbox of the EchoService row. 4. Click the Assign Binding menu and select MyProviderGeneralBindings from

the drop-down menu.

29

1

2 4

3

5. The Policy Set Attachments collection table should look like the following:

6. Save the changes.

Attach policy set and binding to EchoService consumer client Click the Services > Service clients link on the left navigation bar to list all the JAX-WS web service clients (consumers) installed:

30

Click on the EchoService link in the collection table to navigate to the detail page.

1. Select the checkbox of the EchoService row as shown below. 2. Click the Attach Policy Set menu and select MyKerberosV5Policyset from the

drop-down menu. 3. Select the checkbox of the EchoService row. 4. Click the Assign Binding menu and select MyConsumerGeneralBindings from

the drop-down menu.

1

24

3

The “Policy Set Attachments” collection table should look like the following:

31

5. Save the changes.

Changing the size of signing keys Application Server V7 FP1 and WCF V3.5 use a different key size for the signing key. WebSphere uses a key size of 20 bytes, and WCF allows a maximum key length of 16 bytes. To be interoperable with the WCF custom Kerberos binding, the configuration of the Application Server client and service key sizes must match. In this section, you’ll set up the custom bindings of the WebSphere provider to have a signing key size of 16 bytes. For the WebSphere provider general binding, set the symmetric signature generator record to sign with a key size of 16 bytes as follows:

1. In the left pane, select Services > Service providers. 2. Select EchoService, then MyProviderGeneralBindings, then WS-Security. 3. Select Keys and certificates. 4. Select gen_respKRBsignkeyinfo 5. Under the “Requires derived keys” section, specify 16 for the Key length field. 6. Click OK, and then Save.

32

Just as the WebSphere provider (service) signing key must use a 16-byte key size to interoperate with a WCF client, the Application Server consumer (client) signing key must also be 16 bytes so that it can interoperate with the WCF service. To update the key size for the client:

1. In the left pane, select Service > Service client. 2. Select EchoService, then MyProviderGeneralBindings, then WS-Security. 3. Select Keys and certificates. 4. Select gen_reqKRBsignkeyinfo. 5. Under the “Requires derived keys” section, specify 16 for the Key length field. 6. Click OK, and then Save. 7. Stop and restart Application Server.

33

Test the EchoService Now that you have finished configuring the Application Server client and service, you can test to ensure that WebSphere-to-WebSphere Kerberos flows are operational. We’ll use the SEI Samples demo to test the WebSphere EchoService client to WebSphere EchoService service to validate our security configuration.

Start the SEI samples demo user interface To test the EchoService using the SEI samples demo UI, point your browser to http://localhost:9080/wssamplesei/demo (where 9080 is the port where the Application Server application is running). Note: If you can’t access the SEI samples, make sure you have installed them as noted in the prerequisite section and that the JaxWSServicesSamples Enterprise Applications is started. Via the Application Server administration console, go to Application > Application Types > WebSphere enterprise applications to list and start the JaxWSServicesSamples Enterprise Applications. Also, ensure that the application server has been restarted after the changes made to the general binding, policy set, or the EchoService.

34

Test the EchoService client and service To validate that the EchoService client and EchoService service are properly configured, select Synchronous Echo for Message Type, enter some text (such as test) in the Message String field, enter the hostname and port number of the service endpoint (for example: http://localhost:9080 assuming Application Server is running on port 9080), then click Send Message.

The response box shows the connection status, the Message Request, and the Message Response. Note that the Message Response is JAX-WS==>>test. The service prepends JAX-WS==>> to the Message Request string test. If you see an exception in the Message Response box, check the System.out log and review the security custom binding configurations for both the client and the service. You should resolve these problems before you continue.

35

Configuring WCF Service provider In the section we’ll configure the WCF service provider sample to interoperate with the Application Server Service consumer. The article ships with a WCF service provider and consumer that are already developed and based on the same WSDL as the Application Server service provider and consumer side. The WCF Service provider configuration already has a custombinding called EchoSOAP. This EchoSOAP binding has the httptransport and textMessageEncoding (Soap11WSAddressing10) extensions enabled. You will use the Microsoft Service Configuration Editor to update this binding to include WS-Security. You will add a security binding extension and configure the security settings to match the WebSphere configuration.

1. Open the Service Configuration Editor. 2. Select File > Open > Config File > WCFService. 3. Select wswindowsservice.exe.config, and click Open. 4. In the left pane, select Bindings EchoSOAP(customBinding). 5. In the right pane, click Add to open the Adding Binding Element Extensions

dialog. 6. Select security, then click Add.

7. In the left pane, select security. 8. Set the following settings:

36

• AuthenticationMode to Kerberos • Default Algorithm to Basic128Rsa15 • MessageProtectionOrder to SignBeforeEncryptAndEncryptSignature • MessageSecurityVersion to:

WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10

• requireDerivedKeys to true • requireSecurityContextCancellation to true • requireSignatureConfirmation to true • securityHeaderLayout to Strict

9. Select Save to save the changes to wswindowsservice.exe.config.

Configuring WCF Service consumer In this section you will configure the WCF Client to meet the Kerberos configuration of the WCF Service provider and Application Server Provider.

1. Open the Service Configuration Editor. 2. Select File > Open > Config File > WCFClient. 3. Select WSWindowsClient.exe.config, and click Open. 4. In the left pane, select Bindings EchoSOAP(customBinding), 5. In the right pane, click Add to open the Adding Binding Element Extensions

dialog 6. Select security, then click Add. 7. In the left pane, select security. 8. Change the following settings:

37

a. AuthenticationMode to Kerberos b. Default Algorithm to Basic128Rsa15 c. MessageProtectionOrder to SignBeforeEncryptAndEncryptSignature d. MessageSecurityVersion to:

WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10

e. requireDerivedKeys to true f. requireSecurityContextCancellation to true g. requireSignatureConfirmation to true h. securityHeaderLayout to Strict

9. In the left pane, select Client > Endpoints >EchoServicePort. 10. In the right pane, set the Address value to:

http://<hostname>:port/WSSampleSei/EchoService, where hostname and port are the values for the service endpoint. Assuming your service is running on port 9094, this value is http://localhost:9094/WSSampleSei/EchoService

11. Switch to the Identity tab, and set the ServicePrincipalName to echoSrvProvider/echoservice.raleigh.ibm.com

12. Select Save to save the changes to WSWindowsClient.exe.config.

38

Test the WCF samples In this section, you’ll learn how to run the WCF samples, including how to correctly start the WCF services and use the commands for the WCF client.

Start the WCF services To start the WCF services, do the following:

1. Select Start > Run > cmd to open a command window. 2. Change to the C:\WCFSecure\WCFService directory. 3. Enter WSWindowService.exe -? to see command usage information as shown

below. C:\WCFSecure\WCFService>WSWindowsService.exe -? Usage: WSWindowsService -p [port] -h [hostname] -e [echoSuffix] -f [pingSuffix] Default values: port= 9080 hostname=localhost echoSuffix= "/WSSampleSei/EchoService" pingSuffix= "/WSSampleSei/PingService" Make sure that you start the service using an open port, such as port 9094. Otherwise, you’ll get an error stating that the port is already in use. The following is an example of the correct command line argument usage. C:\WCFSecure\WCFService>WSWindowsService.exe -p 9094 SERVICE>> Echo READY: http://localhost:9094/WSSampleSei/EchoService SERVICE>> Ping READY: http://localhost:9094/WSSampleSei/PingService SERVICE>> Press ENTER to exit the services. To stop the WCF services, press Enter in the command window.

Run the WCF client To run the WCF client, do the following: 1. Select Start > Run > cmd to open a command window. 2. Change to the C:\WCFSecure\WCFClient directory. 3. Enter WSWindowClient.exe -? to see command usage information as shown below. C:\WCFSecure\WCFClient>WSWindowsClient.exe - Incorrect Parameter Format

39

Usage: WSWindowsClient [ -e | -h [hostname] -p [port] -f [urlSuffix] ] -m [testMessage] -s [echo|ping|async] -t [asynctimeout] Options: -e = Create the service proxy with no endpoint address (specify in config) -h hostname= "localhost" -p port= 9080 -f urlSuffix= "/WSSampleSei/EchoService" -m testMessage= "hello" -s service= echo -t asynctimeout= 120 The version of the WCF client used in this article has a new option -e. The client code has been modified to create the service proxy using the endpoint information in WSWindowsClient.exe.config. Therefore, you need to make sure to define the service endpoint address as described in the Configuring WCF Service consumer. You must use the -e option for this test. The following example shows how to run the WCF client from the command line and verify that both the WCF services and client are configured correctly.

1. Configure the service endpoint in the WSWindowsClient.exe.config file to point to the WCF service started in previous section. The service endpoint should be defined as: http://localhost:9094/WSSampleSei/EchoService.

2. Run WSWindowsClient.exe –e. C:\WCFSecure\WCFClient>WSWindowsClient.exe -e CLIENT>> Using Echo endpoint from config file. CLIENT>> Connecting to Echo Service... CLIENT>> Sending message 'HELLO' ... CLIENT>> The answer is 'DotNet==> HELLO' The service response to the client request is DotNet==>>hello. The service prepends DotNet==>> to the test message hello. You should see the hello message in the service window.

Test interoperability between WebSphere and WCF This section describes how to test the interoperability between WebSphere and WCF configured to use Kerberos. By now you should have verified that the WebSphere client to WebSphere service is working correctly, and that the WCF client to WCF service is working correctly.

40

Test the WCF client to WebSphere service To test the WCF client to WebSphere service interoperability, you need to set the service endpoint to be your WebSphere service endpoint in the WSWindowsClient.exe.config file. For example: http://localhost:9080/WSSampleSei/EchoService. Run the WCF client using the same command shown in Run the WCF client . The WebSphere service response to the WCF client request should be JAX-WS==>>hello.

Test the WebSphere client to WCF service To test interoperability between the WebSphere client and the WCF service using the SEI sample UI:

1. Select Synchronous Echo for Message Type. 2. Enter some text (such as test) in the Message String field. 3. Enter the hostname and port number of the WCF service endpoint (for example:

http://localhost:9094). 4. Click Send Message.

The WCF service response to the WebSphere client request should be DotNet==>>test.

Summary This article showed you how to configure a Kerberos environment to secure SOAP messages exchanged between WebSphere Application Server V7.0 and Windows Communication Foundation V3.5. You learned how to modify a Kerberos-based policy set and general binding using the policy-based administration features for JAX-WS Web services deployed Application Server. You also learned how to configure an equivalent Kerberos-based custom binding for WCF. You learned about the differences between how Application Server and WCF handle Kerberos requests. For example, by default Application Server uses the SHA1 encoded key for subsequent message after the initial AP_REQ packet is accepted. On the other hand, WCF uses an AP_REQ packet for each request. You saw how you can configure Application Server to generate an AP_REQ packet for each request so that interoperability between a Windows Communication Foundation client and service and Application Server can succeed. This article also highlighted the fact that Application Server and WCF use a different signing key size. Application Server uses a signing key size of 20 bytes while WCF uses 16 bytes. You learned how to set up Application Server with a 16-byte key size to be interoperable with WCF. Finally, you learned about the Kerberos token type used between the WebSphere provider and consumer to ensure interoperability.

41

Resources

• OASIS WS-Security Kerberos Token Profile Version 1.1 • WebSphere Application Server V7.0.0.1 InfoCenter • How do I install Active Directory on my Windows Server 2003 server • Windows Server 2003 Service Pack 1 Support Tools: The Windows Support

Tools has the Kerberos utilities to create required Service Principle Names (SPNs).

• Microsoft .Net Framework 3.5: For information on the WCF Web service provider/consumer.

• Windows SDK for Windows Server 2008 and .Net Framework 3.5: The SDK contains utilities to configure WCF configuration file.

About the authors Salim Zeitouni works as an advisory software engineer on the IBM WebSphere web services interoperability team. Salim is an active member of the WS-I community, an open industry organization chartered to promote Web services interoperability and currently chairs the Sample Applications Work Group. Prior to joining the web services group, Salim was a team lead on several IBM WebSphere products that provide integrated client-server environment and application development tools to extend business applications and data to mobile users. Since joining IBM in 1996, Salim has worked on several of the WebSphere, Tivoli, and Lotus software products. Derek Ho works as an advisory software engineer in the IBM WebSphere Web Services security team. He is the developer for the OASIS Kerberos Token Profile support in Web services. Prior to joining the Web Services security team, Derek worked on Web Services engine, HTTP transport, and J2EE security in WebSphere. Since joining IBM in 1995, Derek also worked on products such as Component Broker and OS/2. Trademarks IBM and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.

42