Skip to main content
    Country/region [select]      Terms of use
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks > Tivoli
Securing Web services using SSL and Tivoli Access Manager 4.1
e-mail it!
1. Web Service updates
2. WebSEAL configuration
3. Test and validate the WebSEAL configuration
4. Web service client development
5. Test the client
About the author
Rate this article
dW newsletters
dW Subscription
(CDs and downloads)

Level: Introductory

David Loupia (
I/T Specialist, IBM
1 June 2003

This article will assist integrators and developers programming Web Services using Apache AXIS that want to add authentication and authorization using Tivoli Access Manager. In this article, you will reuse an existing sample SOAP/HTTP web service provided by the IBM WebSphere SDK for Web Services, and then you will configure Tivoli Access Manager WebSEAL to make authentication and authorization on your web service. Finally you will see how to develop a sample client passing the right parameters to access your secure web service.

This article assumes that you are familiar with the AXIS processing system. The software required for the examples is as follows:

  • IBM WebSphere SDK for Web Services (WSDK) v5.0
  • Tivoli Access Manager WebSEAL 4.1
This article assumes that the above software is installed and configured. (See Resources for the WSDK download information.)

Securing Web Services is one of the main challenges we have to face today in order to allow the use of web services in a production environment.

On one hand, the immediate security level you can provide on web services is securing the transport protocol used to transmit the SOAP requests and responses. If your Web Service is available through HTTP, SSL can be a good way to fulfill your security requirements. What SSL provides at the protocol level, is:

  • Identification: who are you?
  • Authentication: how do I know your identity is true?
  • Integrity: is the data you sent the same as the data I received?
  • Confidentiality: are we sure that nobody read the data you sent me?

But some security requirements are not covered by SSL, like:

  • Authorization: are you allowed to perform this transaction?
  • Auditing: record of all transactions so we can look for security problems after the fact
  • Non-repudiation: both sender and receiver can provide legal proof to a third party that the sender did send the transaction, and the receiver received the identical transaction

If you need Authorization, Auditing or Non-repudiation, SSL is not sufficient by itself. Auditing and Non-Repudiation can be provided by way of a logging mechanism in using the W3C XML Signature recommendation for non-repudiation. Several SOAP implementations like the Apache SOAP embedded in WebSphere Application Server 5.0 or AXIS support XML Signature.

On the other hand, you may have heard about WS-Security, a new specification dedicated to secure web services at the message level. WS-Security was originally endorsed by IBM, Microsoft and Verisign and is now hosted by the OASIS consortium. WS-Security addresses the same security requirements as SSL, including non-repudiation as well. Furthermore, WS-Security is an end-to-end solution and can be used across several intermediaries -- something which is not possible with an SSL point-to-point security solution.

However, authorization is still not provided, neither by SSL nor WS Security.

WebSEAL authorization level

Using WebSEAL, authorization is managed at the web service level, not at the method level

The purpose of this white-paper is to show that Tivoli Access Manager 4.1 can fill the gap and perform authentication and authorization for web services. WEBSEAL, a security reverse proxy provided by Tivoli Access Manager, is the enforcer chosen for authentication and authorization in the sample shown in this article.

In this article we will work on configuring WebSEAL to secure an existing web service.The sample web service to be secured is the Sample1 taken from the WSDK.

  • First, we change the WSDL file of the Sample1 web service to specify that our web service is accessible through SSL, and through the WebSEAL reverse proxy.
  • Secondly, we will configure WebSEAL to do authentication and authorization on the web service.
  • Lastly, we will write a sample client that uses Basic authentication to send its credentials to the server able to accept the WebSEAL server certificate.

When to use Basic Authentication

HTTP basic authentication is too weak to be trusted on a non-encrypted channel, but works over SSL.

As a prerequisite, we first need to fix a bug in the AXIS 1.0 framework that would prevent us from using the IBM JSSE implementation required to make some SSL calls. This is a known bug corrected in AXIS 1.1. To fix the problem, just download the file axis.jar from the Resources section, and replace the existing one in your <WSDK-install-dir>\appserver\lib directory.

The desired architecture topology at the end of this white-paper is the following:

Architecture topology
Architecture topology

1. Web Service updates
There's no change to make on the code of the Web Service itself. Authentication and authorization are not managed by the web service but by WebSEAL which is located in front of the Web Service.

Open a DOS command window and enter the following configuration command to ensure you are using the IBM JDK furnished in the WSDK.
C:\>set PATH=c:\<WSDK-install-dir>\appserver\java\jre\bin;c:\<WSDK-install-dir>\appserver\java\bin;%PATH%

Update the Sample1 WSDL file
The WSDL file of the Sample1 web service can be accessed dynamically or statically. In this article, we decide to use a static WSDL file to describe the Sample1 web service. Using a static file, we can authorize all users (even non-authenticated) to access the WSDL file, and we can restrict access to the web service implementation. The drawback of this approach is that we would have to regenerate the WSDL file each time the web service interface changes, for instance by providing a new method. In a real production system, this would not happen often: the interface wouldn't evolve that frequently. In contrast, the web service implementation may vary a lot without impacting clients.

Using a text editor, open the file Hello_SEI.wsdl in the <WSDK-install-dir>\appserver\installedApps\DefaultNode\Sample1WebService.ear\Sample1WebService.war\WEB-INF directory and change the value of the location attribute linked to the tag <wsdlsoap:address> to use https instead of http, your proxy hostname instead of localhost, and add the junction that we will create in WebSEAL.

WebSEAL SSL listenning port

You can find the WebSEAL listening port for SSL requests in the webseald.conf file , entry https-port

The updated line should look something like this:
<wsdlsoap:address location="https://proxyhost:8443/B2BGateway/SayHelloProject/services/Sample1"/>

assuming my proxy hostname where WebSEAL is installed is called proxyhost, WebSEAL is listening for https requests on port 8443, and /B2BGateway is the junction name we are going to use in WebSEAL.

Also copy the Hello_SEI.wsdl file to the directory <WSDK-install-dir>\appserver\installedApps\DefaultNode\Sample1WebService.ear\Sample1WebService.war to ensure that the WSDL file will be downloadable.

Now you can start the WSDK server using
Start -> Programs -> IBM WebSphere SDK for Web Services V5.0 -> Start Server

WSDK server start
WSDK server start

At this point, the Sample1 web service can be called internally on URL http://privatehost:6080/SayHelloProject/services/Sample1 and the WSDL file of the Sample1 web service can be downloaded from http://privatehost:6080/Sample1WebService/Hello_SEI.wsdl

Because the WSDL file links the web service implementation to an address accessible through the WebSEAL reverse proxy, we need now to configure WebSEAL to create the junction named B2BGateway to the private host running the Sample1 web service. We will restrict access to the Sample1 web service but the WSDL will still be downloadable freely without restriction.

2. WebSEAL configuration

Create a junction in WebSEAL
Ensure WebSEAL is started.

WebSEAL administrative tools

All the WebSEAL administrative tasks in this article are done using the pdadmin command-line tool. But you can also use the browser-based administrative interface (WPM) to perform all of these tasks.

Open an OS command window and launch the TAM pdadmin administrative console. Log on using your administrative username, sec_master most of the time.

pdadmin command-line tool
pdadmin command-line tool

We first need to create the junction to the private machine hosting the web service implementation using pdadmin. To do so, enter the following command on pdadmin:
pdadmin> server task webseald-proxyhost create -t tcp -h privatehost -p 6080 /B2BGateway
Message: junction created

assuming webselad-proxyhost is the WebSEAL server on my machine. If you don't know your WebSEAL server, just enter the command server list inside pdadmin. After the creation of the junction, you should receive a Message: junction created response in case of success.

Junction properties

In each junction we can also ask WebSEAL to pass some of the user's credentials to the backend HTTP server. Because the Sample1 web service implementation doesn't' care about that, this is not the case here.

The junction creation can be described as the following:

  • -t tcp option specifies the type of the junction. We use HTTP as the communication protocol between WebSEAL and the backend HTTP server.
  • -h privatehost -p 6080 specifies the backend HTTP server hostname and port we use to communicate
  • /B2BGateway is the junction name the clients have to use to connect to the backend HTTP server through WebSEAL

Load the Sample1 Web Service into the object space
Now we need to create the object space for the Sample1 web project:
pdadmin> objectspace create /WebSEAL/proxyhost/B2BGateway/Sample1WebService "WSDK Sample1 web service container" 14

Then we populate that object space with the object representing the Sample1 web service...
pdadmin> object create /WebSEAL/proxyhost/B2BGateway/Sample1WebService/services/Sample1 "WSDK Sample1 web service" 15

...and with the object representing the Sample1 web service WSDL file
pdadmin> object create /WebSEAL/proxyhost/B2BGateway/Sample1WebService/Hello_SEI.wsdl "WSDK Sample1 web service WSDL" 15

Create a user authorized to access the Sample1 web service
To be recognized by WebSEAL, each client of the Sample1 web service has to be an authenticated and authorized TAM user. As a result of a user registration, a username and password are generated that are used in the HTTP BASIC authentication header of each web service sample client.

Still using pdadmin, we can now create a user named igor:
pdadmin> user create igor cn=igor,secAuthority=Default igor igor passw0rd

Then, display the user's attributes with the command:
pdadmin> user show igor
Login ID: igor
LDAP DN: cn=igor,secAuthority=Default
LDAP CN: igor
LDAP SN: igor
Is SecUser: yes
Is GSO user: no
Account valid: no
Password valid: yes
Authorization mechanism: Default:LDAP

Notice that the Account valid attribute is set to no by default. We need to update it so that the user account can be used.
pdadmin> user modify igor account-valid yes

Create the ACLs associated with the Sample1 Web Service
In this section, we are going to create two ACLs: one to limit access to the Sample1 web service to authenticated and authorized users only, and one to authorize all users, even unauthenticated, to access the Sample1 WSDL file.

First, we create the restrictive ACL:
pdadmin> acl create Sample1_restrictedAccess
Now, we link it to the Sample1 web service:
pdadmin> acl attach /WebSEAL/proxyhost/B2BGateway/Sample1WebService/services/Sample1 Sample1_restrictredAccess
Finally, we authorize the user "igor" to access the Sample1 web service, by updating the restrictive ACL:
pdadmin> acl modify Sample1_restrictredAccess set user igor Tr

The ACL is filled using the permissions "Tr" to give authorized access to the Sample1 web service. The traverse permission ("T") is required for access to any object below this point. And the permission "r" is required for HTTP requests (GET or POST requests made by a SOAP client or an HTTP browser for instance)

In this sample the administrative user sec_master wouldn't be authorized to access the Sample1 web service because he wouldn't have the read (r) permission.

If we look at the list of the authorized users for the Sample1 web service, we can see that only igor is authorized.
pdadmin> acl show Sample1_restrictredAccess
    ACL Name: Sample1_restrictredAccess
    Description: Access restriction to the Sample1 web service to authenticated and authorized users only
        User sec_master TcmdbsvaBl
        User igor Tr

We have to repeat the above process with slight changes to create an ACL that will authorize all users (even non-authenticated) to access the interface of our web service, i.e. the WSDL file: Creation of the open ACL:
pdadmin> acl create Sample1_freeAccess
Link between the ACL and the Sample1 web service WSDL:
pdadmin> acl attach /WebSEAL/proxyhost/B2BGateway/Sample1WebService/Hello_SEI.wsdl Sample1_freeAccess 
Authorization to all authenticated to access the Sample1 web service WSDL:
pdadmin> acl modify Sample1_freeAccess set any-other Tr
To avoid any warning message, we can update the sec_master entry to add the "r" permission first.
pdadmin> acl modify Sample1_freeAccess set user sec_master TcmdbsvaBrl
Now that anybody (authenticated) can get access, we can add the unauthenticated entry. This second entry acts as a mask to the other entries, permitting access to unauthenticated users.
pdadmin> acl modify Sample1_freeAccess set unauthenticated Tr

If we look at the list of the authorized users on the free ACL we can see that all authenticated and unauthenticated users can access the Sample1 web service WSDL file:
pdadmin> acl show Sample1_freeAccess
	    ACL Name: Sample1_freeAccess
	    Description: Free access to the Sample1 web service WSDL to all users
	        Any-other Tr
	        User sec_master TcmdbsvaBrl
	        Unauthenticated Tr

When a client tries to access the WSDL file, he is prompted for the Server certificate but not the client authentication.

Export the WebSEAL certificate
As a last operation on the server side, we need to export the WebSEAL digital certificate in order to give it to all the web service clients. The exported certificate will contain the WebSEAL public key signed by a CA, or in our sample, self-signed. This certificate can be freely downloaded by everybody and all web service clients will need to register it as the valid server certificate for the proxy host.

To export it, you need to launch the IBM Key Management utility, located by default in c:\Program Files\IBM\gsk5\bin on Windows. Open a Windows Explorer, browse to that directory and double-click on the application gsk5ikm.exe.

At installation, WebSEAL provides a default certificate key database. The webseal-cert-keyfile parameter, located in the [ssl] stanza of the webseald.conf configuration file, identifies the name and location of this file:
# WebSEAL certificate keyfile
webseal-cert-keyfile = C:/Program Files/Tivoli/PDWeb/www/certs/pdsrv.kdb

File type descriptions
.arm An ASCII encoded binary file. A .arm file contains a base-64 encoded ASCII representation of a certificate, including its public key, but not its private key. The original binary certificate data is transformed into an ASCII representation. When a user receives a certificate in a .arm file, iKeyman decodes the ASCII representation and places the binary representation into the appropriate .kdb file. Similarly, when a user extracts a certificate from a .kdb file, iKeyman converts the data from binary to ASCII and places it in a .arm file.

.kdb The .key database. file. Stores personal certificates, personal certificate requests, and signer certificates. For example, the default WebSEAL key database file is pdsrv.kdb.

The default password used for the default certificate key database is "pdsrv".

Using the IBM Key Management, open the certificate key database.

IBM Key Management tool
IBM Key Management tool

Then, click on Extract Certificate... and specify ProxyHostCertificate.arm as the Certificate file name.

Extract Certificate
Extract Certificate

3. Test and validate the WebSEAL configuration

Validate that the Sample1 Web Service is running
Open a browser and enter the URL http://privatehost:6080/Sample1WebService/services/Sample1

You should see the following welcome page for the Sample1 web service. Remember you are accessing a web service that waits for SOAP requests using the HTTP POST method. In our test we use an HTTP browser and the GET method by entering a URL, we cannot expect a SOAP response. That's why you see the following screen.

Sample1 web service access through private host
Sample1 web service access through private host

Open a browser and enter http://privatehost:6080/Sample1WebService/Hello_SEI.wsdl. If your browser supports XML, you should see the following page. Check that the location attribute of the SOAP address is set to use https, your proxy hostname (proxyhost), your proxy port (8443) and the WebSEAL junction /B2BGateway

Sample1 web service WSDL access through private host
Sample1 web service WSDL access through private host

You should obtain exactly the same result using the URL https://proxyhost:8443/B2BGateway/Sample1WebService/Hello_SEI.wsdl as you would accessing the file through WebSEAL -- except that your are prompted for the server certificate. Remember we have not restricted the access to the WSDL file in WebSEAL, all users can see it.

Server certificate
Server certificate

Accept it to see again the WSDL file

Validate the TAM authentication/authorization
We need to check that the address for the web service specified in the WSDL document is really mapped to the web service implementation on the private host. We also need to validate that there is restricted access to the Sample1 web service. On your open browser, enter the URL specified in the WSDL file (https://proxyhost:8443/B2BGateway/Sample1WebService/services/Sample1). You should be prompted for a Basic Authentication. Enter igor as the username and passw0rd as the password.

Basic authentication pop-up
Basic authentication pop-up

You should now see the previous welcome page for the Sample1 web service, this time accessible through SSL and WebSEAL.

Sample1 web service access through proxy host
Sample1 web service access through proxy host

At this point, the Charging Web Service is accessible through SSL and WebSEAL for the user named igor. If we close the browser, re-open it and fill the Basic Authentication fields with the user named sec_master, the access to the Sample1 web service is not auhorized.

Notice that the user sec_master is authenticated by WebSEAL because the Basic Authentication pop-up is not re-prompted. Only the authorization has failed for the sec_master user. This behavior is normal because the ACL Sample1_restrictedAccess associated previously with the Sample1 web service does not provide to the user sec_master the appropriates rights.

Forbidden access to the Sample1 web service for the user sec_master
Forbidden access to the Sample1 web service for the user sec_master

4. Web service client development

Import the proxy server certificate
Now that we've updated the WSDL file for the Sample1 web service and configured WebSEAL, the last step is to write a web service client that recognizes and accepts the Server certificate sends the Basic Authentication headers programmatically.

On the client side (potentially on a remote machine), you first need to download or get by e-mail the WebSEAL certificate that you've exported from your proxy host.

Create a directory c:\Sample1WebServiceClient on your client and copy the file ProxyHostCertificate.arm in that directory. If you're on a different machine, ensure the IBM WebSphere SDK is also installed, and that you use the WSDK JVM.

You can import the WebSEAL certificate using the keytool program furnished in each JDK. To import the certificate into a key store named client.keystore enter the following command
C:\>keytool -import -storepass keypass -keystore c:\Sample1WebServiceClient\client.keystore 
-alias ProxyHostCertificate -file c:\Sample1WebServiceClient\ProxyHostCertificate.arm

keytool documentation

You can find some information on the keytool command in your JDK documentation or on the SUN Java web site:

Enter yes to trust the certificate like it is shown on the next figure.

Import the server certificate into the client key store
Import the server certificate into the client key store

The key store now contains the WebSEAL certificate of the proxy host. You can validate the presence of the certificate inside the key store (protected by the password keypass) using the command
C:\keytool.exe -list -storepass keypass -keystore C:\Sample1WebServiceClient\client.keystore

List the client key store
List the client key store

Client proxy generation
The first step from a client point of view is to generate some proxies from the web service WSDL file, helpful for client-side programming. To be able to generate client proxies using the IBM WSDK, we first need to update the setWSDKProperties.bat program to include support of SSL through the IBM JSSE implementation. Change to the directory <WSDK-install-dir>\appserver\bin , open the setWSDKProperties.bat in a text editor and append to the WSDK_JVM_PROPERTIES environment variable the following new Java properties separated by a space:

Now that SSL is supported, we can launch the WSDL2Java tool to generate client proxies from the web service WSDL file:
C:\WSDK_v5\appserver\bin>WSDL2Java.bat -output c:\Sample1WebServiceClient 

Accessing a WSDL protected with Basic Authentication

if you need to access a WSDL file that is protected by Basc Authentication, you can still specify the username and password on the WSDL2Java command line.

As a result of the preceding operation, several files are generated: some XML descriptors in the META-INF sub-directory that could be used if you want to package your web service client in a J2EE application, and some java classes located in the com/ibm/wsdk/Sample1 sub-directory that are the proxy stubs you can use to develop the web service client.

Client Java code
The java files generated by the previous command are the following:

  • New interface file that contains the appropriate java.rmi.Remote usages.
  • Java file containing the client side service interface.
  • Java file containing the client side service implementation class.
  • Client side stub.

What now create the client application that will interact with the generated stubs without having to deal with SOAP requests or responses, or even with the SOAP runtime (AXIS) used. That's the added value of the JAX-RPC API used in this sample.

Create in directory C:\Sample1WebServiceClient\com\ibm\wsdk\Sample1 a file called and enter the following skeleton code:


public class Sample1WebServiceClient {

public static void main(String args[]) {

  try {
	//Code will go there
  catch(Exception e) {


Accept the WebSEAL digital certificate

To update the web service client's main method in order to recognize the server certificate as valid we need to add the following system properties:

  // Specify the location of where to find key material for the TrustManager.
  // This overrides the default cacerts file in the JRE lib directory.

  // Use the IBM's reference implementation for the "https" URL protocol type.

Send the Basic authentication headers

Pass the client username and password as a Basic authentication header, we have to append the following code:

  // Sample* classes are client proxy classes generated by AXIS from the WSDL
  Sample1InterfaceService service = new Sample1InterfaceServiceLocator();
  Sample1Interface stub = service.getSample1();
  // The username and password used here need to be registered in WebSEAL.
  // They are passed dynamically at the client runtime
  ((Sample1SoapBindingStub)stub)._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, args[0]);
  ((Sample1SoapBindingStub)stub)._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, args[1]);

Call the remote method

Finally, we complete the code for the main method with the call to the remote web service method.

  //Print the output of the remote method called with the input parameter set to the username

Compile the client
Now that we've written the web service client, we can compile it. We need first to set up the CLASSPATH environment variable (linebreaks have been added for readability):

C:\Sample11WebServiceClient>set LIB=<WSDK-install-dir>\appserver\lib
C:\Sample11WebServiceClient>set CP=.;%LIB%\axis.jar;%LIB%\jaxrpc.jar;%LIB%\commons-logging-api.jar; %LIB%\commons-discovery.jar;%LIB%\j2ee.jar;%LIB%\qname.jar;%LIB%\xerces.jar;%LIB%\saaj.jar;%LIB%\wsdl4j.jar

then compilation can be launched using the defined CLASSPATH.

C:\Sample11WebServiceClient>javac.exe -classpath %CP% com\ibm\wsdk\Sample1\*.java

5. Test the client
We now test the web service client, specifying several users. If igor and passw0rd are specified as parameters on the web service client, the remote web service method can be executed:
C:\Sample11WebServiceClient>java.exe -classpath %CP% igor passw0rd
Hello igor!

Launching the same test with the user sec_master will lead to a (403)Forbidden return code:
C:\Sample11WebServiceClient>java.exe -classpath %CP% sec_master passw0rd
 faultCode: {}HTTP
 faultString: (403)Forbidden
 faultActor: null
 faultNode: null
        null: return code:  403

And launching the same test with an unknown user or a bad password would lead to a (401)Unauthorized return code:
C:\Sample11WebServiceClient>java.exe -classpath %CP% sec_master passw0rd
 faultCode: {}HTTP
 faultString: (401)Unauthorized
 faultActor: null
 faultNode: null
        null: return code:  401

In this article you have learnt how you can configure Tivoli Access Manager WebSEAL to protect a web service. WebSEAL can manage authentication and authorization, and can be efficiently combined with SSL to provide a good point-to-point security solution.

On the server side, the WSDL of the web service needs first to be updated to reflect the new architecture topology. Then WebSEAL has to be populated with the junction to the backend HTTP server, with objects representing the web service, with the ACLs and with the authorized users. Finally, we need to export the WebSEAL server certificate and give it to the web service clients.

On the client side, the needs are to import the WebSEAL certificate, and then to update the client code to send the user credentials required by the authentication proxy.


  • "axis.jar" fixed to be able to send SSL requests throiugh the IBM JSSE implementation..

  • "ibmjsse-debug.jar" can be efficiently used to retrieve log information related to the SSL exchanges between the client and the server. Just place the JAR in the same directory that contains the file ibmjsse.jar used by your JDK. When you launch the client or the server, specify the option to enable debug information printed to standard output.

  • Download the "IBM WebSphere SDK for Web Services V5.0" used in this article.

  • "Tivoli Access Manager for e-business product manuals" is of course the best source for understanding Tivoli Access Manager and WebSEAL administrative tasks.

  • It’s also possible to authenticate a SOAP client using a digital certificate instead of the Basic Authentication header. "Web Services Over SSL - HOW TO" by Pankaj Kumar offers additional insight on its usage.

  • "Security with Apache SOAP" by Sylvain Benoist shows you how to pass authentication information in a SOAP client developed with Apache SOAP instead of Axis.

About the author
David Loupia is an IT Specialist that works in La Gaude (France) to support IBM Business Partners. He currently works as an e-business architect providing education and support in the area of Web Services, J2EE and Tivoli security products.

e-mail it!

What do you think of this document?
Killer! (5)Good stuff (4)So-so; not bad (3)Needs work (2)Lame! (1)


developerWorks > Tivoli
  About IBM  |  Privacy  |  Terms of use  |  Contact