You are on page 1of 51

Web Services Security

Cookbook
Using Web Services Technology
in Mixed IBM & SAP Environments

Authors:
Khirallah Birkler (IBM)
Reinhard Heite (IBM)
Martin Raepple (SAP)

August 2006
Web Services Security Cookbook

Index
1. Introduction_________________________________________ 3
1.1. A short overview of WS-Security ______________________________________________4
1.2. An overview of the WS-Security scenarios _____________________________________7
1.3. WS-Security in SAP NetWeaver Web AS J2EE 2004s ___________________________9
1.4. WS-Security in IBM WebSphere Application Server 6___________________________10

2. Key Management ___________________________________ 11


2.1. Key Management for WebSphere ____________________________________________12
2.2. Key Management for NetWeaver ____________________________________________14

3. Integrity Scenario __________________________________ 16


3.1. NetWeaver as a Secure Web Services Provider _______________________________16
3.2. WebSphere as a Secure Web Services Consumer _____________________________20
3.2.1 Configure the Request Generator ____________________________________________20
3.2.2 Configure the Response Consumer __________________________________________24
3.3. Testing the Configuration ___________________________________________________29

4. Authentication Scenario ____________________________ 32


4.1. Enabling Security on WebSphere Application Server ___________________________32
4.2. WebSphere as a Web Services Provider for Authentication______________________34
4.3. NetWeaver as a Web Services Consumer with Authentication ___________________36
4.4. Testing the configuration ___________________________________________________39

5. Encryption Scenario ________________________________ 44


5.1. WebSphere as Web Services Provider with Encryption _________________________44
5.2. NetWeaver as a Web Services Consumer with Encryption ______________________46

6. Conclusion ________________________________________ 49

7. Appendix __________________________________________ 50
7.1. StockQuoteJSP.jsp ________________________________________________________50

August 2006 2
Web Services Security Cookbook

1. Introduction
This paper describes how to apply Web Services Security (WS-Security) in mixed IBM and SAP
environments. WS-Security provides security at the message level -- specifying how to
authenticate, sign or encrypt SOAP messages. For Web Services-based applications that are
developed and running on the respective J2EE environments from IBM WebSphere and SAP
NetWeaver, WS-Security constitutes an important design element.
This guide is intended to be used by IT Architects or IT Specialists who have to build
interoperability scenarios. Therefore, the main focus in this paper is on the configuration of
technical Web Services-based examples that are enhanced by WS-Security.
This document starts by giving a short overview of WS-Security and an introduction of how it is
supported within the WebSphere and NetWeaver environments. Please note that neither WS-
Security nor the supported functionality in the respective environments is covered in-depth.
Readers interested in these topics should consult the references in Table 1.
Subsequently, a short overview is given how to manage the cryptographic keys that are used for
signing and encryption. The last sections of this guide documents the configuration of a
signature scenario, an authentication scenario, and an encryption scenario.
The configurations described herein should be reproducible given that the reader follows the
operational model of our lab environment.

Title Where to find Reference


Web Services Security: http://docs.oasis-open.org/wss/2004/01/oasis- [1]
SOAP Message Security 1.0 200401-wss-soap-message-security-1.0.pdf
(March 2004)
Web Services Security: http://docs.oasis-open.org/wss/2004/01/oasis- [2]
Username Token Profile 1.0 200401-wss-username-token-profile-1.0.pdf
(March 2004)
Web Services Security: X.509 http://docs.oasis-open.org/wss/2004/01/oasis- [3]
Certificate Token Profile 1.0 200401-wss-x509-token-profile-1.0.pdf
(March 2004)
WebSphere Version 6 Web http://www.redbooks.ibm.com/redbooks/pdfs/sg [4]
Services Handbook 246461.pdf
Development and
Deployment (July 2005)
Web Services Cookbook https://www.sdn.sap.com/irj/servlet/prt/portal/prt [5]
Using Web Services root/docs/library/uuid/d6be0241-0d01-0010-
Technology in mixed b8a7-8d53d40be03a
IBM/SAP environments
WS-I Basic Security Profile http://www.ws- [6]
1.0 Working Group Draft i.org/Profiles/BasicSecurityProfile-1.0.html
WS-I Sample Application http://ws- [7]
Implementations for the BSP i.org/deliverables/workinggroup.aspx?wg=samp
leapps
Providing and Consuming http://help.sap.com/saphelp_erp2005/helpdata/ [8]
Web Services, SAP en/31/a6d13f83a14d21e10000000a1550b0/fra
NetWeaver 2004s Online meset.htm
Documentation

Table 1 Additional Documentation

August 2006 3
Web Services Security Cookbook

1.1. A short overview of WS-Security


This chapter introduces the concepts of WS-Security. For the sake of clarity in this discussion,
the following denotations are used (Figure 1):
• the entity that offers a Web Service is denoted as a Web Services Provider
• the entity that calls and therefore uses a Web Service is denoted as a Web Services
Consumer
• A Web Services Consumer issues a SOAP request for calling a Web Service and
receives a SOAP response as a result.

Web Services SOAP Request X Web Services


Consumer SOAP Response Y Provider

Web Service

Figure 1 Some Denotations for the WS-Security Introduction

Securing Web Services can meet different goals and requirements, e.g.
• ensuring that only authorized entities may consume a Web Service
• protecting SOAP messages against tampering by a third party (the requirement of
Integrity)
• protecting SOAP messages against eavesdropping by a third party (the requirement of
Confidentiality)
Different techniques are available to accomplish these goals
• a prerequisite for authorization is the ability to authenticate the Web Services Consumer
• tampering is prevented by signing a SOAP message
• eavesdropping is prevented by encrypting a SOAP message.
These techniques can be supported either at the transport or the message level.

Transport level security applies the techniques to all messages that are transported across a
given HTTP connection (Figure 2). It supports authentication of a Web Service Consumer
using Basic Authentication, meaning that username and password are transported as part of the
HTTP header of each request or client-side X.509 Certificates. Signing or encrypting can be
supported using Secure Socket Layer (SSL). In addition, SSL supports authenticating a Web
Services Provider to the Web Services Consumer and vice versa.

SOAP Request X
Web Services Web Services
Consumer Provider
SOAP Request Y
HTTP Transport with
Basic Authentication

HTTPS Transport
based on SSL

Figure 2 Overview of Transport Level Security for SOAP messages

August 2006 4
Web Services Security Cookbook

Message level security applies the techniques to the respective SOAP messages (Figure 3).
This means that an individual SOAP message can be configured to contain a Username token
for authentication; it can be signed or even encrypted -- completely or partially.

SOAP Request W

Web Services SOAP Response X Web Services


Consumer Provider
SOAP Request Y
Username Token

SOAP
SOAP Response Z Signed

Partially Signed

Encrypted

Figure 3 Overview of Message Level Security for SOAP messages

Thus, message level security offers a fine-grained check on the level signing or encryption is
applied to individual messages. In addition, it provides end-to-end security (Figure 4), e.g. an
encrypted SOAP request can be forwarded to a final provider via an intermediate provider,
without being decrypted in transit.
Intermediate Final
Web Services
SOAP Request Y Web Services SOAP Request Y Web Services
Consumer
Provider Provider

Figure 4 End-To-End Message Level Security

