The security token service

Federated Identity Manager provides an implementation of the Web Services Trust Language (WS-Trust) specification that allows it to exchange, issue, and validate security tokens of varying formats. When an incoming request is received, the trust server uses a policy-based mechanism to select an appropriate series of modules, or module chain, to process the request and return a response. Modules and module chains allow us to abstractly understand several different security token types and convert between them. The out-of-the-box support is provided for SAML 1.0, Liberty 1.1/1.2, Tivoli Access Manager credentials, and username-password tokens. However, enterprises can require custom security tokens.

In addition to security token modules, the trust server supports other types of modules that act upon information received from the upstream chain. For example, one module might require that an e-mail is sent to an administrator whenever a certain user attempts to access the system; that enterprise can develop a module to perform that action after validating the token presented to the trust server.

The WS-Trust implementation

The external behavior of the Security Token Service is dictated by the WS-Trust specification. This specification explains how to validate, exchange, and issue security tokens in a standard manner. The Federated Identity Manager integrated Security Token Service provides the ability to fulfill WS-Trust requests by executing a configurable module chain, where each module modifies a security token until the requested operation completes.

The interface to the Security Token Service is the WS-Trust RequestSecurityToken element. All requests end with a corresponding RequestSecurityTokenResponse element. Upon receiving a request, the Security Token Service uses the Issuer and AppliesTo elements of the request to select the appropriate chain used to process the request. When configuring a module chain within Federated Identity Manager, it is important that the Issuer and AppliesTo match the requests you plan to receive so that your chain is selected. Listings 7 and 8 show the XML request-response flow from the Web service client to the WS-Trust end point provided by Federated Identity Manager.

About token modules

Modules are organized into module chains. The trust server selects a chain based on the AppliesTo and Issuer elements presented during the Web service request. Federated Identity Manager maintains multiple chain mappings that allow it to map the AppliesTo and Issuer to the appropriate module chain. While the Federated Identity Manager Console automatically maintains module chains for federations and partners, custom module chains are available that allow users to define module chains that respond to WS-Trust requests. For example, the following module chain configuration results in three different modules called in different modes, as shown in the listing and diagram below. See Listing 3 for an example of a module's execution.

				
    <sts:STSModuleChain id="uuide5f4a935-00fb-f5c2-f748-d755a88d7f47">
        <sts:ChainName>Extranet Token Issuer</sts:ChainName> 
        <sts:Module mode="validate" moduleConfigurationId="module-config-id-1" /> 
        <sts:Module mode="map" moduleConfigurationId="module-config-id-2" /> 
        <sts:Module mode="issue" moduleConfigurationId="module-config-id-3" /> 
        <sts:Description>Issue an extranet token for our partners.</sts:Description> 
    </sts:STSModuleChain> 

Modules must follow a few rules to conform with the system:

• Each module must be stateless and atomic. Federated Identity Manager creates one module instance for each module chain, but provides the necessary configuration and context for each request.
• Each module must implement the STSModule interface. See Listing 2 for details on the interface. For each applicable request, the trust server passes context information and the requested mode (validate, exchange, or issue). As each module in the chain processes the token, they can place context information in the STSRequest object to provide information to downstream modules. Attributes placed in the STSRequest persist for the life of the request; the request object is cleared for each request.
• Modules performing validate or issue operations must return results in an intermediate format, the STSUniversalUser.
• Not all modules must provide a user interface, but configuration information might be required. In this case, user interfaces must be specified using a built-in format, GUIXML.
• Modules must be packaged and deployed in a specific manner. See the section Deploying the module for more information.

				 
    public interface STSModule { 
        public void init(Map config) throws STSModuleException; 
        
        public void destroy() throws STSModuleException; 
        
        public boolean invoke(STSMode mode, STSRequest request, STSResponse response) 
            throws STSModuleException; 
    }
            

The STSUniversalUser

All modules that issue or validate tokens must use the STSUniversalUser as the intermediate format (by either populating the object or consuming information contained within the object). This format allows all modules in the module chain to contribute information to the response, and allows the trust server to put the appropriate information into the response. The STSUniversalUser is represented as both a Java™Bean technology and an XML document. Each instance of an STSUniversalUser provides principal information, group membership information, and attribute information. Each attribute in the Universal User is a tuple of name, value, and type. The schema for the Universal User represents almost all elements as attributes; some elements, such as Principal, have special names but are still represented as attributes. Figure 2 shows a diagram of the STSUniversalUser schema.

User interfaces using GUIXML

