Secure Web services with WebSphere Application Server and Microsoft Windows Communication Foundation Abstract

Secure Web services with WebSphere Application
Server and Microsoft Windows Communication
Foundation
Salim Zeitouni
Advisory Software Engineer, WebSphere Web Services Interoperability
IBM, Research Triangle Park, NC
Derek Ho
Advisory 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 WSSecurity Kerberos Token Profile V1.1 specification. Message-level security using WSSecurity 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/[email protected] 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
The principal name.
@ZEITOUNI8.RALEIGH.IBM.COM
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.
The principal
-ptype KRB5_NT_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/[email protected]
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.
2.
3.
4.
5.
Ensure that the WCF service provider system is part of your Domain.
For system login, specify echoprovider as the user name.
Specify Kerberos1 for the password.
Specify the name of your Microsoft Domain; in our case it is ZEITOUNI80.
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/[email protected]
Number of entries: 1
[1] Service principal:
krbtgt/[email protected]
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
[email protected] 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.
2.
3.
4.
Select Services > PolicySets > Application policy sets.
Select MyKerberosV5Policyset.
Note that the WS-Security and WS-Addressing policies are enabled.
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, WSAddressing 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-profile1.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.
5.
6.
7.
Select com.ibm.wsspi.wssecurity.krbtoken.targetServiceName.
Click Edit and then update with the Value field to echoSrvProvider.
Click Apply.
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
2
1
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.
4
2
1
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.
2.
3.
4.
5.
6.
7.
In the left pane, select Service > Service client.
Select EchoService, then MyProviderGeneralBindings, then WS-Security.
Select Keys and certificates.
Select gen_reqKRBsignkeyinfo.
Under the “Requires derived keys” section, specify 16 for the Key length field.
Click OK, and then Save.
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.
2.
3.
4.
5.
Open the Service Configuration Editor.
Select File > Open > Config File > WCFService.
Select wswindowsservice.exe.config, and click Open.
In the left pane, select Bindings EchoSOAP(customBinding).
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:
WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12
BasicSecurityProfile10
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.
b.
c.
d.
e.
f.
g.
h.
AuthenticationMode to Kerberos
Default Algorithm to Basic128Rsa15
MessageProtectionOrder to SignBeforeEncryptAndEncryptSignature
MessageSecurityVersion to:
WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12
BasicSecurityProfile10
requireDerivedKeys to true
requireSecurityContextCancellation to true
requireSignatureConfirmation to true
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 JAXWS==>>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