Since transport level security is already supported by standard protocols, WS-Security is


defined as message level security (see [1], [2] and [3]). The standards define how to extend
SOAP messages with message level security. Thereby, they offer some variations on how these
messages are built.
In order to understand the various configuration options that are employed and discussed
during the rest of this document, we will sketch typical structures of a signed, authenticated, and
encrypted SOAP message below.
Figure 5 depicts a typical structure of a signed SOAP message. The security annotations are
inserted into the SOAP header whereas the SOAP body is left unchanged. The security
annotations consist of the Signature Value and additional information that describe how to build
the signature.
The signature is built from the footprint of a timestamp and of the SOAP body. Since an attacker
could easily record the message and send an exact copy of it afterwards to authenticate again,
the timestamp is used to express the creation and expiration times of the security semantics in
the message. Both sources are not used directly, but put into a canonical form, before the
footprint is computed. After that, the footprint is encrypted with the key that is referenced within
the key information box. Within the structure shown, the key information refers to a Security
Token that contains a public key certificate. The private key that belongs to this certificate is
actually used for encrypting the footprint.

August 2006 5
Web Services Security Cookbook

SOAP Header

Security

Security Token

Timestamp

Signature

Signing information

Canonicalization method

Signature method

Reference

Reference

Signature value

Key information
Reference

SOAP Body

Figure 5 Typical structure of a signed SOAP message

A SOAP message with authentication contains a Username token and a timestamp within the
security part of its SOAP header (Figure 6). Within the token, the username and the password
of the Web Services consumer are inserted in clear text.

SOAP Header

Security
Timestamp

Username Token
Username

Password

SOAP Body

Figure 6 Structure of SOAP message with authentication

Using WS-Security encryption for encrypting a username token results in a structure (shown in
Figure 7). In this structure, the username token contains an encrypted username and password
- within the cipher data entry - together with a description of the encryption method.
The credentials are encrypted with a symmetric key that is dynamically generated by the original
sender of the SOAP message. Apparently, the symmetric key must be included in the message,
but not in clear text. Therefore, it gets encrypted with the public key of the receiver of the
message, before it is inserted into the "Cipher Data" box within the "Encrypted key" area of the
SOAP message. The "Key information" entry within this area contains a reference to the public
key, but not the key itself, that is used for encrypting the symmetric key.

August 2006 6
Web Services Security Cookbook

SOAP Header

Security
Encrypted key

Encryption Method

Key information

Security Token Reference

Cipher Data

Reference

Timestamp

Username Token

Encrypted Data

Encryption Method

Cipher Data

SOAP Body

Figure 7 Typical Structure of a SOAP message with encrypted username token

The next sections introduce the WS-Security scenarios that are documented in this paper.

1.2. An overview of the WS-Security scenarios


The WS-Security interoperability scenarios described in this paper are configured in a mixed
IBM/SAP environment like the one depicted in Figure 8. It consists of two nodes, one running
IBM Rational Application Developer (RAD) for development and IBM WebSphere Application
Server for deployment. On the other node, SAP NetWeaver Developer Studio (SAP IDE) for
development and SAP NetWeaver Web Application Server (Web AS) J2EE for deployment is
installed and up and running.
myRad.ctsc.com nw2004s.ctsc.com

IBM Rational Application Developer, V 6.0.1 SAP NetWeaver Developer Studio, 7.0.07

IBM WebSphere Application Server, V 6.0.2 SAP J2EE Application Server 04s, SP07

= development

= deployment

Figure 8 Operational model for configuring WS-Security Interoperability Scenarios

Even though IBM and SAP support WS-Security according to common standards there
nevertheless exists some differences in their respective level of support. For instance, IBM
offers much flexibility by providing a bunch of configuration options, whereas SAP NetWeaver

August 2006 7
Web Services Security Cookbook

has defined a set of profiles -- summarizing configurations options that are commonly found in
typical scenarios.
Thus, the scenarios described in this paper are reduced to a common denominator of the WS-
Security functionality found in both environments and based on the documentation that is
publically available.
The first WS-Security scenario documented in this paper describes how to ensure integrity of
Web Services-based communication by signing SOAP messages with asymmetric keys (Figure
9). In this scenario, IBM WebSphere acts as a consumer to a Web Service that is provided by
SAP NetWeaver. Signing is done using the respective private key of the sender of a SOAP
message (unambiguously identified by the keystore entry labels "ws-signature" for IBM
WebSphere and "NW-Signature" for SAP NetWeaver).
signed with private key of ws-signature

Web Services Consumer Web Services Provider

IBM Rational Application Developer, V 6.0.1


SOAP Request Y SAP NetWeaver Developer Studio, 7.0.07

IBM WebSphere Application Server, V 6.0.2 SAP J2EE Application Server 04s, SP07
SOAP Response X
myRad.ctsc.com nw2004s.ctsc.com
key store key store
ws-signature signed with private key of NW-Signature NW-Signature

Figure 9 Integrity Scenario

For the next scenarios, the roles of the infrastructures are changed, i.e. IBM WebSphere acts as
a provider and SAP NetWeaver as a consumer. The authentication scenario depicted in Figure
10 documents how to add a Username Token containing username and password to a SOAP
request and how to configure the provider to use the token for authenticating the consumer.

authentication with
Username Security Token

Web Services Consumer Web Services Provider

SAP NetWeaver Developer Studio, 7.0.07


SOAP Request Y IBM Rational Application Developer, V 6.0.1

SAP J2EE Application Server 04s, SP07 IBM WebSphere Application Server, V 6.0.2
SOAP Response X

nw2004s.ctsc.com myRad.ctsc.com

Figure 10 Authentication Scenario

Finally, the authentication scenario is extended by encrypting the username token (Figure 11).
Encryption is done using a symmetric key which is generated by the sender of the SOAP
request on-the-fly. The symmetric key is encrypted by the public key of the receiver (part of the
certificate "ws-encryption-certificate").

August 2006 8
Web Services Security Cookbook

authentication with encrypted with public key


Encrypted of ws-encryption-certificate
Username Security Token

Web Services Consumer Web Services Provider

SAP NetWeaver Developer Studio, 7.0.07


SOAP Request Y IBM Rational Application Developer, V 6.0.1

SAP J2EE Application Server 04s, SP07 IBM WebSphere Application Server, V 6.0.2
SOAP Response X

nw2004s.ctsc.com myRad.ctsc.com
key store key store
ws-encryption- ws-encryption
certificate

Figure 11 Encryption Scenario

Before documenting the configurations, the next sections give a short overview of the WS-
Security support in the respective environments.

1.3. WS-Security in SAP NetWeaver Web AS J2EE 2004s


The WS-Security support within SAP NetWeaver Web AS J2EE 2004s includes
• the authentication of SOAP messages based on username/password security tokens
(username token for short) or X.509 client certificates,
• the signature of SOAP messages based on XML signatures, and
• the encryption of security token based on XML encryption.
WS-Security functionality is provided by the runtime of the J2EE Server1. Therefore, it is only
applicable to the entities that are deployed to the J2EE server. No code has to be developed for
WS-Security, since the functions are provided by configuring Web Services artifacts.
Adding WS-Security to existing Web Services comprises a two-step approach (Figure 12):
• Within the SAP IDE, configure the design-time requirements of WS-Security (the what).
For a Web Services Provider, the web services configuration has to be extended,
whereas WS-Security for a deployable proxy is specified within its logical port.
• After deployment, the Visual Administrator is used for adding the technical details of
WS-Security to deployed entities (the how), which is required at runtime. This
configuration is based on security profiles that are derived from security templates. The
profiles are associated with the web services operations.