Modules have the option of providing a user interface for configuration information. The user interface is integrated with the Federated Identity Manager Console, and will be presented whenever an administrator needs to provide module instance configuration information. If a user interface is required, it must be specified in an XML format that conforms to a packaged schema. The following section, Anatomy of a GUIXML document, explains this schema in detail.

The schema allows developers to describe the user interface presented for their module in terms of several different component types. GUIXML provides support for simple components such as text fields or check boxes. Components are grouped into pages, and modules can specify that a different page be provided for each possible mode (validate, issue, and exchange). Developers may internationalize module user interfaces through Java resource bundles. The configuration information provided in each field is automatically stored with the module configuration and provided to the module instance at initialization time. Examples of a user interface and how to package the user interface with your custom module are provided in later sections of this article.

Anatomy of a GUIXML document

GUIXML documents must follow an XML schema format in order for the document to be successfully displayed in the Management Console. This section details the major elements of that schema.

The root element of all GUIXML documents is the Page element. This element contains page's title and the actual form user interface. The PageTitle element gives the panel a title. The PageLayouts element contains the actual form elements. See Figure 3 for a diagram of the document's root elements. Each PageLayouts element contains at least one PageLayout element, which specifies the look of a form for a given configType. The configType attribute specifies the type of configuration that this form applies to:

• init: Any parameters specified with this type are passed to the module upon initialization as the FIM server starts up. These parameters should be used for all requests passed to the module.
• self: Configuration that applies to the self-side of a federation chain. Most custom modules should use this type.
• partner: Configuration that applies to a partner in a federation chain.

See Figure 4 for a schema diagram of the PageLayouts element.

The number of controls available to GUIXML documents is left to minimal elements, as these panels are intended for advanced use. GUIXML supports a text field, text area, checkbox, and one advanced control for selecting a key identifier from the Federated Identity Manager key configuration.

The individual form controls are placed inside of a PageLayout element. The controls are laid out in order of specification. All form controls share a common set of attributes, specified by the ComponentBase type. Figure 5 shows the schema for the ComponentBase type. For each control, the following attributes must be specified (in addition to attributes required by the individual controls):

• name: The name of the configuration parameter used to associate the control's value in configuration files.
• required: Whether the user of the form is required to enter a value in the field before the form can be submitted. If the user leaves a required field blank, the Management Console will display an error and not allow the form's submission until the field has a value.
• modes: The module modes that this control should be displayed for. Each module in a chain can be executed in validate, map, issue, exchange, or "other" mode. Specify a comma-separated list of modes in which this field is valid.

Figure 6 shows the schemas for each of the four controls. Figure 7 shows an example of the SAML module configuration panel, which uses the TextField, CheckBox, and KeyIdentifier controls. Specifications on the attributes available for each control are as follows:

• TextField: A single-lined text field used for short configuration data. This control has the following attributes:
  • password: If set to "true," will be treated as a password field where the characters entered are masked with dots or stars (depending on the browser in use).
  • displayWidth: The number of characters this field should display on the form.
  • defaultValue: The default value for the field. This value will be automatically populated in the field when the form is rendered.
• KeyIdentifier: Presents the user with a control that allows for the selection of a keystore and associated key. All keys and keystores must be configured using the key management features of Tivoli Federated Identity Manager. The Management Console displays a drop-down list of all keystores, a text field for the user to enter the keystore password, a "List Keys" button that the user clicks to list all the key aliases in a particular keystore, and a table to display those aliases. The user is meant to select a keystore from the drop-down list, enter the password in the text field, click the "List Keys" button, then select the key alias they want from the table. Optionally, a checkbox can be displayed to enable or disable the entire key selection control. This provides the ability to make key selection optional for a given module. The key identifier control has the following attributes:
  • enabledName: Optional attribute of the parameter name used for storing the choice of whether a key needs to be used.
  • checked: Optional attribute to determine if the key selection control is enabled or disabled by default.
  • keyTypes: Optional attribute used to filter the types of keys displayed. Key types are defined in the ValidKeyType GUIXML schema type. Valid selections are "public", "keypair", and "symmetric".
  • To specify labels for both the checkbox and the key identifier layout, use two ComponentLabel elements. Within each ComponentLabel element, specify a "for" attribute with the value of either "keyidentifier" or "checkbox". The "for" attribute is optional and used only in the case where you have a checkbox. In the case where you do not have a checkbox, you would have only one ComponentLabel, so the "for" attribute is unnecessary.
