Skip to main content

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

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

All information submitted is secure.

  • Close [x]

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.

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

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

Developing a custom Java module

Tivoli Federated Identity Manager 6.2

Shane B. Weeden, Senior Software Engineer, IBM Tivoli
Shane Weeden
Shane Weeden is a senior software engineer with the IBM Tivoli Federated Identity Manager development team. He has worked in IT security since 1992, and since 2000 has been working with Tivoli Security products including Tivoli Access Manager for eBusiness and Tivoli Federated Identity Manager. Shane now divides his time between customer focused engagements and core product development activities. He holds a Bachelor of Information Technology from the University of Queensland in Australia.
(An IBM developerWorks Professional Author)
Ann-Louise Blair (, Software Engineer, IBM Tivoli
Ann-Louise Blair is a Software Engineer in the IBM Australia Development Laboratory. She has four years experience working in the IT industry and holds a Bachelor of Software Engineering degree from the University of Queensland. Having worked in both testing and development roles in the Gold Coast Integration Factory team, Ann-Louise has gained expertise working with many Tivoli software products.
Simon Chen (, Staff Software Engineer, IBM Tivoli
Simon Chen
Jiayue (Simon) Chen was going to devote his career to building robots until he realized that sniffing fumes from a soldering iron could cause more harm than good. So instead, he's now working as a staff software engineer with the Tivoli Federated Identity Manager development team, where the radiation from the computers in his office keeps him warm. Simon graduated from Georgia Tech with an B.S. in Electrical Engineering and has been with IBM full-time since 2006. His technical interests include Eclipse and OSGi.

Summary:  In this tutorial, we will walk through the complete development process for creating a custom trust service (aka Security Token Service or STS) plug-in for Tivoli® Federated Identity Manager (TFIM) 6.2. Customers might develop their own plug-ins for a variety of reasons including advanced user mapping and attribute gathering capabilities, or to support validation and issuing proprietary security token types. This tutorial will use as a working example a simple mapping module which adds a configurable name/value parameter pair as an attribute to the TFIM Trust Service's STSUniversalUser. For those readers familiar with developing STS modules for previous versions of TFIM (see Developing Custom STS Modules), the development interfaces are largely unchanged; however, the packaging and deployment is different as TFIM 6.2 has now moved to an Open Services Gateway Initiative (OSGi) plug-in framework for extensions. This OSGi plug-in framework is used for developing a variety of supported extension points in TFIM, including the STSModule extension point which is the focus of this tutorial.

Date:  12 Sep 2008
Level:  Advanced


GUIXML widgets reference

Available GUI XML Widgets and their Configuration

When designing a new page layout using GUI XML, (as was done earlier in this tutorial as part of "Developing the Custom Module"), there are a number of available widgets. For the purposes of the GUI design for our demo module, only TextFields with their associated labels were required (refer back to Figure 22).
This section describes all the available widgets and their configuration when developing custom Java™ modules.

There are 8 widget types available for use in a Page Layout, as shown in Figure 63 below.

Figure 63. Available GUI Elements
GUIXML Widgets

Following is a table showing the various widgets and their configuration properties. There are some commonalities among the widgets. For example:

  • name - The name is always required, and represents the name of the configuration parameter. This is the same name that you use to retrieve the parameter value in your module code. See example in Listing 2.
  • required - I bet you can figure this one out.
  • modes - This acts as a filter, and is a comma-separated listed of STS module modes that the module may operate in and use this parameter. The set of modes we are talking about is the set of operational modes that the module can be configured in when added to a module chain (i.e. validate,map,issue,exchange,other,authenticate,authorize). The console will only prompt for the parameter when the module is configured in a listed mode. For example it makes no sense to prompt for a "signature validation key" for a module that is in issue mode. Similarly it doesn't make sense to prompt for a "signing key" for a module in validate mode. The console only prompts for the parameters required for the mode the module is operating in.

Non-obvious properties for the widgets are described in detail in the table.

Widget TypeDescriptionConfigurable PropertiesConfiguration Notes
TextFieldText input box that allows users to enter text on a single*
required* {true|false}
multivalued {true|false}
password {true|false}
issuerField {true|false}
The valueType for a text field is not currently used, but the intent is to eventually use it for validating entry. For now we recommend you set it to string (this is what the internal modules use), and perform your own validation of the input at runtime.
The multivalued attribute allows a TextField to behave like a TextArea. This is historical, and we now recommend using a TextArea where multiple lines of input are desired.
The password attribute determines if the characters on the display are replaced with *. There are two main differences between using this and a PasswordField widget. First, the value is stored in plaintext when using a TextField, but obscured when using a PasswordField. Second, the PasswordField provides a secondary "re-enter password" field for validation, whereas TextField does not.
The displayWidth attribute is an integer that controls the default width of the input string. The default is 60 and is suitable for most purposes.
The displayValue attribute allows you to pre-populate the text field with a default value.
The issuerField attribute is a special attribute that is used internally by TFIM to occasionally hide a text field attribute from the display when collecting parameter information in wizards. For example the issuer attribute for generating SAML assertions is generally defaulted to the Identity Provider ID, and for simplifying the amount of data collected it is not prompted for during wizard federation creation. It is not recommended that you use this field for your own token modules.
TextAreaText input area that allows the user to enter large amounts of text across multiple*
required* {true|false}
This is a multi-line text entry field. You can distinguish the lines in your code by looking at the String[] returned by STSGroupMembership.getSelfProperties or STSGroupMembership.getPartnerProperties
CheckBoxA check box (tick box) that represents an option to the user. The user is permitted to make multiple selections from a number of*
required* {true|false}
checked* {true|false}
The checked attribute determines if the checkbox is pre-selected as checked.
KeyIdentifierInputAllows the user to enter a key identifier. A key identifier represents a public or private key, and consists of a keystore, plus the label of the key within that*
required* {true|false}
checked* {true|false}
This complex widget consists of a set of components which allow you to pick a key. It looks something like this:
KeyIdentifier Widget

The enabledName attribute describes an optional configuration parameter name. If provided, the widget will display a checkbox to describe if the function associated with this key is enabled. If no enabledName value is provided, a key is to always be prompted for. If a value is provided, a checkbox will appear (like the example above which has the label "Really need a key?"). When the checkbox is selected, the entire rest of the key widget is enabled, when it is not selected, the rest of the key widget is disabled. The tricky part here is providing a label for the checkbox. This is done by adding a ComponentLabel under the KeyIdentifierInput and setting the for: attribute of the ComponentLabel to checkbox, as shown here:
KeyIdentifier Checkbox Label

Note that this ComponentLabel is in addition to the one which describes the label for the key identifier widget itself (defined as "My KeyID" above). To define the ComponentLabel for the actual key identifier widget, set the for: attribute of the ComponentLabel to keyidentifier, or just leave it blank.

The first element in the main portion of the key widget (labeled Keystore) is a drop-down list box of keystore names. This will be filtered based on the type of keys selected in the keyTypes parameter.
The keyTypes parameter is a comma-separated list of one or more of the following values:
  • public - a public key, such as is typically used for XML encryption or signature validation
  • keypair - a private/public key pair such as is typically used for XML decryption or signature generation
  • symmetric - a symmetric key (e.g. DES)

The second element in the main portion of the key widget is for the Keystore Password, which is the password used to open the keystore you have selected.

The third element in the main portion of the key widget is the List Keys button, and the table which shows all the listed keys. The List Keys button should only be pressed after the password is entered, and the keys will only be listed if the password is correct. Each of the keys in the keystore which match the keyTypes filter will be shown.

The last part of the main portion of the key widget is actually a variable set of drop-down list boxes which permit you to select which portions of the key are included in the KeyInfo element of digital signatures. Of course in your own module, this will not have the same semantics as what you use the key for is completely up to your own code. Therefore unless you have specific requirements for allowing a user to select these elements, you probably will not need to use them in your own modules. For completeness of documentation though, you can optionally decide whether or not to prompt for any of the following:
  • The public key
  • The X509 certificate data
  • The X509 subject name
  • The X509 subject key identifier
  • The X509 issuer details

For each attribute you will be prompted for one of the following values:
  • Use the default (which equates to unset)
  • Yes (which equates to a value of true)
  • No (which equates to a value of false)
In our example above you will see we only added prompts for two of the four variable portions (for demonstration purposes).

The checked attribute controls whether or not the main portion widget is enabled, and basically pre-checks the optional parameter defined by the checkedName attribute for enabling or disabling key selection. It doesn't make sense to set this attribute to false unless you are definitely including the enabledName attribute and want it to be disabled by default. A good example where TFIM uses this combination internally is enabling signatures for the TAM Credential module.

The only other attribute not yet mentioned is validateUseKeyInfoName. This is an advanced configuration parameter we do not recommend using in your own modules (leave it blank). This parameter again represents an optional configuration parameter name, which if provided, causes the key widget to prompt for an additional key selection options (not shown in our example) via a radio button group at the very top of the main part of the widget. The radio buttons allow you to select whether or not a key to be used for signature validation should come from the KeyInfo inside an XMLSignature element itself, or from a user-selected key from the widget (as shown in our example). If signature validation is done from KeyInfo information, then no key is selected from a keystore, and instead we prompt for an optional subject DN expression for allowable X509 certificates. The semantics of this property are very particular to TFIM internal API options for signature validation, and it is more likely that for your own module you would use a combination of other widgets to prompt for these style of options rather than this particular attribute of KeyIdentifierInput.
ComboBoxA drop down list box containing a list of existing options that can be selected*
required* {true|false}
editable {true|false}
The editable attribute describes whether or not the user can put in their own text rather than selecting one of the built-in options. The widget allows you to add an Options element, and to this you add one or more child Option elements. Each Option has a display label and value.
TDIModuleInput*For internal use only as part of the TDI mapping*
required* {true|false}
Do not use this widget in your own modules.
PasswordFieldA pair of text input fields where the entered characters will be obfuscated so that they do not appear on the screen in clear*
required* {true|false}
The displayWidth has the same meaning as for a TextField widget.

The widget will automatically prompt for the same value twice, and will validate that the input is the same for both entry fields. It will also automatically obfuscate the resulting value before storing it in configuration. When reading a password from configuration in your module code, it is necessary to call the with the value of the parameter to access the cleartext password.
RadioButtonGroupA radio button (option button) allows the user to choose one of a predefined set of*
required* {true|false}
A RadioButtons element is added to a RadioButtonGroup, and under that an ordered list of RadioButton elements are added to build the list of options. Each RadioButton has both a label and a value (as would be expected). The ordered list is zero-indexed, so setting the defaultButtonIndex to 0 will pre-select the first radio button.

NOTE: * indicates a required field.

10 of 14 | Previous | Next


Zone=Tivoli (service management), Tivoli, Java technology, Security
TutorialTitle=Developing a custom Java module