1
To further improve interoperability based on the WS-I Basic Security Profile (BSP) [6] of the WS-Security service in
SAP NetWeaver WebAS 2004s SP7, it is recommended to install an BSP update that is available with SAP’s
implementation of the WS-I Sample Application (http://www.ws-i.org/SampleApplications/BSP/SAP-BSP-SA-
2006.05.zip). Please follow the instructions of step 2 in the readme.txt which can be found in the download archive.

August 2006 9
Web Services Security Cookbook

SAP NetWeaver Studio


Configure WS-Security (what)
Web Service A

Web Service Configurations SAP J2EE Server Visual Administrator

A --- Security Profile


Configure WS-Security (how)
Deployable Proxy B B --- Security Profile
deploy
Logical Ports

Figure 12 Configuring WS-Security in SAP NetWeaver Web AS

This two-step approach reflects the different roles that take part in configuring WS Security, i.e.
• the application developer states only what he wants in the IDE
• the security administrator uses the Visual Administrator to specify the technical details
at configuration time
During the course of configuration please be aware of the following denotations (Figure 13):
Configuring inbound or outbound properties have different meanings depending on whether
they are applied to a consumer or provider. For a consumer, an inbound property refers to a
SOAP response, whereas an outbound property refers to a SOAP request. For a provider, it is
simply the other way round.

outbound SOAP Request X inbound


Web Services Web Services
Consumer Provider
inbound SOAP Response Y outbound

Figure 13 Denotation of inbound/outbound processing in NetWeaver

1.4. WS-Security in IBM WebSphere Application Server 6


WebSphere Application Server 6.0 is based on the implementation of WS-Security 1.0 in the
OASIS specification and profiles as defined in [1], [2] and [3]. In addition, some extension
functions are provided, like identity assertion and pluggable token architecture [4].
WebSphere follows a configuration approach for providing WS-Security. Similar to NetWeaver,
WS-Security functionality is specified in descriptor files. These specifications drive configuration
of security handlers during deployment, which ultimately provide the respective runtime its
functionality.
Different levels of WS-security configurations are supported (Figure 14). Extensions to server or
client deployment descriptor files specify which level of WS-Security (what in Figure 14) should
be applied to the respective Web Service or Web Service proxy. The technical details -- the how
in Figure 14 -- are specified within binding configurations.
Thus, akin to NetWeaver, WebSphere reflects different roles within its WS-Security
configurations, e.g. application developer or security administrator.

August 2006 10
Web Services Security Cookbook

IBM Rational Application Developer

Web Service A (Web Services Provider)


webservices.xml

Server Deployment Descriptor Extensions

Server Binding Configurations

Configure WS-Security
(what) Proxy B (Web Services Consumer)
web.xml
Configure WS-Security
Client Deployment Descriptor Extensions
(how)
Client Binding Configurations

Figure 14 Configuring WS-Security in IBM WebSphere

Within each descriptor or configuration file, the specification of WS-Security is split into two
portions (Figure 15).
• A Request Generator portion specifies the WS-Security that is to be applied to a SOAP
request by a Web Services Consumer.
• A Response Consumer portion defines the WS-Security constraints a Web Services
Consumer expects to be met by a SOAP response, e.g. the SOAP response should be
signed.
• A Request Consumer portion defines the WS-Security constraints a Web Service
Provider expects to be met by a SOAP request.
• A Response Generator portion specifies the WS-Security that is to be applied to a
SOAP response by a Web Services Provider.

Web Services Consumer Web Services Provider

Request Generator SOAP Request X Request Consumer

Response Consumer SOAP Response Y Response Generator

Client Deployment Descriptor Extensions Server Deployment Descriptor Extensions

Client Binding Configurations Server Binding Configurations

Figure 15 Portions of WS-Security configurations

The actual configurations of these scenarios are described in the next chapters. First, the
generation and management of the respective key stores are introduced. Subsequently, the
configuration of the scenarios in the respective development environments is described. As has
been mentioned before, these configurations are based on work that is described in [5].

2. Key Management
This chapter describes the key management for the WS-Security scenarios, consisting of the
generation of key pairs for signing SOAP messages as well as for encrypting username tokens.
In addition, it shows how to exchange the public key from IBM to the SAP tools.
Figure 16 gives an overview of the steps and the tools involved. WebSphere key management
is handled using the tool "iKeyman" for creating a key database, for generating asymmetric key
pairs for signing and encryption, and for exporting a certificate.

August 2006 11
Web Services Security Cookbook

The key management for NetWeaver is conducted using the "Visual Administrator". Here, an
asymmetric key pair for signing is generated within the existing realm "Key Storage". In the
same way, the certificate for the encryption scenario is imported here.

iKeyman Visual
export import Administrator

create
WS-KeyDB Key Storage
create

NW-Signature
ws-signature
ws-encryption-
ws-encryption certificate

WebSphere NetWeaver

Figure 16 Key Management for WS-Security Scenarios

Note that for the sake of simplicity only self-signed certificates are used during the course of this
description.

2.1. Key Management for WebSphere


Perform the following steps on the node "myRad.ctsc.com" where WebSphere is installed2:
Start the key management tool iKeyman (typically found in "C:\Program
Files\IBM\Rational\SDP\6.0\runtimes\base_v6\bin"). Within this application, issue the
command "Key database File -> New" from the file menu (Figure 17).

Figure 17 Create a new key database

On the next screen, choose the name of the key database ("WS-KeyDB"), its location and
its database type ("JKS") (Figure 18). After pressing the "OK" button, assign a
password for the new database ("ws-keydb", in our case) within the pop-up window. As
a result, the new database is opened within "iKeyman".

Figure 18 Specify Key Database

Start creating a new self-signed certificate by issuing "Create -> New Self-Signed
Certificate" from the menu (Figure 19).

Figure 19 Create new Self-Signed Certificate

2
As a default action, it is assumed that every configuration is saved using the appropriate buttons.

August 2006 12
Web Services Security Cookbook

Specify the key-pair and certificate for signing SOAP messages as depicted in Figure 20.
Choose "ws-signature" as the internal key label and "CN=WS-Signer, O=IBM, C=DE"
as distinguished name, and press the "OK" button.

Figure 20 Specify Self-Signed Certificate for signing

In the same way, repeat the creation of a key-pair and self-signed certificate for encryption
with the details as shown in Figure 21.

Figure 21 Specify Self-Signed Certificate for encryption

Start exporting the encryption certificate by selecting "ws-encryption" in the "Personal


Certificates" pane within "iKeyman", and press the "Extract Certificate" button (Figure
22).

Figure 22 Extract Certificate of ws-encryption

On the next screen, select the Data type "Base64", and the location of the file in which to
extract the certificate, and press the "OK" button.

August 2006 13
Web Services Security Cookbook

Figure 23 Select format and location for extracted certificate

2.2. Key Management for NetWeaver