• TextArea: A multi-line text box used for freeform data. This control has no additional attributes.
• Checkbox: A checkbox used to indicate a Boolean state. The checked attribute is a Boolean attribute used to indicate the initial state of the control, checked or unchecked.

Back to top

Creating the "Hello World" token module

Now that we know what it takes to write a custom token module, we’ll create a token module that issues and validates "HelloWorld" tokens. The next few sections guide you through writing, deploying, and testing this module.

Import the sample project

In the Resources section of this article, you'll find a JAR file containing the sample code for this project. We used Eclipse to develop the sample custom module, so the sample code will import directly into Eclipse. Import the code by choosing File>, Import...>, Archive File and locating the JAR file you've downloaded from this page. Then, follow the instructions in the README in order to prepare your environment.

Implement the STSModule interface

All token modules must implement the STSModule interface. Notice in the class com.ibm.itfim.examples.sts.modules.STSHelloWorldModule the following block of code that determines what to do based on a request from the trust service. The invoke(...) method is called for each invocation of a module instance, and the mode, request, and response are provided to the module. In our sample, the module determines if the mode is ISSUE or VALIDATE, and calls the appropriate helper method based on the mode. All invocations are required to return a Boolean status; true indicates that the module invocation was successful, while false indicates an error occurred. If a module returns false or throws an STSModuleException, chain processing is halted, and the trust server returns an error.

You may wish to use a logging facility to output information as chain processing occurs. We recommend that you use the logging facilities integrated with the WebSphere Application Server. These logging facilities allow for fine-grained control over logging levels and log entries that are integrated with the application server's logs. See the Resources section for a link to the WebSphere Application Server InfoCenter topic on logging.

				 
   /** At configuration time a mode is set in the STS chain for the instance
    * of the module. The mode is used to switch functionality behavior of the 
    * invoke() method for the module; essentially overloading the 
    * invoke() method. An example is to have the same module do validate and issue. 
    */
    public boolean invoke(STSMode mode, STSRequest req, STSResponse resp) 
		throws STSModuleException
	{        
        System.out.println(STSHelloWorldModule.class.getName() + " invoke() called.");
        System.out.println(STSHelloWorldModule.class.getName() + " mode: " +
            mode.getText());
            
            boolean status = true;
            
            if (mode == STSMode.ISSUE) { 
                status = issue(mode, req, resp);  
            } else if (mode == STSMode.VALIDATE) { 
                status = validate(mode, req, resp);                        
            } 
            
        return status; 
    }
            

Provide a user interface

If necessary, a custom module can provide a user interface that will be included in the Federated Identity Manager Console. This user interface allows for the collection of configuration options. Each configuration option is stored alongside the module chain configuration in the Federated Identity Manager configuration files. The schema presented above shows the format of the GUI specification.

The code listing below shows a GUI for the issue and validate modes. The panel contains two text fields and a checkbox. Note that the bold text shows how to internationalize a component. The GUIXML in the listing produces a panel that looks like the panel below.

				
<Parameters>
<Parameter name="HelloModule.GUIXML">
    <Value>< ![CDATA[
    <Page xmlns="urn:ibm:names:ITFIM:GUIXML:1.0">
        <PageInfo>
            <!-- PageTitle elements MUST use resource bundles -->
            <PageTitle 
                titleKey="TITLE"
                titleDescriptionKey="TITLE_DESC"
                resourceBundleClass=
                  "com.ibm.itfim.examples.sts.modules.STSHelloWorldResourceBundle"
            />
        </PageInfo>            
        <PageLayouts>
            <PageLayout configType="init">
                <TextField name="example.config.item.1" required="true" 
                    modes="issue,validate"
                    defaultValue="" valueType="string">
                    
                  <ComponentLabel 
                     resourceBundleClass=
                       "com.ibm.itfim.examples.sts.modules\
                         .STSHelloWorldResourceBundle"
                     resourceBundleKey="TEXT_FIELD_LABEL_1"
                     fdaTitleKey="TEXT_FIELD_LABEL_1" 
                     fdaTextKey="TEXT_FIELD_LABEL_1"
                     textLabel="Text field 1" />

                </TextField>
                <TextField name="example.config.item.2" required="true" 
                        modes="issue,validate"
                        defaultValue="" valueType="string">
                     <ComponentLabel textLabel="Text field 2" />
                </TextField>
                <CheckBox name="example.config.checkbox" required="true"
                     checked="true" modes="issue,validate">
                     <ComponentLabel textLabel="Check box 1" />
                </CheckBox>                        
            </PageLayout>
        </PageLayouts>
    </Page>
    ]] ></Value>
