SOA authorization using Tivoli Federated Identity Manager and WebSphere Service Registry and Repository

This article describes a service-based approach to authorization in Service Oriented Architecture (SOA) environments using IBM® Tivoli® Federated Identity Manager (TFIM). This approach extends existing IBM solutions for identity propagation in SOA by leveraging Tivoli Access Manager (TAM) as the authorization policy decision point. A software utility to discover services from the IBM WebSphere® Service Registry and Repository (WSRR) to enable the authorization solution will be provided to simplify and accelerate deployment of this authorization solution.


Craig Forster (, Software Engineer, IBM Tivoli

Craig ForsterCraig Forster is a software engineer on the IBM Common Authorization Component team. He joined IBM in 2005 after graduating from the University of Queensland holding a Bachelor of Engineering (Software) with Honours Class 1 and Bachelor of Science (Computer Science).

Neil Readshaw (, Senior Certified IT Specialist, IBM

Readshaw, NeilNeil Readshaw is a Senior Certified IT Specialist in the Tivoli Advanced Technology team. Based in the IBM Australia Development Lab, Neil works with customers to define solutions using the Tivoli Security software suite, and works in an enablement role with IBM Business Partners and the IBM technical sales team in the Asia Pacific region.

developerWorks Contributing author

09 January 2008


Identity propagation in SOA

For Service Oriented Architecture (SOA) to be effective for aligning IT with business, the identity of service requestors must be able to flow through the entirety of a loosely coupled, composite application. Identity propagation in SOA is best considered the responsibility of the SOA infrastructure, not the applications themselves, in order to provide the flexibility required in a dynamic business environment. It is therefore logical that identity be considered as a service which can be invoked from various SOA infrastructure platforms such as application servers and Enterprise Service Buses (ESBs).

The WS-Trust specification (see Resources) provides a standards-based mechanism for SOA infrastructure to access an identity service to validate, transform and issue security tokens representing identities. A service that can respond to WS-Trust requests is called a Security Token Service (STS). Tivoli Federated Identity Manager (TFIM) provides an STS as one of its core components. The interaction between a SOA component and the TFIM STS is shown in Figure 1.

Figure 1. Identity propagation using WS-Trust and the TFIM STS
Identity propagation using WS-Trust and the TFIM STS

In the TFIM STS, different identity propagation configurations can be specified. These configurations are called trust module chains. Incoming requests to the STS are matched to trust module chains in TFIM, based on the values of the AppliesTo, Issuer, and TokenType parameters. In this way, the same logical STS instance can support a variety of different identity requirements.

Trust module chains are composed of module instances, as shown in Figure 2. When a module instance is configured in a trust module chain, it operates in one of a few different modes - validate, map, issue, or other. Figure 2 shows a typical trust module chain structure, with trust modules operating in different modes.

Figure 2. Anatomy of a TFIM STS trust module chain
Anatomy of a TFIM STS trust module chain

Service authorization in SOA

Identity propagation is certainly important in SOA but might not be the end goal. Identity in SOA is a foundation on which additional business value can be delivered. Common uses of the identity foundation are an enabler for:

  • Authorization - Determining the suitability of a service requester to access a service and its operations, based on security policy.
  • Audit - Record the flow of identity through a composite application and the results of service authorization decisions.

TFIM provides a mechanism to extend its SOA identity solution to include service authorization. An authorization module is provided with TFIM that is able to make authorization decisions using Tivoli Access Manager (TAM). The interaction between the Authorization STS module and Tivoli Access Manager infrastructure is shown in Figure 3.

Figure 3. Interaction between the Authorization STS module and TAM
Interaction between the TFIM STS Authorization module and TAM

The Authorization STS module uses the TAM Java™ Authorization API to evaluate authorization decisions. Authorization decisions are determined by making a secure call to the TAM Authorization Server (pdacld). A simple TAM authorization decision takes three inputs:

  • A principal, representing the identity of the user.
  • A protected object, representing the resource being accessed.
  • A set of actions, representing the operation being attempted on the protected object.

The Authorization STS module:

  • Constructs a PDPrincipal object from the current identity in the STSUUSER document in the module chain.
  • Constructs the protected object name from the data in the STSUUSER document available to the trust module chain, according to the structure shown in Figure 4.
  • Uses the invoke action "i" from the [WebService] action group in TAM.
Figure 4. TAM protected object space for SOA service authorization
Interaction between the TFIM STS Authorization Module and TAM

The Authorization STS module is suitable for authorization decisions in trust module chains invoked from the following components:

  • TFIM Web Services Security Management (WSSM) token consumer
  • TFIM WSSM token generator
  • TFIM/DataPower integration point
  • TFIM identity mediation module for WebSphere ESB

TFIM provides a utility called wsdl2tam to create the protected objects in TAM. The wsdl2tam utility parses a single WSDL file and generates a set of commands that can be processed by the TAM pdadmin command to create objects. In environments with a large number of services using TFIM for service-based authorization, this can become a cumbersome process. Moreover, in environments which use a database such as WebSphere Service Registry and Repository or a UDDI directory, the WSDL documents for services need to be exported before they can be operated on with the wsdl2tam utility.

The requirement to export WSDL documents from WebSphere Service Registry and Repository (WSRR) manually has a number of shortcomings. The primary concern is the administration overhead required for this process - exporting each WSDL to a file and invoking wsdl2tam is a time-consuming process. Furthermore, the repetition of this manual process is prone to error.

Solution overview

To address the shortcomings inherent in manually exporting WSDL service definitions from WSRR and converting them to pdadmin scripts individually, an automated solution is required. The solution proposed in this article consists of a number of steps, as outlined in Figure 5.

Figure 5. Processing flowchart
Processing flowchart

The main steps in the solution are:

  1. Connect to an existing WSRR installation using the standard APIs
  2. Prompt the user for a pattern to search for in WSDL file names in the registry. This avoids listing a potentially large number of services in a heavily populated service registry.
  3. Search the registry for WSDL names matching the provided pattern.
  4. Display the matching WSDL names and prompt to select one or more to be processed.
  5. For each of the selected WSDL names, extract the full WSDL from the registry.
  6. Invoke the WSDL2TAM tool to create a pdadmin script that will populate the TAM Object Space for this WSDL.
  7. If there are more WSDLs to extract and convert, return to Step 5.
  8. When all the pdadmin scripts have been converted, invoke pdadmin to populate the TAM protected object space.

While there are still manual steps in this solution, there are a number of advantages that this solution provides. First, it is much easier to search and extract the relevant WSDLs from the registry. Second, using an automated tool to create the pdadmin scripts helps to ensure that no exported WSDLs are omitted from processing. The possibility for introducing errors is significantly reduced.

Populating the TAM protected object space from WSRR

This article provides a tool that builds upon wsdl2tam to allow the creation of pdadmin scripts using information extracted from WebSphere Service Registry and Repository (WSRR). This integration reduces the manual steps involved in populating the TAM protected object space required for authorization decisions.

The solution is in the form of a command-line Java application. This application connects to a WSRR installation using the Web services API, and displays a list of the WSDL files currently stored in the registry. The user can also specify a search string in order to filter the WSDLs returned. When the list of WSDL files is displayed, the user can select which file or files they want to extract from the service registry and create pdadmin scripts for. Figure 6 shows the solution architecture.

Figure 6. Solution architecture overview
Solution architecture overview

The full solution with source code is provided in the Download section below, however there are a number of important steps that should be highlighted. These three steps are outlined in the following code snippets:

  1. Retrieving the list of WSDLs from WSRR
  2. Extracting a specific WSDL from WSRR
  3. Converting the WSDL to a pdadmin script using wsdl2tam.

Listing 1 shows how to retrieve a list of WSDLs from WSRR. Because the number of WSDLs stored in the registry can be large, the functionality to search by the WSDLs name is provided. This searching is done via simple substring search. Furthermore, two pieces of information are explicitly extracted from WSRR in this step: the WSDL's name, and its bsrURI. This URI is the unique identifier for a document stored in WSRR, and will be used later to reference the WSDL in order to extract it in full.

Listing 1. Retrieving a list of WSDLs from WSRR
String PARAM_NAME = "name";
String PARAM_BSR_URI = "bsrURI";

//First get a connection to WSRR
WSRRCoreSDOClient client = new WSRRCoreSDOClient( srrURL );

//Setup our query to find the WSDLs in WSRR
PropertyQuery pq = (PropertyQuery)DataFactory.INSTANCE.create(
	TypeConstants.SR_URI, TypeConstants.TYPE_PROPERTYQUERY );
if ( substring == null || "".equals( substring)  )
	pq.setQueryExpression( WSRR_SEARCH_STRING );
	pq.setQueryExpression( WSRR_SEARCH_STRING + "[ matches( @name, '.*" + substring 
		+ ".*', 'i')]" );

BSRSDOHelper.INSTANCE.addProperty( pq, "p1", PARAM_NAME );
BSRSDOHelper.INSTANCE.addProperty( pq, "p2", PARAM_BSR_URI );

//Execute our query
List propertyQueryResults = client.executeQuery( pq );

Listing 2 shows how the user selects a result from the list returned by the code in Listing 1, retrieves the WSDL document from the registry, and writes the WSDL document to a temporary file on disk. The user selection is in the form of an integer index into the list of results from the code in Listing 1.

Listing 2. Extracting a WSDL and writing it to disk
int wsdlNum = getUserSelection();

PropertyQueryResult selectedResult = 
	(PropertyQueryResult) propertyQueryResults.get( wsdlNum );
String name = BSRSDOHelper.INSTANCE.getPropertyQueryResultValue( 
		selectedResult, PARAM_NAME );
String bsrURI = BSRSDOHelper.INSTANCE.getPropertyQueryResultValue( 
		selectedResult, PARAM_BSR_URI );
//Retrieve the WSDL specified based on it's URI
WSDLDocument wsdl = (WSDLDocument) client.retrieve( bsrURI );

//Create our temporary output file
File wsdlFile = File.createTempFile( name, ".cache" );

//Write the WSDL contents to the temporary file.
OutputStream wsdlWriter = new FileOutputStream( wsdlFile );
wsdlWriter.write( wsdl.getContent() );

Listing 3 shows how to invoke the wsdl2tam tool from TFIM in order to convert this WSDL into a pdadmin script. The wsdl2tam tool takes three arguments:

  1. The name of the WSDL, which is used to name the sub-tree in the TAM protected object space;
  2. The location to write the pdadmin script to;
  3. The location of the WSDL file to convert, which is the temporary file created in Listing 2.
Listing 3. Converting a WSDL file to a pdadmin script
String tamOutput = TAM_DIR + File.separator + name + ".pdadmin";
File tamFile = new File( tamOutput );
//Call WSDL2TAM to do our conversion
//The arguments to WSDL2TAM
// -n wsdlName...
// -tam [tam_script_file]
// [wsdl_file]
String[] wsdl2tamArgs = new String[] { "-n", name, 
		"-tam", tamFile.getAbsolutePath(), 
		wsdlFile.getAbsolutePath() }; wsdl2tamArgs );

When the desired WSDLs have been extracted from WSRR and converted to pdadmin scripts, the pdadmin tool can be used to execute the scripts and populate the TAM protected object space. Because the script for each WSDL has been written to a separate file, a UNIX® or Linux® shell script can be useful to automate the process of executing these scripts. An example of such a shell script, using Bourne shell, is shown in Listing 4. Execute the script from the same directory as the saved files, with the appropriate values substituted for the TAM administrative login credentials.

Listing 4. Automating the execution of the pdadmin scripts
for i in *.pdadmin
do pdadmin -a [admin_id] -p [password] $i


In order to illustrate the functionality of this tool, a simple test service will be used. This test service is called 'EchoService', and simply echoes the input back to the caller of the service. The WSDL for this service is shown in Listing 5.

Listing 5. The EchoService WSDL
<wsdl:definitions xmlns:wsdl="" 
    <xsd:schema targetNamespace="" 
      <xsd:element name="EchoOperation">
            <xsd:element name="in" type="xsd:string"/>
      <xsd:element name="EchoOperationResponse">
            <xsd:element name="out" type="xsd:string"/>
  <wsdl:message name="EchoOperationRequest">
    <wsdl:part element="tns:EchoOperation" 
  <wsdl:message name="EchoOperationResponse">
    <wsdl:part element="tns:EchoOperationResponse" 
  <wsdl:portType name="EchoService">
    <wsdl:operation name="EchoOperation">
      <wsdl:input message="tns:EchoOperationRequest"/>
      <wsdl:output message="tns:EchoOperationResponse"/>
  <wsdl:binding name="EchoServiceSOAP" 
    <soap:binding style="document" 
    <wsdl:operation name="EchoOperation">
        <soap:body use="literal"/>
        <soap:body use="literal"/>
  <wsdl:service name="EchoService">
    <wsdl:port binding="tns:EchoServiceSOAP" 
      <soap:address location=""/>

This service is deployed at the URL '' as shown in the address of the port binding above, and for the purposes of this example assume that there is a WebSphere Service Registry and Repository installed at the host '' that includes an entry for this service.

Listing 6 shows an example of invoking the tool. The listing shows searching for the service based on the string 'Echo', then saving the WSDL in the file 'tam/EchoService.wsdl.pdadmin'. The tool is packaged in wsrr2tam.jar, located in the Download section of this article. The following libraries are required to execute this tool:

  • sdo-int.jar from a WSRR install
  • ServiceRegistryClient.jar from a WSRR install
  • ibm-jaxrpc-client.jar from the WebSphere Application v6.0 runtime/ directory.
  • itfim-wssm-common.jar from a TFIM install
  • itfim-wssm-mgmt.jar from a TFIM install

When these pre-requisites are available, the tool can be invoked from the command line. User inputs are shown in bold in Listing 6.

Listing 6. Invoking the WSRR2TAM tool
[wsrr2tam]$ java -classpath itfim-wssm-common.jar:itfim-wssm-mgmt.jar:sdo-int.jar:\
	ServiceRegistryClient.jar:ibm-jaxrpc-client.jar:wsrr2tam.jar \
Enter the SRR location in the form 'host:port' [localhost:9080]:
Enter a sub-string to filter WSDL names by (optional): Echo
        /WSRR/WSDLDocument[ matches( @name, '.*Echo.*', 'i')]
The following WSDLs were found on the server:
        1: EchoService.wsdl
Select a WSDL number to convert to TAM, or press enter to modify search parameters.
Specify multiple WSDLs using the format '1-3,5,6-10':
Retrieved WSDL 'EchoService.wsdl' from WSRR.
Select a file to write the PDADMIN script to ['tam/EchoService.wsdl.pdadmin']:

The pdadmin script was successfully written.
Convert more? yes / no [yes]: 

When invocation is complete, a pdadmin script containing the data shown in Listing 7 is produced. This script can be executed using the command shown in Listing 4, which results in the protected objects being created in TAM.

Listing 7. pdadmin Script for the EchoService WSDL.
action group create WebService
action create i wssm 0 WebService
objectspace create /itfim-wssm wssm 0
object create /itfim-wssm/wssm-default wssm 0 ispolicyattachable yes
object create /itfim-wssm/wssm-default/EchoService.wsdl wssm 0 ispolicyattachable yes
object create /itfim-wssm/wssm-default/EchoService.wsdl/EchoService wssm 0 \
	ispolicyattachable yes
object create /itfim-wssm/wssm-default/EchoService.wsdl/EchoService/EchoService wssm 0 \
	ispolicyattachable yes
object create /itfim-wssm/wssm-default/EchoService.wsdl/EchoService/EchoService/ \
	EchoOperation wssm 0 ispolicyattachable yes

After the object space is created in TAM, authorization policy can be configured. The most common authorization policy construct in TAM is an ACL, although POPs and Authorization Rules can also be configured. In an ACL, the invoke permission 'i' from the WebService action group is what is checked by the authorization request originating in the Authorization STS module. Also note that a TAM policy object, such as an ACL, does not need to be attached to every object in TAM, because it has an inheritance model to determine effective policy on any object in the TAM protected object space.

The last step in using the configuration in the TAM protected object space is to configure one or more instances of the Authorization STS module in trust module chains that will be invoked from SOA components such as WebSphere ESB or a DataPower XML Firewall. The TFIM 6.1.1 Information Center contains guidance on configuring the Authorization STS module configuration.

Future work

The utility described in this program can be extended to also work with Universal Description Discovery and Integration (UDDI) solutions such as WebSphere UDDI Registry.


In an SOA environment, propagating identity is a necessary foundation for services such as authorization and auditing. IBM Tivoli Federated Identify Manager (TFIM) provides a way to integrate authorization and access control into a trust chain through an Authorization STS module. This module depends on Tivoli Access Manager (TAM), which requires its object space to be populated using information from service descriptions in WSDL format. This article provides a way to automate the process of extracting service information from IBM WebSphere Service Registry and Repository (WSRR), create a set of administration scripts to populate the object space, and execute those scripts using a TAM administration tool.


The WSRR2TAM utility described in this articlewsrr2tam.zip8.4KB



Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Security on developerWorks

Zone=Security, Tivoli
ArticleTitle=SOA authorization using Tivoli Federated Identity Manager and WebSphere Service Registry and Repository