Perform the following steps on the node "nw2004.ctsc.com" where NetWeaver is installed.
1. Start the Visual Administrator, expand "<SID> -> Server... -> Services" in the left pane,
and open the "Key Storage" entry (Figure 24). In the right pane, select the
"WebServiceSecurity" view and press the "Create" button for opening the key
generation dialog window.

Figure 24 Open Key Storage

2. Specify the key-pair and self-signed certificate as shown in Figure 25. The key pair is
labeled "NW-Signature"; as the distinguished name of the certificate the value
"CN=NW-Signer, O=SAP, C=DE" is chosen. Press the "Generate" button.

August 2006 14
Web Services Security Cookbook

Figure 25 Key and Certificate Generation

3. As a result, two entries are created within the Key Storage. "NW-Signature" denotes the
private key of the generated key pair, whereas "NW-Signature-cert" denotes the self-
signed certificate with the public key of the generated key pair (Figure 26).

Figure 26 Entries for NW-Signature

4. As a final step, import the self-signed certificate within the file "ws-encryption.arm". A
prerequisite of this step is that this file has been made available on the NetWeaver
node. Press the "Load" button" which you find on the same pane, select the exported
file from its file location and press the "OK" button (Figure 27).

August 2006 15
Web Services Security Cookbook

Figure 27 Import the ws-encryption certificate.

3. Integrity Scenario
This chapter describes the detailed configuration steps for the integrity scenario as depicted in
Figure 9. First the configurations for NetWeaver are introduced. After that, all the WebSphere
configurations are described. Finally, it is shown how to test the configured scenario. As a
general prerequisite, perform the key management steps of chapter 2 beforehand.

3.1. NetWeaver as a Secure Web Services Provider


This chapter assumes that the configuration steps described in chapter 8.1 of [5] have been
completed. As a result, SAP IDE contains
• an EJB Project "SmallStockQuoteEJB" with an EJB "StockQuote" and a derived Web
Service "WS_ExampleStockQuote".
• an Enterprise Application Project "SmallStockQuoteEAR" that comprises the
corresponding units of deployments.
In addition, it is assumed that the Web Service has been deployed on the SAP NetWeaver
WebAS J2EE Server. Given this configuration, conduct the following steps:
1. Open the project "SmallStockQuoteEJB" in the Web Services perspective of the SAP
IDE, navigate to the "Web Service Configurations" and open it within the "WS-
Deployment Descriptor Editor". Select the "Security" item and configure "Signature" for
"Request" as well as "Response" under the "Document Security" button (Figure 28).

August 2006 16
Web Services Security Cookbook

Figure 28 Configure WS-Security Signature in NetWeaver Developer Studio

2. Open the context menu of "SmallStockQuoteEJB" and press "Build EJB Archiv" to build
up the jar archive (Figure 29).

Figure 29 Build EJB Archive

3. Open the context menu of "SmallStockQuoteEAR" and select "Build Application


Archive" to generate the unit of deployment (Figure 30).

Figure 30 Build Application Archive

4. Open the context menu of SmallStockQuoteEAR and press "Deploy to J2EE Server"
(Figure 31). This completes the configuration of this scenario within the SAP IDE.

August 2006 17
Web Services Security Cookbook

Figure 31 Deploy the Web Service

5. Start the "Visual Administrator", open the "Web Services Security" folder and press the
"Profile Administration Tab" (Figure 32). Select "Inbound Messages" and ensure that a
profile "default_Signature" is configured.

Figure 32 Profile Administration within Visual Administrator

6. On the same screen, select "Outbound Messages". Press the "New" button and define
a new profile "IBMSAP-Signature-Outbound" as shown in Figure 33. The template
"Signature" defines typical configuration options for signing SOAP messages, e.g. how
to exchange information about the certificate which is used for signing. The
"Configuration" options specify the signing key "NW-Signature" and its key storage. For
interoperability reasons, it is recommended to select “WS Security SAP NW 04 Stack
12” for the WS Security Version.

August 2006 18
Web Services Security Cookbook

Figure 33 Define new Profile for Outbound Messages

7. At the bottom of the same screen, press the "Security Administration". Select the
deployed Web Service "WS_ExampleStockQuote" in the left pane and associate it with
the "default_Signature" profile for inbound and the "IBMSAP-Signature-Outbound"
profile for outbound processing (Figure 34). Since the Web Services Consumer in
WebSphere will be configured to contain its signing certificate within the SOAP request
(Figure 42), no special requirements need to be configured for the inbound processing.
The outbound profile describes the key for signing the SOAP response message.

Figure 34 Associate profiles with deployed Web Service

August 2006 19
Web Services Security Cookbook

3.2. WebSphere as a Secure Web Services Consumer


Before starting the configuration steps of this chapter, ensure to have completed chapter 8.1.3
of [5]. As a result, IBM RAD contains a dynamic Web Project "WSClient" with a container
managed Web Services proxy to the Web Service "WS_ExampleStockQuote" provided by
NetWeaver. The following description shows how to add the signing of SOAP messages to the
proxy. Thereby, the description distinguishes between the configuration of the "Request
Generator" and "Response Consumer" part.

3.2.1 Configure the Request Generator


1. Select the Project "WSClient" in the J2EE perspective. Navigate to the web deployment
descriptor "web.xml" and open it (Figure 35).

Figure 35 Open Web Service Client Deployment Descriptor

2. As described in chapter 1.4, configuring WS-Security comprises a functional (what) and


a technical (how) part. The functional part is configured within extensions to the
deployment descriptor. Therefore, select the "WS-Extension" tab (Figure 35) and open
the "Request Generator Configuration" section. Likewise, open the "Integrity" section
and press the "Add" button (Figure 36).

Figure 36 Open Integrity Dialog

3. Within the "Integrity Dialog" screen, choose a name "sig_body" for the specification, and
select the Message parts to which a signature should be applied, using the "Add" button
(Figure 37). In this case, the specification requires the data part of a SOAP message
and an additional timestamp to be signed.

August 2006 20
Web Services Security Cookbook

Figure 37 Specify message parts of the request on which to apply integrity

4. For adding a timestamp to the SOAP request, expand the "Add Timestamp" section and
select the "Use Add Timestamp" box (Figure 38).

Figure 38 Add a timestamp to the SOAP message

5. For specifying the technical details of the signature scenario, switch to the "WS-Binding"
tab and expand the "Security Request Generator Binding Configuration" section (Figure
39). Since a detailed description of all the configuration options is beyond the scope of
this paper, only those options are introduced that are necessary for this scenario.

Figure 39 Open WS-Bindings for specifying technical details of signature scenario

6. Start the technical configuration by configuring a generator for an X.509 token that is
used for signing the SOAP request. Expand the "Token Generator" section (Figure 39)
and click the "Add" button. Within the Token Generator dialog (Figure 40), specify a
name for this definition ("tok_gen_request"), select the values for the fields "Token

August 2006 21
Web Services Security Cookbook

generator class", "Value Type" and "Call back handler" from the respective drop-down
menus as depicted in Figure 40, and specify the key database and the key to be used
("ws-signature", in our case). Save the configuration by clicking the "OK" button.

Figure 40 Configure a Token Generator

7. Open the "Key Locator" section in the Bindings Configuration (Figure 39) and click the
"Add" button. Within the "Key Locator dialog" (Figure 41), configure how the keys are
retrieved for signing the message3. Give a name to this configuration
("key_loc_request"), select the value for the field "Key locator class" from the respective
drop-down menu (Figure 41) and specify the key database and the key to be used
("ws-signature", in our case). Save the configuration by clicking the "OK" button.

Figure 41 Configure Key Locator for the request message

8. Open the "Key Information" section in the Bindings Configuration (Figure 39) and click
the "Add" button. Within the "Key Information dialog" (Figure 42), specify how the
information about the signing certificate is to be included into a SOAP message (Figure

3
Even though similar information has been given within the Token Generator dialog, we found that the key locator is
nevertheless necessary.

August 2006 22
Web Services Security Cookbook

5). In the scenario described here, the key information part of a SOAP message
contains a reference to a security token which is also part of the SOAP message.
Therefore, select "STRREF" as key information type, select "Use token" and choose the
name of the security token that has been defined before. In addition, reference the key
locator as defined in Figure 41, and give this key information definition a name
("key_info_request"). Press the "OK" button to save this configuration.

Figure 42 Configure Key Information for the request message

9. Open the "Signing Information" section in the Bindings Configuration (Figure 39) and
click the "Add" button. In the "Signing Information dialog" Figure 43, specify the
"Signing information" part of a SOAP message (Figure 5).
For the fields for the canonicalization and the signature method leave the default
values. Then set the key information element to the defined element in Figure 42 and
choose an arbitrary name for the field "Key information name". Press the "OK" button to
save the configuration.

Figure 43 Configure Signing Information for the request message

10. As shown in Figure 5, the signature of a SOAP message can be built from the digest of
a SOAP body and a timestamp. However, there are other options available, like also
including the digest of a certificate or only a certain part of the body. In order to support
this kind of flexibility, there exists a sub-dialog as part of the signing information, where
all those parts whose digest comprise a signature can be configured individually.
Thus, select the defined signing information "sign_info_request" and expand the "Part
References" section as shown in Figure 44 and click the "Add" button.

August 2006 23
Web Services Security Cookbook

Figure 44 Part References and Transforms Sub-dialog for the request message

11. Within the "Part Reference dialog" choose a name ("part_ref_request") and select the
integrity part as defined in the extensions (Figure 37). Leave the default value for the
digest method and client the "OK" button to save the configuration.

Figure 45 Configure Part Reference for the request message

12. Likewise, expand the "Transforms" section (Figure 44) and click the "Add" button. The
"Transform dialog" appears for specifying the transformation method that is to be
applied to the related part of a SOAP message before its digest is built. For configuring
this scenario, just choose a name ("transform"), leave all the other values as given and
press the "OK" button. This step finalizes the configuration of the Request Generator
part.

Figure 46 Configure Transform for the request message

3.2.2 Configure the Response Consumer


This subsection describes how a signed SOAP response is handled within its receiver. Thus, it
describes the expectations a receiver has on the SOAP message which drives the actual
checking of the message.

August 2006 24
Web Services Security Cookbook

Although the configuration of the extensions to the deployment descriptor (what) is similar to the
request generator, there are some additional topics to be found within the configuration
bindings.
1. Within the editor of the file "web.xml" click on the "WS-Extension" button (Figure 35)
and open Response Consumer Configuration section (Figure 47).

Figure 47 Response Consumer Configuration

2. Open the "Required Integrity" section and click the "Add" button. Within the "Required
Integrity dialog", choose a name for this configuration ("sig_body_response") and define
the body and timestamp as parts of a response message expected to be signed (Figure
48).

Figure 48 Specify message parts of the response on which to apply integrity

3. Likewise, specify that a timestamp is expected to be contained within the SOAP


response (Figure 49).

Figure 49 Configure expected timestamp

4. For specifying the technical details of handling the response message, switch to the
"WS-Binding" tab and open the "Security Response Consumer Binding Configuration"
section.

August 2006 25
Web Services Security Cookbook

Figure 50 Security Response Consumer Binding Configuration

5. Open the "Token Consumer" section, click the "Add" button. In the "Token Consumer
dialog" (Figure 51), specify how to extract and check the certificate that will be part of
the response message. Give a name to this configuration ("tok_cons_response") and
select the value for the "Token consumer class" from the respective drop down menu.
Specify to expect an X509 v3 token by checking the box "Use value type" and selecting
the depicted "Value type". Fill "system.wssecurity.X509BST" as a value for the field
"jaas.config.name". Finally, check the field "Trust any certificate" on the bottom of the
pane.

August 2006 26
Web Services Security Cookbook

Figure 51 Token Consumer configuration

6. Open the "Key Locators" section (Figure 50) and press the "Add" button. Within the
"Key Locator dialog" select the "Key locator class" from the drop-down menu as shown
in Figure 52 to locate the key from the X509 certificate contained within the message.
Give a name to this definition ("key_loc_response") and press the "OK" button.

Figure 52 Key Locator for the response message

August 2006 27
Web Services Security Cookbook

7. Open the "Key Information" section (Figure 50) and press the "Add" button. Fill in the
configuration within the "Key Information dialog" as depicted in Figure 53. Note that the
configuration is similar to the one for the request message as shown in Figure 42,
except that the defined entities for response handling are referenced. In particular, no
key name is required as the key is taken from the response message. Press the "OK"
button to save the configuration.

Figure 53 Key Information configuration for the response

8. Open the "Signing Information" section (Figure 50) and press the "Add" button. Within
the "Signing Information Dialog" (Figure 54) give a name for this specification
("sign_info_response") and leave the defaults for the canonicalization and signature
method. Add a new row within the "Signing key information", select
"key_info_response" as a value for the column "key information element" using the
drop-down menu and choose a name for the column "key information name". Press the
"OK" button to save the configuration.

Figure 54 Signing Information for response message

9. Similar to the steps described on page 23, select "sign_info_response", expand the
"Part References" section, press the "Add" button and define the part reference as
shown in Figure 55. Press the "OK" button to save the configuration.

Figure 55 Part Reference for response message

August 2006 28
Web Services Security Cookbook

10. Expand the "Transforms" section (Figure 44), press the "add" button and specify a
transformation within the "Transform dialog" by just giving a name and leaving all the
defaults before saving the configuration (Figure 56).

Figure 56 Transform for response message

11. Before testing the configuration, ensure that the project "WSClient" with the changed
configuration has been deployed and started on the running WebSphere Application
Server. Usually, deployment happens dynamically on-the-fly after you have saved a
changed project. However, for immediate testing, there exists a reloading interval that
leads to a certain delay of the reloading of changed configurations. For testing
purposes, just to ensure that the corresponding "WSClientEAR" project is added to the
server, right-click on the running server in the Server perspective and select "Add and
remove projects ..." (Figure 57).

Figure 57 Add project to the server

12. Then add the EAR project "WSClientEAR" to the list of deployed projects. If it had not
been added there before, select it on the list of available projects and press the "Add"
button. Note that adding a new project restarts it automatically. If, however, the project
was already on the list, then you might have to restart the project manually.

Figure 58 Add EAR-Project to Server

3.3. Testing the Configuration


