Integrating Tivoli Federated Identity Manager and Tivoli Identity Manager

An enabler for SOA identity propagation

IBM® Tivoli® Federated Identity Manager (TFIM) is IBM's solution for identity propagation in Service-Oriented Architecture (SOA). As well as providing support for a variety of security token types, identity processing in TFIM can transform identities from one administrative domain to another. In this article, the design and implementation of a customized mapping module for TFIM will be presented. Tivoli Identity Manager (TIM) will be used as the source of identity metadata used to map the incoming identity to another identity.


Neil Readshaw (, Senior Certified IT Specialist, IBM Australia Development Lab

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

12 September 2008


Tivoli Federated Identity Manager (TFIM) provides infrastructure that enables identity propagation in SOA. The TFIM Security Token Service (STS) is an identity and authentication service that implements the WS-Trust specification. The IBM Redpaper "Propagating Identity in SOA with IBM Tivoli Federated Identity Manager" provides an introduction to using TFIM in a SOA environment. When propagating identities between service components, there are three key requirements:

In what format must the identity be presented to a service component?

SOA platforms and applications have differing capabilities in terms of the token types that they support. Some systems are only able to support a small number of security token types natively. Others might be running on a more flexible infrastructure that can understand security tokens in a variety of formats. The TFIM SOA identity infrastructure supports the validation and issuance of a wide variety of token formats including Security Assertion Markup Language (SAML), Kerberos, X.509, Lightweight Third Party Authentication (LTPA), and Username.

Which identity should be propagated in the security token?

For applications composed of loosely coupled service components, it is common that the user repositories might not use the same unique identifier (that is, userid and username) for a given user. Different user repositories can use different naming conventions for constructing the user identifier, or in some cases the identity required might not be unique to a user, but be specific to their role in the organization. TFIM caters to this by providing a number of STS modules that can perform identity mapping. These modules provide the ability to look up data using:

  • Lightweight Directory Access Protocol (LDAP)
  • Tivoli Access Manager (TAM) Global sign-on (GSO) credential store
  • Tivoli Directory Integrator (TDI)

Simple mappings can also be achieved in TFIM by using the eXtensible Stylesheet Language (XSL).

Which attributes of an identity should be included in the security token?

Propagating more than just the username or other unique identifier provides additional information to the security infrastructure of a service component. These additional attributes can be used as part of an authorization decision or other action within the service component. Security token formats such as SAML and LTPA are capable of including arbitrary attributes in the security token. Other security token formats, such as Username, cannot. Including arbitrary attributes in security tokens is achieved in TFIM through the use of suitable security token and identity mapping modules in a trust module chain in the STS.

In environments where the portfolio of Tivoli identity management software is deployed, it is common to observe the use of Tivoli Identity Manager (TIM) to manage the account lifecycle across a number of users and systems. This article shows how to leverage an existing TIM deployment when designing and implementing a SOA identity solution using TFIM. A possible use of the solution presented in this article is shown in Figure 1.

Figure 1. Integrating TIM with the TFIM STS
Integrating TIM with the TFIM STS

In the diagram above, a service request is mediated by an enterprise service bus (ESB). The ESB has been configured to invoke TFIM to perform identity mediation, using an existing WS-Trust integration point. The trust module chain in the STS would first validate the security token in the incoming message using a trust module instance for that security token type. Next, the TIM mapping module instance would map the incoming identity data to a different identity using the metadata in TIM. The resulting identity data is reformed into a different security token using a trust module instance for the type of the returned security token.

About Tivoli Identity Manager

Tivoli Identity Manager is a user provisioning solution that can manage user accounts across a wide variety of platforms. For detailed information on TIM, consult the Information Center in the Resources section at the end of this article. The TIM directory (an LDAP directory) stores metadata about users and their accounts. A partial TIM data model is shown in Figure 2.

Figure 2. TIM data model (partial)
Partial TIM data model

The relevant data relationships for this article are as follows:

  • A person represents a human or system entity that can possess accounts on one or more managed systems.
  • A service represents a system managed by TIM.
  • Each service will contain zero or more accounts. Account data can consist of a user identifier and a number of other attributes. The schema for an account is determined by the type of service to which the account belongs.
  • A person owns zero or more accounts. A person can own multiple accounts per service and can own accounts across multiple services, as shown in Figure 3.
Figure 3. TIM account ownership model
Account ownership model

The TIM directory retains a copy of account data for all accounts on all systems managed by TIM. This is used in TIM for purposes such as auditing, reporting, and account revalidation. The advantage of retaining the copy of this data in TIM is that these operations can be undertaken without directly affecting the managed systems themselves.

Solution design

Figure 4 shows the high level architecture for a solution that uses TIM as a repository of identity mapping information in a SOA identity solution. A TIM mapping module is developed for TFIM using the TIM Java™ API.

Figure 4. Architecture of TIM mapping module
Mapping module overview

STS module interface

TFIM modules implement the interface. The key aspects of using this interface are:

  1. Creates an OSGi extension point to define the capabilities and user interface aspects of the module.
  2. Develops a class that implements the STSModule interface. This is where the business logic of the module is implemented.
  3. Creates a java.util.ListResourceBundle that contains the labels for the user interface components of the module.

The requirements for the module are to transform identities, so the map module will be the only mode supported for this module.

Table 1 describes the configuration properties that are available to the TFIM administrator when configuring an instance of the TIM mapping module. Notice that the parameters required to connect to the TIM environment are specified here. This simplifies the configuration when multiple trust module chains need to interact with the same TIM server, though for different identity transformations.

Table 1. Module instance configuration properties
Configuration propertyDescriptionSample value
Module instance nameThe name of the module instance. This is the label displayed in the list of module instances when constructing a trust module chain.TIM mapping - prod
Module instance descriptionDescription of the module and its purpose.Connects to production TIM environment.
TIM server hostHostname or network address where the WebSphere® Application Server (WAS) instance hosting the TIM server is
TIM server IIOP portIIOP port number of the WAS instance hosting the TIM server.2809
TIM administrator IDUser ID of TIM account used to access data in TIM. Note that an administrator account such as "itim manager" is not mandatory, but the account will require sufficient access to read and search account and service data in TIM. TIM ACIs can be used to grant minimal permissions in TIM for the user specified here.itim manager
TIM administrator passwordPassword for the TIM administrator described in the previous parameter.Ccs0kwcs
TIM base DNThe LDAP distinguished name constructed from the short name of the organization configured in TIM, and the LDAP suffix under which TIM data is stored.ou=enterprise,dc=com
WAS administrator IDUser ID for authenticating to the WAS instance hosting the TFIM runtime. A value for this parameter only needs to be supplied if administrative security is enabled in the TFIM Runtime instance of WAS.wasadmin
WAS administrator passwordPassword for the account specified by the preceding parameter. A value for this parameter only needs to be supplied if administrative security is enabled in the TFIM Runtime instance of WAS.c7i3hj%H
JAAS application loginThe name of the Java Authentication and Authorization Service (JAAS) application login configured in the TFIM instance of WAS and used to authenticate to the TIM server.ITIM

Table 2 lists the configuration properties available when configuring an instance of the TIM mapping module in a trust module chain. These parameters are specific to a particular identity transformation. The configuration data that defines the TIM server is obtained from the module instance properties.

Table 2. Module configuration properties
Configuration propertyDescriptionSample value
Service name for incoming accountName of TIM service in which to search for the account that corresponds to the identity received as input to the TIM mapping module. The name of the service is assumed to be unique.Active directory - Queensland
Service name for target accountName of the TIM service in which to search for the account owned by the owner of the incoming identity. Again, the name of the service is assumed to be unique.Enterprise directory
Target account objectclassLDAP object class used in TIM to store account data for accounts for service specified by the preceeding parameter.erTAMAccount
Target account attributesList of additional attributes retrieved from the mapped account. One attribute value per line. givename

For more information on exploiting the STSModule interface, consult the excellent tutorial listed in the Resources section at the end of this article.


The TIM API is an API that provides remote connection to the TIM server from Java and J2EE™ environments. A number of resources are provided on an installed TIM system to help develop applications using the TIM API. ITIM_HOME/extensions/doc/index.html is the starting point for conceptual information and sample code for using the Java API. ITIM_HOME/extensions/api/index.html is the main JavaDoc page for using the TIM API.

The pseudo-code for how the mapping module uses the TIM API is shown in Listings 1 and 2.

Listing 1. Module initialization pseudo-code
Create a TIM platform context
Create a JAAS login context
Listing 2. Mapping pseudo-code
Locate the service for the incoming identity.
Search for account from incoming service that matches the incoming identity.
Find the owner of that account
Locate the service for the target identity.
Search for an account from the target service owned by the owner from the previous step.
Return attributes from target account.


The source code for the solution is provided in the Downloads section at the end of this article. This can be imported into an Eclipse environment using the Project Interchange format.

One important and possibly non-obvious aspect of the implementation is that the code to construct the TIM platform context and login context needs to run in the J2EE environment, not the OSGi environment. A technique for achieving this is described in the Resources section at the end of this article. Listing 3 shows a code snippet that implements the J2EEContainerAction class. Listing 4 illustrates how to invoke the code from Listing 3 so that it runs in the J2EE environment as required in this solution.

Listing 3. LoginHelper
public class LoginHelper implements J2EEContainerAction
  public Object run()
        throws LoginException, RemoteException, ApplicationException
    create platform context
    create login context
Listing 4. Invoking the LoginHelper
LoginHelper helper = new LoginHelper(...);

try {
} catch (J2EEContainerActionException jcae) {
  throw new STSModuleException(jcae.getMessage(), jcae);


The configuration steps required to use the TIM mapping module for TFIM are described in this section.

Prepare the WebSphere Application Server (WAS) environment

To use the TIM Java API from WAS, configure the WAS instance needs so that the required TIM classes are present and able to be invoked. In this example, these steps need to be performed in the WAS instance in which the TFIM STS (Runtime) is installed and running.

Locate the TIM API JAR files from an installed TIM system. The JAR files will be located in the ITIM_HOME/lib directory on the TIM server. On the machines running the TFIM Runtime, the JAR files should be copied into the WAS_HOME/lib/ext directory, or WAS_HOME/lib directory if the embedded WAS version is being used (such as in a test environment). The JAR files to be copied are:

  • api_ejb.jar
  • itim_api.jar
  • itim_common.jar
  • itim_server_api.jar
  • jlog.jar

Restart the WebSphere Application Server instance hosting the TFIM Runtime.

Authentication to the TIM server requires that a JAAS application module be created in the WAS instance in which the TFIM Runtime is executing. Use the procedure below to achieve this outcome.

  1. With a browser, logon to the Integrated Solutions Console (ISC) for the appropriate WAS instance.
  2. From the left navigation menu, navigate to the Security" / "Secure administration, applications, and infrastructure task.
  3. Expand the Java Authentication and Authorization Service container.
  4. Choose Application logins. The current list of JAAS application login configurations is displayed.
  5. Click New to create a new configuration.
  6. Supply the alias value ITIM.
  7. Click Apply.
  8. Under Additional properties, select JAAS login modules. The list of current JAAS application login modules is displayed. It should be empty.
  9. Click New.
  10. Enter for the module class name.
  11. Check the Use login module proxy checkbox.
  12. Click OK.
  13. Click Save to save these configuration changes directly to the master configuration.

Deploy the TIM STS module

Because TFIM STS modules are packaged as OSGi plug-ins, they can be rapidly deployed to update a TFIM Runtime environment. Use this procedure to deploy the TIM mapping plug-in.

  1. Copy the download to the FIM_HOME/plug-ins directory.
  2. With a browser, logon to the Integrated Solutions Console (ISC) for the appropriate WAS instance.
  3. Navigate to the "Tivoli Federated Identity Manager" / "Domain Management" / "Runtime Node Management" task.
  4. Click the Publish plug-ins button as shown in Figure 5. This updates the TFIM Management Service with the plug-ins from the TFIM install directory to where the new plug-in was copied in Step 1 above.
Figure 5. Publish plug-ins
Publish plug-ins
  1. Click the Load configuration changes to Tivoli Federated Identity Manager runtime button as shown in Figure 6 to update the TFIM Runtime.
Figure 6. Updating TFIM Runtime configuration
Updating TFIM Runtime confguration
  1. Verify that the module name now appears in the list of modules by navigating to the Configure Trust Service / Module Types option in the ISC.
  2. Check that the hostname designated in the TIM server's instance of WebSphere Application Server can be resolved from the TFIM machine. This step is required because the endpoint for communicating with the TIM server is provided from the TIM instance of WAS during the initialization of the TIM API. The hostname used by the TIM instance of WAS can be determined by checking the file WAS_HOME/profiles/profile-name/logs/AboutThisProfile.txt from the WAS instance used by TIM. If required, update the DNS or local host confguration database on the TFIM server.

Using the solution

To use the TIM mapping module deployed in the previous section involves three steps:

  1. Creating and configuring a module instance
  2. Using the module instance in a module chain
  3. Testing the solution

These steps are described in the ensuing sub-sections.

Create a module instance

A module instance needs to be created before it can be used in a trust module chain. Table 1 describes the configuration properties for an instance of the TIM mapping module. Figure 7 shows how the TIM mapping module instance can be configured in using the Integrated Solutions Console. Refer to Table 1 for guidance on choosing suitable values for the configuration parameters.

Figure 7. TIM mapping module instance properties
TIM mapping module instance properties

A single instance of the TIM mapping module can be used in multiple trust module chains. Multiple instances of the TIM mapping module must be configured if the TFIM environment needs to connect to more than one TIM environment, or if different credentials need to be used to access the same TIM environment.

Use the module instance in a module chain

Figure 8 shows how the TIM mapping module might appear after being configured in a module chain. Refer to Table 2 for guidance on choosing suitable values for the configuration parameters.

Figure 8. Configuring the TIM mapping module in a module chain
Configuring the TIM mapping module in a module chain

Test the solution

A simple test harness to see the TIM mapping module operate uses a simple WS-Trust RequestSecurityToken and sending it to the TFIM Security Token Service. A convenient representation of the incoming and outgoing token types is the TFIM internal STS Universal User (STSUUSER). A sample input message is provided in the Downloads section and is shown in Listing 5. The security token in Listing 5 includes an STSUUSER security token including a single name attribute. No other attributes are included.

Listing 5. RequestSecurityToken message
<soapenv:Envelope xmlns:soapenv=""
            <stsuuser:Attribute name="name">
          <stsuuser:AttributeList />

A TFIM test environment is configured with a trust module chain that includes:

  1. STSUUSER token module in validate mode
  2. TIM mapping module in map mode
  3. STSUUSER token module in issue mode

An HTTP client, such as curl, can be used to deliver the WS-Trust request to the TFIM STS. Sample usage is provided in Listing 6.

Listing 6. Curl command to test TIM mapping module
curl.exe --header "soapaction: anything" --data-binary @rst.xml \"

Listing 7 shows a sample response after successful processing using the TIM mapping module. Notice that the resultant STSUUSER security token contains a different username. Additionally, surname and common name attributes are extracted from the target TIM account and included in the resultant security token.

Listing 7. RequestSecurityTokenResponse message
  <soapenv:Header />
    <wst:RequestSecurityTokenResponse Context=""
            <stsuuser:Attribute name="name" type="">
                cn=David Brown
            <stsuuser:Attribute name="Username"
                cn=David Brown
            <stsuuser:Attribute name="sn">
            <stsuuser:Attribute name="cn">
                cn=David Brown
              <stsuuser:Value>David Brown</stsuuser:Value>
            <stsuuser:Attribute name="KeySize"
            <stsuuser:Attribute name="RequestType"
            <stsuuser:Attribute name="Base"
                  <stsuuser:AttributeList />
            <stsuuser:Attribute name="Forwardable"
            <stsuuser:Attribute name="RenewingAllow"
            <stsuuser:Attribute name="Issuer"
            <stsuuser:Attribute name="RenewingOk"
            <stsuuser:Attribute name="AllowPostDating"
            <stsuuser:Attribute name="Delegatable"
            <stsuuser:Attribute name="AppliesTo"
          <stsuuser:ContextAttributes />
          <stsuuser:AdditionalAttributeStatement />


This article described the design and implementation of a mapping module for TFIM that leverages the identity metadata stored in TIM. This module can be used in SOA identity propagation scenarios in components such as enterprise service buses to transform identity information.


Project interchangetim-project-interchange.zip101KB
Manifest file for TFIM OSGi connector1MANIFEST.MF80KB
Deployment package for TIM mapping
Sample WS-Trust request to test mapping modulerst.xml2KB


  1. File is found in the directory.



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 Tivoli (service management) on developerWorks

Zone=Tivoli (service management), Security, Tivoli
ArticleTitle=Integrating Tivoli Federated Identity Manager and Tivoli Identity Manager