</Parameter>
</Parameters>

Back to top

Deploying the module

Now that we've stepped through the code provided in the sample, use the following steps to deploy a token module. This process consists of packaging the module, copying it to the server, deploying the module, and configuring the module.

Packaging the module

As mentioned earlier, all modules must be packaged in a specific manner so that Federated Identity Manager can properly load them. You must perform the following steps in order to properly package a module:

• Provide a JAR file of the module's implementation. The JAR file must follow the same format as a traditional Java library. The JAR file will be placed in the plugins directory within the Federated Identity Manager server's installation directory for future deployment to the server.
• Provide an XML descriptor of the module's behavior, including the GUIXML. The file must be called module.xml and be located in the same location as the module's JAR file. See the section The module.xml File for details on the contents of this file.
• If the GUIXML for your module contains internationalized resources, the resource bundle must be made available to the Management Console environment. Place the resource bundle in the following location ($ISC_HOME refers to the installation directory of the Management Console; on UNIX® systems the default is /opt/IBM/ISC, on MicroSoft® Windows® systems the default is c:\Program Files\IBM\ISC). After copying the resource bundle, restart the Management Console.

  $ISC_HOME/PortalServer/installedApps/itfim-fimconsole*/PA*/WEB-INF/lib

  Note that the * above refers to a variable portion of the path that differs per installation.

The module.xml file

Each custom module must supply a descriptor file named module.xml. The file describes the module's user interface and some information about which class contains the module implementation. The listing below shows the contents of the module.xml file.

• The Module element describes metadata about the module. It must have a unique ID and version number.
• The Description element is used to explain text and can be internationalized.
• The Features element is used to describe the features provided by this module. STSModule is required, so the block shown in the example listing should be copied and pasted into your moudule.xml file.
• The DependencySet element is used to ensure that module dependencies are met. Most modules have no dependencies, so it's usually left blank.
• The ExposedClasses element lists all the classes provided that implement the STSModule interface. Each ExposedClass element provides a unique id for the given class name.
• The Parameters element stores the GUIXML for the module. Notice that the enclosed element specifies that GUIXML is a parameter for the module.

				
<Module id="com.tivoli.am.fim.sts.hello" 
        version="1.0" 
        xmlns="urn:ibm:names:ITFIM:1.0:module">
   <Description msgKey="">
       The Hello World Module.
   </Description>

   <Features>
       <Feature>STSModule</Feature> 
   </Features>

   <DependencySet />

   <ExposedClasses>
       <ExposedClass id="HelloModule" 
           className="com.ibm.itfim.examples.sts.modules.STSHelloWorldModule" />
   </ExposedClasses>

   <Parameters>
       <Parameter name="HelloModule.GUIXML">
       		GUIXML goes here!
       </Parameter>
   </Parameters>
</Module>

Update the server with the new module

Package the module's class files into a JAR file, and copy the JAR file and the corresponding module.xml file to new directory named $FIM_HOME/plugins/com.tivoli.am.fim.sts.hello_1.0 ($FIM_HOME corresponds to /opt/IBM/FIM on UNIX platforms and C:\Program Files\IBM\FIM on Windows). If you installed the product as the root or administrative user, you will need to use the same account for this step.

In order to deploy the module to a live environment, Federated Identity Manager must be made aware of the new module. The file $FIM_HOME/pkg/software.properties contains metadata about the installed components, and whether an update to the live environment is required. Specifically, the property com.tivoli.am.fim.rte.software.serialId tells the Management Console which version of the Runtime is installed. In order to make sure your custom module is properly deployed, simply increment the value of this property. The following listing shows the property bolded.

				
    #
    #Mon Jul 18 12:45:30 CDT 2005
    com.tivoli.am.fim.rte.earPropertiesLocation=release/itfim_ear.properties
    com.tivoli.am.fim.rte.publishDirs=plugins:pages
    com.tivoli.am.fim.rte.software.displayName=6.0.1 [2005-07-17T23:01:44Z]
    com.tivoli.am.fim.rte.software.serialId=1121708730358
    com.tivoli.am.fim.rte.installedAt=2005-07-18T17:45:30Z
            

Configuring the custom module

Once you've updated the software.properties file, the Runtime Nodes page of the Console will notify you that an update is available. Use the Console to deploy the updated Runtime; this will automatically publish your custom module to the live environment.