Given that the projects for the Web Services consumer and provider are deployed and running
on their respective servers, test the configuration as depicted in Figure 59. In this configuration,
a local TCP/IP monitor is added in "front of" the WebSphere Application Server for checking and
displaying exchanged messages.

August 2006 29
Web Services Security Cookbook

TestClient.JSP WS_ExampleStockQuote
WS_ExampleStockQuoteVi_DocumentProxy TCP/IP Monitor
SAP J2EE Application Server 04s, SP07
IBM WebSphere Application Server, V 6.0.2

myRad.ctsc.com nw2004s.ctsc.com

Figure 59 Testing the Configuration

Prepare the TCP/IP monitor by performing the following steps.


13. From the menu within RAD, open "Window -> Preferences"
14. Within the "Preferences" window, navigate to "Internet -> TCP/IP Monitor" (Figure 60),
Click on the "Add" button in the right pane and define the TCP/IP Monitor as depicted in
Figure 60. This defined monitor acts as a proxy and forwards any request which it
receives on port 50100 to the remote host "nw2004s" on port 50100. Press the "OK"
button to save the configuration and the "Start" button subsequently.

Figure 60 Define TCP/IP Monitor

15. Within RAD, navigate to the automatically generated "TestClient.jsp" within the
"WSClient" project and select "Run -> Run on Server" from its context menu (Figure
61).

August 2006 30
Web Services Security Cookbook

Figure 61 Run TestClient.jsp on the server

16. The JSP is displayed within the integrated Web Browser (Figure 62). Before actually
calling the Web Service, change the internal URL within the proxy to point to the TCP/IP
monitor. This is done by selecting the operation "setEndpoint", input the URL
http://localhost:50100/WS_ExampleStockQuote/Config1?style=document and press the
"invoke" button. Figure 62 shows the result of this operation.

Figure 62 Change endpoint to be called by the proxy.

17. Finally, select the actual web service call "getQuote", input either "IBM" or "SAP", and
press the "invoke" button (Figure 63). The result of the call should be displayed within
the "Result" pane. In addition, check the signed messages that are exchanged between
the proxy and the Web Service within the TCP/IP monitor (Figure 63).

August 2006 31
Web Services Security Cookbook

Figure 63 Call the proxy

4. Authentication Scenario
This section describes how to configure message level-based authentication as defined by WS-
Security (Figure 6). In this configuration, the SOAP request message is extended by a
username security token containing username and password.
Since the password is transmitted in clear text, this kind of configuration should either be used
in conjunction with transport level-based SSL-encryption or employed with WS-Security-based
encryption. The latter will be described in more detail in chapter 5. So consider this chapter also
as an introduction to chapter 5.
Within the scenario to be described, WebSphere is acting as a Web Services Provider whereas
NetWeaver plays the Web Services Consumer role (Figure 10). Similar to the previous chapter,
it is assumed that the configuration steps of chapter 8.2 in [5] have been performed in the
respective development environments.
A prerequisite for WebSphere to act as a secure provider is to enable security on the
WebSphere Application Server which is described first. After that, the extension of the Web
Service "SmallStockQuote" by authentication is described, followed by a description of the Web
Services Consumer part in NetWeaver.

4.1. Enabling Security on WebSphere Application Server


Enabling security on WebSphere Application Server facilitates automatic authentication of
incoming SOAP requests against the user registry which is provided by the operating system on
which the server is running. The actual configuration is done with the server, which is integrated
into RAD.
1. Within RAD, open the configuration of the integrated server by double-clicking on its
entry within the Servers view (Figure 64).

August 2006 32
Web Services Security Cookbook

Figure 64 Entry of the test server in the Servers view

2. Within the server configuration, check that security is enabled and specify User ID and
password of a user that has been configured on the node "myRad.ctsc.com" with
appropriate rights (Figure 65). Save the configuration.

Figure 65 Enable security on the test server

3. Start the Administrative Console of the test server from the context menu of its entry
within the Servers view (Figure 66).

Figure 66 Start Administrative Console

4. When the console comes up provide an arbitrary User ID (at this time it is not checked
yet).
5. Within the Administrative Console, expand Security in the left pane, and click on Global
security (Figure 67). Then click on "Local OS" in the right pane.

Figure 67 Select Global Security and Local OS in the Administrative Console

August 2006 33
Web Services Security Cookbook

6. Input user ID and password and press "Apply" (Figure 68).

Figure 68 Specify Local OS user

7. Again on the configuration window, enable global security by selecting the appropriate
check box, select "Local OS" as the active user registry (Figure 69) and click twice to
save the configuration.

Figure 69 Enable Global Security

8. Restart the server.

4.2. WebSphere as a Web Services Provider for Authentication


This section assumes that RAD is opened in a workspace, which contains a Dynamic Web
Project "SmallStockQuote" with a "Stockquote" Web Service as defined in chapter 8.2 of [5].
Perform the following steps to extend the project by username token-based authentication.
1. Select the project "SmallStockQuote" in the J2EE Perspective, expand the folder
"SmallStockQuote -> WebContent ->Web-IBF" and open "webservices.xml" in the Web

August 2006 34
Web Services Security Cookbook

Services Editor (Figure 70). Click on the "Extensions" tab for defining that this provider
expects a username token as a functional extension of a SOAP request.

Figure 70 Open Web Services deployment descriptor

2. Expand "Request Consumer Service Configuration details" as well as "Required


Security Token" section and press the "Add" button. In the "Required Security Token
Dialog" (Figure 71), denominate the token ("use_token") and select "Username" as a
token type from the drop-down menu. Select "Required" as a "Usage type" to define
the username token as being mandatory. Press the "OK" button to save the
configuration.

Figure 71 Add Required Security Token

3. For defining the technical details, switch on the "Bindings" tab in the Web Services
Editor (Figure 70). Open the "Request Consumer Binding Configurations Details" and
the "Token Consumer" section and press the "Add" button. Define a Token Consumer
as depicted in Figure 72. Then add the token consumer name ("tok_cons"), select the
"Security Token" that was specified before, choose "Username Token" as a Value Type
and specify "system.wessecurity.UsernameToken" as "jaas.config" property. Press the
"OK" button to save the configuration.

August 2006 35
Web Services Security Cookbook

Figure 72 Add Token Consumer

4. Ensure that the project is deployed on the integrated application server as described on
page 29.

4.3. NetWeaver as a Web Services Consumer with Authentication


WS-Security can only be applied to container-managed entities. This means that a deployable
proxy has to be configured as Web Services Consumer in NetWeaver. The description starts
from scratch since chapter 8.2 in [5] introduces the configuration of standalone proxy only.

1. Open NetWeaver Developer Studio in "Web Services Prespective", select "Client


Explorer". From the File Menu, choose "File -> New -> Other ...", then select Web
Services --> Deployable Proxy Project" (Figure 73).

Figure 73 Create Deployable Proxy Project

2. Choose "SmallStockQuoteDeployProxyProject" as the project name (Figure 74).

Figure 74 Choose Project name

3. Select the created project and choose "New -> Client Proxy Definition" from its context
menu (Figure 75).

August 2006 36
Web Services Security Cookbook

Figure 75 Create Client Proxy Definition

4. Define the package and name for the deployable proxy and select the WSDL source as
depicted in Figure 76.

Figure 76 Define the deployable proxy

5. Browse to the shared file location that contains the WSDL of the Web Service provided
by WebSphere (see [5], chapter 8.2), and press "Next" and "Finish" (Figure 77). As a
result, a deployable proxy is created.

Figure 77 Select the WSDL

6. The generation of a username token is configured in the "Logical Ports" description of


the deployable proxy project. Open the logical port "Stockquote" as depicted in Figure
78, press the "Security" button, select "Document Authentication" as a value for the
"Authentication" field, select the "Basic" radio button and specify "Username" for the
"Request". Save the configuration.

Figure 78 Configure generation of UsernameToken in the logical port

7. Select "Build EAR" from the context menu of "SmallStockQuoteDeployProxyProject"


(Figure 79).

August 2006 37
Web Services Security Cookbook

Figure 79 Build EAR file

8. Navigate to the created EAR-file within the project and select "Deploy" from its context
menu (Figure 80). This finishes the configuration of the username token within the IDE.

Figure 80 Deploy the EAR of the deployable proxy project

9. The technical details for generating a username token are configured within the Visual
Administrator. Within the Visual Administrator, expand "Services" under your server
entry and scroll to "Web Services Security" in the left pane (Figure 81). Select "Profile
Administration" on the bottom of the window and "Outbound Messages" on the upper
left corner. Press the "New" button and define a new profile "SAPIBMUserToken", that
is derived from the template "Username". Define username and password as the
values for the username token4. Press the "Save" button.

4
Note that for successful testing the username/password pair must be defined within the local user registry on the
WebSphere node "myRAD.ctsc.com".

August 2006 38
Web Services Security Cookbook

Figure 81 Define Profile for Username Token in Visual Administrator

10. Finally, select the "Security Administration" button, navigate to the defined proxy within
the Web Services pane, press the "Document Security" button in the right pane and
select the profile "SAPIBMUserToken" for Outbound communication (Figure 82). This
finishes the configuration of the username token within NetWeaver.

Figure 82 Associate profile with proxy

4.4. Testing the configuration


Since the deployed proxy cannot directly be called by a browser, an additional component
managed by the SAP NetWeaver WebAS J2EE server must be introduced for testing the
configured entities. Different options are available. In the configuration documented in this
section, a JSP will be introduced that actually calls the proxy (Figure 83). Even though it is not

August 2006 39
Web Services Security Cookbook

the focus of this document, the configuration description must include how to develop the JSP
for the sake of completeness.
On the WebSphere side, again, a TCP/IP monitor is used as a proxy in order to check the
messages exchanged.

StockQuoteJSP.jsp
SmallStockQuote
SmallStockQuoteDeployProxy TCP/IP Monitor
IBM WebSphere Application Server, V 6.0.2
SAP J2EE Application Server 04s, SP07

nw2004s.ctsc.com myRad.ctsc.com

Figure 83 Testing the configuration

1. With NetWeaver Developer Studio, start creating a Web Module Project for the JSP by
issuing "File -> New Web Module Project" from the menu within the J2EE perspective
(Figure 84). Name the project "SmallStockQuoteJSPWeb" and press the "Finish"
button.

Figure 84 Create project for JSP

.
2. Select "Add Web Service Client API Library" from the context menu of the new project
(Figure 85).

Figure 85 Add Web Services Client API

3. Select the project of the deployable proxy and press the "OK" button (Figure 86).

Figure 86 Select the client api of the deployable proxy

4. Start creating the JSP by issuing "New -> JSP" from the context menu of the deployable
proxy project (Figure 87). Name the project "StockQuoteJSP" and press the "Finish"
button. The source of the new JSP is documented in Appendix 7.1

Figure 87 Create a JSP

5. Within the project "SmallStockQuoteJSPWeb" open the file "web-j2ee-engine.xml",


select the "References" tab and define the jndi mapping "Stockquote" as shown in
Figure 88. In particular, ensure that you assign the depicted value to the field "Server
component JNDI name". Save the configuration.

August 2006 40
Web Services Security Cookbook

6.
Figure 88 Define the JNDI Mapping

7. Select "Build WEB Archive" from the context menu of the project (Figure 89).

Figure 89 Build the WEB Archive

8. Create the corresponding EAR project by issuing "File -> New -> Enterprise Application
Project" from the file menu (Figure 90).

Figure 90 Create the Enterprise Application Project

9. Choose "SmallStockQuoteJSPWebEAR" as a name for the EAR project , press the


"Next" button and add the JSP project to the EAR project (Figure 91).

Figure 91 Add the JSP project to the EAR project

10. Within the EAR project, open "application-j2EE-engine.xml", click on the "General" tab,
select "References" and click the "Add" button. Define a reference to the proxy project
as depicted in Figure 92.

August 2006 41
Web Services Security Cookbook

Figure 92 Create a Reference to the deployable Proxy

11. Within the EAR project, open "application.xml", select the "Modules" tab and ensure
that you see the definition in Figure 93.

Figure 93 Application descriptor of EAR project

12. Build the application archive (Figure 94) by selecting it in the context menu of the EAR
file.

Figure 94 Build Application Archive

13. Finally, select the generated EAR file "SmallStockQuoteJSPWebEAR.ear" and issue
"Deploy to J2EE server" from its context menu.

August 2006 42
Web Services Security Cookbook

Figure 95 Deploy the EAR project

14. After successful deployment, start testing by calling the JSP within a browser. If you
open the browser on the node "nw2004s.ctsc.com", you may use the URL depicted in
Figure 96.

Figure 96 Call the Test-JSP

15. Before issuing the "getQuote" operation, ensure that TCP/IP monitor is configured on
the WebSphere side as shown in Figure 97.

Figure 97 Define the TCP/IP Monitor

16. Also within RAD, on the WebSphere side, check the exchanged messages within the
TCP/IP monitor view (Figure 98).

August 2006 43
Web Services Security Cookbook

Figure 98 Check the TPC/IP Monitor

5. Encryption Scenario
The final scenario to be described is the encryption of the username token (Figure 11).
Although this seems to be a limitation from a standards point of view, the configuration
techniques within the development environments are the same regardless of which part of a
SOAP message is encrypted.
This scenario is presented as an extension of the previous one described in chapter 4. Thus,
ensure that you have configured the authentication scenario before you start with performing
the steps within this chapter.

5.1. WebSphere as Web Services Provider with Encryption


Before you start with the configuration below, ensure that you have performed the steps
described in chapter 4.2.
1. Within RAD, select the project "SmallStockQuote" in the J2EE perspective and open
the file "webservices.xml" in the Web Services editor (Figure 70). Select the
"Extensions" tab, and open the "Request Consumer Service Configuration Details" and
"Required Confidentiality" section, subsequently. Press the "Add" button. Within the
"Required Confidentiality dialog" add the configuration of which parts of a SOAP
request should be encrypted (Figure 99). Specify a name "req_confid" for this part of
the specification, select "Required" as Usage type, and choose "usernametoken" as the
Message parts keyword. Press the "OK" button to save the configuration.

August 2006 44
Web Services Security Cookbook

Figure 99 Required Confidentiality

2. Switch to the "Bindings Configurations" tab within the Web Services editor (Figure 70)
for specifying the technical details of how the encrypted part of the SOAP message is
built (Figure 7).
Open the "Request Consumer Binding ConfigurationDetails" and the "Key Locators"
section, subsequently, and press the "Add" button. Within the "Key Locator dialog"
configure how the private key, which will be used for decrypting the session key, is
retrieved from the local key store (Figure 100). Choose a name for this configuration
("key_loc"), select the key locator class from the respective drop-down menu and
specify the key database as well the key to be used ("ws-encryption", in our case).
Press the "OK" button to save the configuration.

Figure 100 Add a Key Locator

3. Open the "Key Information" section in the Bindings Configuration and press the "Add"
button. Within the "Key Information dialog" (Figure 101) specify how the receiver
extracts the information about the private from the request message. Specify a key
information name ("key_info") and select "KEYID" as key information type. In addition,
associate the key information with the key locator defined in the step before. Press the
"OK" button to save the configuration.

August 2006 45
Web Services Security Cookbook

Figure 101 Add Key Information

4. Open the "Encryption Information" section and press the "Add" button. Within the
"Encryption Information dialog" (Figure 102), describe how to encrypt the confidentiality
part that has been configured in Figure 102. Give a name to the configuration
("enc_name"), leave the defaults for the data and key encryption method and reference
the key information configured in the previous step. Press the "OK" button to save the
configuration.

Figure 102 Encryption information

5. Ensure that the project is deployed on the integrated application server as described on
page 29.

5.2. NetWeaver as a Web Services Consumer with Encryption


Perform the configuration documented in chapter 4.3 before starting to execute the following
steps.

1. Go back to the NetWeaver Developer Studio, open the project


"SmallStockQuoteDeployProxyProject" in the Client Explorer of the Web Services

August 2006 46
Web Services Security Cookbook

perspective. Open the logical port "Stockquote", select the "Security" tab and configure
"Encryption+Username" for Document Security (Figure 103). Save the configuration.

Figure 103 Configure encrypted Username token in the IDE

2. Build the EAR file Figure 79 and deploy it (Figure 80).


3. Start the Visual Administrator, open the "Web Services Security" entry (Figure 81) and
switch on the "Profile Administration" tab. Select "Outbound Message", press the
"New" button and define the profile "SAPIBMUserTokenEncrypted" for encrypting
Username tokens as shown in Figure 104. Thereby, specify the contents of the
Username token (see also Figure 81) as well as the key that is used for encrypting the
dynamically generated symmetric encryption key which is used to protect the token.
Note that this key has been imported as described in Figure 27. Do not forget to save
the configuration.

Figure 104 Define profile for username encryption

4. Associate the new profile with the deployed proxy by selecting the "Secure
Administration" tab, navigate to the deployed proxy, press the "Document Security" tab
and choose the respective profile for outbound processing (Figure 105).

August 2006 47
Web Services Security Cookbook

Figure 105 Associate Profile with the proxy

5. For testing this scenario, the configuration from chapter 4.4 can be reused. Therefore,
just call the JSP as shown in Figure 96.
6. Within the TCP/IP monitor on the WebSphere side, check that the SOAP request
message contains an encrypted username token.

Figure 106 Encrypted Username Token in TCP/IP Monitor

August 2006 48
Web Services Security Cookbook

6. Conclusion
WS-Security provides a flexible and extensible framework to support a variety of security
scenarios. However, flexibility and extensibility can also add significant complexity to the
development process. From a platform vendor’s perspective, the challenge is to shield this
complexity from the developers and let them concentrate on their business requirements.

While other vendors provide support for WS-Security through APIs, IBM’s and SAP’s
implementation strike the balance between flexibility and ease of use by addressing the most
common usage scenarios based on a deployment programming model. All security
requirements are expressed in XML deployment descriptors which are configured by a rich set
of design-time tools in the respective development environments.
Based on these scenarios, this cookbook provided guidance and recommendations for
achieving interoperability between secured Web Services using IBM WebSphere and SAP
NetWeaver. Overall, the results attest how well both platforms implement the WS-Security
standard.
In addition, IBM and SAP are active members in the Web Services Interoperability (WS-I,
www.ws-i.org) community which is chartered to deliver best practices and resources for
developing interoperable Web Services solutions. An important deliverable of this open industry
organization is the Basic Security Profile (BSP) 1.0 [6], which focuses on improving
interoperability between WS-Security implementations by strengthening requirements when
possible and reducing some of the flexibility by consolidating multiple options in the OASIS
specifications [1][2][3] to, ideally, just one. As part of their work in WS-I, IBM and SAP
published a new version of the WS-I Sample Application, which demonstrates interoperability in
action, based on the application of the BSP. Both implementations can serve as working
examples for developers looking to follow the WS-I guidelines. Both examples can be
downloaded from the WS-I web site [7].

August 2006 49
Web Services Security Cookbook

7. Appendix
7.1. StockQuoteJSP.jsp
<%@ page language="java" %>
<%@ page import="javax.naming.InitialContext" %>
<%@ page import="javax.rmi.PortableRemoteObject" %>
<%@ page import="com.examples.StockquoteService" %>
<%@ page import="com.examples.Stockquote" %>
<html>
<head>
<title>
Test deployed proxy
</title>
</head>
<FORM
METHOD="post"
ACTION="StockQuoteJSP.jsp">
<P>
Company name:
</P>
<P>
<INPUT
NAME="company"
size=10>
</P>
<P>
<INPUT
TYPE="SUBMIT"
NAME="Submit"
VALUE="getQuote">
</P>
</FORM>
<P>
<HR
HEIGHT="1px"
WIDTH="80%"
COLOR="#000000">
</P>
<body>
<%
try {
InitialContext ctx = new InitialContext();
StockquoteService obj =
(StockquoteService) ctx.lookup("java:comp/env/Stockquote");
Stockquote port =
(Stockquote) obj.getLogicalPort(Stockquote.class);
%>
<P>
<B><%="Result is " + port.getQuote(request.getParameter("company"))%>
</B>
</P>
<%
} catch (Exception ex) {
%>
<%=ex.getMessage() %>
<%
}
%>
</body>
</html>

August 2006 50
Web Services Security Cookbook

About the Authors

Khirallah Birkler is an IT Architect for IBM Software Group Germany. He works for Business
Partner Technical Support in the Boeblingen lab. He joined IBM eight years ago and has about
seven years experience in the J2EE and software development area. He is an IBM WebSphere
Business Integration Expert and has deep SAP NetWeaver skills covering knowledge in SAP
Basis technologies as well as on various application modules. He holds a Bachelor of Science
degree in Information Technology Management from University of Cooperative Education
Stuttgart.

Reinhard Heite is an IT Specialist with IBM Germany. He has seventeen years of experience
working for IBM and his areas of expertise include distributed computing, IT security, and
designing and implementing e-business solutions. He holds a degree in Computer Science
from the University of Bonn and received a Ph.D. in Computer Science from the University of
Erlangen. Currently, he works for the IBM/SAP Collaboration Technology Support Center
(CTSC) in Walldorf on interoperability scenarios between IBM WebSphere and SAP
NetWeaver.

Martin Raepple is a Standards Architect with SAP's Industry Standards team, working in the
area of standardization and interoperability testing of new Web Services technologies, and
focusing on message security and identity management. Martin is a frequent speaker at
conferences and author of books and articles related to information security, integration
middleware and J2EE development.

August 2006 51