In order to use the module, you must inform the console of your new module's existence, and then configure the module.

To add the module, perform the following steps:

1. In the Management Console, Go to Service Management>Trust Service>Modules>Create
2. Enter the following information in the fields:
   • Module Name, should match the id attribute in the Module element from module.xml.
     Enter com.tivoli.am.fim.sts.hello
   • Module Version Number, should match the version attribute in the Module element from module.xml.
     Enter 1.0
   • Exposed Class ID, should match the id attribute in the ExposedClass element from module.xml.
     Enter com.ibm.itfim.examples.sts.modules.STSHelloWorldModule
3. Click Finish to submit the form.

Using the Module Instances section of the Management Console, create an instance of the Hello World module. Call the instance HelloWorldModuleInstance. The values for the token-specific configuration can be anything you want. If you need assistance, see the demonstration on how to configure the module instance..

When an instance of the custom token module exists, the instance must be added to a module chain so that the trust server will know to associate incoming requests with the custom token module. Use the Module Chains task in the Management Console to create two chains with the custom token module as the only member: one that validates tokens, and one that issues tokens. Use the following information to configure each chain. Be sure to restart WebSphere Application Server after the module chains are created.

Chain 1, validate

• Module Chain Name: chain1
• Issuer Address: http://issuer/1
• AppliesTo Address: http://appliesto/1
• Add the module instance HelloWorldModuleInstance to the chain in validate mode.

Chain 2, issue

• Module Chain Name: chain2
• Issuer Address: http://issuer/2
• AppliesTo Address: http://appliesto/2
• Add the module instance HelloWorldModuleInstance to the chain in issue mode.

Back to top

Testing the module

Now that the module instance exists and chains have been created, the trust server is ready to process requests associated with the custom token module. This section explains how to test the token module. Included with this article's Eclipse project is a test client, which will send requests to validate and issue tokens to the trust server. Since the client performs a series of web service operations, the best way to see what’s going on is to use a TCP monitor, like TCPMON that comes with Axis.

Open Eclipse and ensure that your environment is configured as specified by the README that comes with the project. Then, open the file com.ibm.itfim.examples.sts.client.STSHelloWorldModuleTestClient.java and edit the variables found at the top of the main(...) method.

Run the class from within Eclipse. If you have a TCP Monitor running, you will see the request and response from the server. See a sample request (Listing 7) and a sample response (Listing 8). The RequestSecurityToken and RequestSecurityTokenResponse elements are bolded.

Back to top

Conclusion

Federated Identity Manager allows an enterprise to exchange identity information in a more secure manner with other enterprises, or even silos within the same enterprise. A key requirement of communicating identity information is the ability to transform identity information between multiple formats. While Federated Identity Manager provides this ability for a number of token formats, many enterprises use custom token formats not supported by the product.

Federated Identity Manager allows developers to create token modules that extend the ability of the product's token support. Developers can create modules that issue and validate tokens of a new format and even manipulate identity information to ensure that it is in the correct format. Custom token modules are deeply integrated with the product -- developers specify user interfaces for configuration parameters and package all of that as a module for deployment with the Federated Identity Manager Runtime.

This article describes the process of creating a custom token module that can be plugged into Federated Identity Manager. We discussed developing, deploying, and testing the module, given an example module provided as a resource. With the tools provided by this article, you can extend Federated Identity Manager to manipulate incoming and outgoing identity information as required by your infrastructure.

Back to top

Download

Information about download methods

Resources

Learn

• A Viewlet showing how to create a module instance.
  
  
• The tcpmon tool used for testing trust server operation.
  
  
• The WS-Trust Specification at DeveloperWorks
  
  
• Tivoli Federated Identity Manager InfoCenter
  
  
• WebSphere InfoCenter topic on logging in WebSphere applications
  
  
• Tivoli Federated Identity Manager Product Page
  
  

Get products and technologies

• Download a free trial version of WebSphere Application Server Version 6.0.
  
  
• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

About the authors

Eric is a developer on the Tivoli Federated Identity Manager team. He holds a Bachelor and Master of Science in Computer Science from Cal Poly, San Luis Obispo, California.

Patrick Wardrop is a developer on the Tivoli Federated Identity Manager team. He holds a Bachelor of Arts in Computer Information Science from the University of Guelph, Guelph, Ontario, Canada.

Rate this article

Comments

Back to top

Table of contents

• The security token service
• Creating the "Hello World" token module
• Deploying the module
• Testing the module
• Conclusion
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Tivoli on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers