Tivoli Access Manager (TAM) Connector

Introduction

The IBM® Tivoli® Directory Integrator 7.1.1 Connector for Tivoli Access Manager enables the provisioning and management of Tivoli Access Manager User accounts, Groups, Policies, Domains, SSO Resources, SSO Resource Groups, and SSO User Credentials to external applications (with respect to Tivoli Access Manager). The Connector uses the Tivoli Access Manager Java API.

The key features and benefits of the Connector are:

• Support for Create, Read, Update, and Delete operations for Tivoli Access Manager User accounts, Groups, Policies, Domains, SSO Resources, SSO Resource Groups, and SSO User Credentials.

SSL communication with the TAM Server is supported.

Connector Modes

The Connector supports the Lookup, Iterator, Update, AddOnly, and Delete modes. Refer to Using the Connector for specific usage of the various modes.

Skip Lookup in Update and Delete mode

The TAM Connector supports the Skip Lookup general option in Update or Delete mode. When it is selected, no search is performed prior to actual update and delete operations.

Valid Link Criteria must be present, that is, the mandatory attribute must be defined in the Link Criteria of the Connector, as defined in the tables of mandatory attributes under the Update Mode and Delete Mode sections respectively.

Configuration

Before attempting to use the connector in an AssemblyLine, Tivoli Access Manager version 6.x must be installed on the target machine: The Tivoli Access Manager Java Runtime Environment (JRTE) must also be installed on the same machine as Tivoli Directory Integrator.

Configuring the Tivoli Access Manager Java Run Time

The Connector makes use of the Tivoli Access Manager Java API and therefore the Tivoli Access Manager Runtime for Java must be installed on the Tivoli Directory Integrator machine. For information on how to install and configure Tivoli Access Manager Runtime for Java on the Tivoli Directory Integrator machine, refer to the Tivoli Access Manager Installation Guide.

When entering the parameters to the configuration utility (pdjrtecfg):

• Check that both the policy server and registry server are running.
• Ensure that Tivoli Directory Integrator is not running.
• Make sure that Tivoli Directory Integrator's JVM is in your path, for example with the following command (on UNIX/Linux):

  export PATH=/opt/IBM/TDI/V7.1.1/jvm/jre/bin:$PATH

• Specify the location of the Tivoli Directory Integrator JRE directory. For example, on a Linux machine the default Tivoli Directory Integrator JVM directory is:

  /opt/IBM/TDI/V7.1.1/jvm/jre

• Specify a configuration type of Full. For example, from the Policy_Director/sbin directory, enter the following command (as one line):

  pdjrtecfg -action config -host TAM_host_name -port 7135 
  		-java_home "/opt/IBM/TDI/V7.1.1/jvm/jre" -config_type full

  where TAM_hostname is the name of the host where Tivoli Access Manager Policy Server is installed. You should get the message "Configuration of Access Manager Runtime for Java is in progress". This might take several minutes. After completion, you should get the message "Configuration of Access Manager Runtime for Java completed successfully".

Configuring secure communication to the Tivoli Access Manager policy server

To configure secure communication between Tivoli Directory Integrator and Tivoli Access Manager policy server and authorization server, and for Tivoli Directory Integrator to become an authorized Tivoli Access Manager Java application, run the SvrSslCfg utility on the Tivoli Directory Integrator machine.

For example, from the TDI_install_dir/jvm/jre/bin directory, enter the following command (as one line). This command must be run with the Tivoli Directory Integrator's Java executable:

/opt/IBM/TDI/V7.1.1/jvm/jre/bin/java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id sec_master
		-admin_pwd password -appsvr_id appsvr -host TAM_host_name -mode remote -port 999
		-policysvr policy_svr:7135:1 -authzsvr auth_svr:7136:1 -cfg_file cfg_file_name 
		-key_file keyfile_name -cfg_action create

For complete information on the SvrSslCfg utility, refer to the Tivoli Access Manager Authorization Java Classes Developer Reference (specifically Appendix A).

Configuring SSL

The following steps allow you to optionally create a new self-signed certificate, and configure Tivoli Directory Integrator to use the certificate:

1. Open the IBM Tivoli Directory Integrator Configuration Editor.
2. Select KeyManager from the Toolbar. The IBM Key Manager tool opens.
3. Select Key Database File then New.
4. Select "JKS" as the Key database type.
5. Enter an appropriate File Name and an appropriate Location. Click OK.
6. Enter a Password. Enter the password again to confirm. Click OK.
7. In the Key database content section, select Personal Certificates. Click New Self-Signed.
   Note:

   Alternatively, an existing certificate can be used. If you wish to do this, click Export/Import to import the appropriate certificate.
8. Enter an appropriate Key Label, an appropriate Organization, and any other appropriate information. Click OK.
9. Close IBM Key Manager.
10. In the Tivoli Directory Integrator Configuration Editor, select Browse Server Stores then click on Open for the Server Store you wish to configure, usually Default.tdiserver. Double-click Solution-Properties, and the solution properties table is opened.
11. Locate the javax.net.ssl.trustStore parameter. Enter the value of Key database File created in step 5 above.
12. Locate the javax.net.ssl.trustStorePassword parameter. Enter the value of the Password entered in step 6 above.
13. Locate the javax.net.ssl.trustStoreType parameter. Enter "jks".
14. Locate the javax.net.ssl.keyStore parameter. Enter the value of Key database File created in step 5 above.
15. Locate the javax.net.ssl.keyStorePassword parameter. Enter the value of the Password entered in step 6 above.
16. Locate the javax.net.ssl.keyStoreType parameter. Enter "jks".
17. Click Close to close the solution properties table. The changes to the solution properties are saved in the relevant solution.properties file.
18. Close Tivoli Directory Integrator Configuration Editor.

Refer to IBM Tivoli Directory Integrator V7.1.1 Installation and Administrator Guide for more information on configuring SSL.

Configuring the Connector

The Tivoli Directory Integrator Connector for Tivoli Access Manager can be added directly into an assembly line. The following section lists the configuration parameters that are available.

TAM ID

The Connector attempts to log on to Tivoli Access Manager with this user name and the password specified by the Password parameter. Default value: sec_master

TAM Password

The value of this parameter is taken in account only when the parameter TAM ID is set to a non-blank value. It then specifies the password used for the logon operation. The default value is blank.

Domain

Specifies the TAM Domain. The default is "Default". Pressing the "Domains" button next to this parameter queries the TAM Server for a list of Domains, from which you can select the appropriate one. The Connector attempts to log on to Tivoli Access Manager with the TAM ID and TAM Password parameters.

TAM Program Name

The name used by Tivoli Access Manager to identify this Connector. Default value: IDI

TAM Configuration File

File pathname for the Tivoli Access Manager configuration file created by the SvrSslCfg configuration utility.

Entry Type

Must be set to one of the following values:

• User (specifying that the Connector operates with data structured by Tivoli Access Manager Users),
• Group (specifying that the Connector operates with data structured by Tivoli Access Manager Groups),
• Policy (specifying that the Connector operates with data structured by Tivoli Access Manager User Policies),
• Domain (specifying that the Connector operates with data structured by Tivoli Access Manager Domains),
• SSOCred (specifying that the Connector operates with data structured by Tivoli Access Manager SSO Credentials),
• SSOResource (specifying that the Connector operates with data structured by Tivoli Access Manager SSO Resources),
• SSResourceGroup (specifying that the Connector operates with data structured by Tivoli Access Manager SSO Resource Groups).

Filter users/groups

An optional connector attribute that defines a filter string used to select "User" or "Group" object types. The parameter is only used in Iterator mode with one of those two Entry Types. By default, this attribute is empty, which implies no filtering.

Import Users/Groups from Registry

When checked, Tivoli Access Manager will import users/groups from the User Registry instead of creating users in the User Registry during an add operation. In Update mode, users/groups will be imported through the add operation only, and not through the modify operation.

Delete Users/Groups/Domains from Registry

When checked, Tivoli Access Manager will delete users/groups/domains from the User Registry during a delete operation. The UserName, RegistryUID, Firstname and Lastname attributes are mandatory for this operation to find the correct LDAP registry user name of the TAM account to import.

In Update mode, users/groups will be imported through the add operation only, and not through the modify operation.

Detailed Log

If this field is checked, additional debug log messages are generated.

Using the Connector

This section describes how to use the Connector in each of the supported IBM Tivoli Directory Integrator Connector modes. The section also describes the Tivoli Directory Integrator Entry schema supported by the Connector.

When the Connector is configured to manipulate TAM Policy objects, special consideration is required when supply attribute values in the work entry that will feed the Connector in AddOnly or Update Modes. The policy object attributes are grouped together for related policy items. The attributes can be broken up into sets where each set of attributes requires a value to update or apply any of the individual attributes for that policy item. For example, when manipuilating the Policy item Account Expiry Date, you must supply values for each of the attributes AcctExpDateEnforced, AcctExpDateUnlimited, and AcctExpDate. If you wish to then modify any of these attributes for Account Expiry Date, you must again also supply values for each of the three attributes and the UserName attribute.

The following table defines the Policy items and their attribute groupings.

AddOnly Mode

When deployed in AddOnly mode, the Connector is able to create a range of data in the Tivoli Access Manager database. The Connector should be added to the Flow section of a Tivoli Directory Integrator AssemblyLine. The Output Map must define a mapping for the following attributes, these attributes can be also be retrieved through querying the Connector Schema.

The Connector does not support duplicate or multiple entries. Only one entry should be supplied to the Connector at a time.

Update Mode

When deployed in Update mode, the Connector is able to modify existing data in the Tivoli Access Manager database. The Connector should be added to the Flow section of a Tivoli Directory Integrator AssemblyLine. The Output Map must define a mapping for the following attributes. These attributes can be also be retrieved through querying the Connector Schema.

When importing users/groups during an update:

• The Tivoli Access Manager account can only be imported from the registry if the account does not already exist in Tivoli Access Manager.
• When the ReplaceUsersOnUpdate or ReplaceroupsOnUpdate flags (see Connector Input Attribute Details) are set to 'true', the user will be added as a member of the group, but an exception will be thrown if the user is already a member.
• The description attribute is the only attribute that will undergo an update during an import. No other Tivoli Access Manager attributes imported from the registry will be modified.

Keep in mind the caveats on manipulating Policy items and their required Policy Entry attributes as stipulated in Table 21.

Attributes marked with an asterisk (*) are mandatory.

Additionally, any mandatory fields mentioned above should be defined in the Link Criteria of the Connector. The Link Criteria is required by the AssemblyLine, since the AssemblyLine will invoke the Connectors findEntry() method to verify the existence of the given user. The value of the attribute, as defined in the Link Criteria, must match the value of the element present in the Output Map.

The only operator supported for Link Criteria is an equals exact match. Wildcard search criteria are not supported. The Connector does not support duplicate or multiple entries. Only one entry should be supplied to the Connector at a time.

Delete Mode

When deployed in Delete mode, the Connector is able to delete existing data from the Tivoli Access Manager database. The Connector should be added to the Flow section of an AssemblyLine.

Attributes marked with an asterisk (*) are mandatory.

The mandatory attribute must be defined in the Link Criteria of the Connector. The Link Criteria is required by the AssemblyLine, since the AssemblyLine will invoke the Connector's findEntry() method to verify the existence of the given user.

The only operator supported for Link Criteria is an equals exact match. Wildcard search criteria are not supported. The Connector does not support duplicate or multiple entries. Only one entry should be supplied to the Connector at a time.

Lookup Mode

When deployed in Lookup mode, the Connector is able to obtain all details of the required Tivoli Access Manager data. The Connector should be added to the Flow section of an AssemblyLine. The mandatory attribute must be defined in the Link Criteria of the Connector.

Attributes marked with an asterisk (*) are mandatory.

The Connector's findEntry() method is the main code executed. The only operator supported for Link Criteria is an equals exact match. Wildcard search criteria are not supported.

The Connector does not support duplicate or multiple entries. The Connector will return only one entry at a time.

Iterator Mode

When deployed in Iterator mode, the Connector is able to retrieve the details of each data entry in the Tivoli Access Manager database, in turn, and make those details available to the AssemblyLine.

When deployed in this mode, the Tivoli Directory Integrator AssemblyLine will first call the Connector's selectEntries() method to obtain and cache a list of all data entries in the Tivoli Access Manager database. If the entry Type is User or Group and a filter attribute was provided, then the list will contain the filtered entries. The Assembly Line will then call the Connector's getNextEntry() method. This method will maintain a pointer to the current name cached in the list.

Wildcards are supported for the filter attribute of User and Group entry types only:

• Asterisks can be used to create a UserName wildcard search pattern. The UserName pattern is interpreted as a string of characters that matches zero or more characters of the User's UserName attribute. Asterisks can be located at the beginning, in the middle or at the end of the UserName pattern, and the UserName can contain multiple asterisks.
• Asterisks can be used to create a GroupName wildcard search pattern. The GroupName pattern is interpreted as a string of characters that matches zero or more characters of the Groups's GroupName attribute. Asterisks can be located at the beginning, in the middle or at the end of the GroupName pattern, and the GroupName can contain multiple asterisks.

Troubleshooting

Problems may be experienced for any of the following reasons:

TAM Connector not installed properly

Check the configuration and re-configure if necessary.

Query Schema Issues

When performing a schema query using the Connectors with the Tivoli Directory Integrator GUI, an attempt to connect to the data source may result in an exception. These exceptions can be ignored. Any subsequent use of the Discover schema button will succeed. The Connectors do not support the Get Next Entry style of schema query. The Connectors do support the normal Tivoli Directory Integrator style of schema discovery.

Changing Mode of Connectors Already in AssemblyLine

During testing, it was observed that changing the mode of Connector in the AssemblyLine did not always work. The Connector sometimes appeared to execute in its original mode, resulting in AssemblyLine errors. If this occurs, delete the Connector and add it to the AssemblyLine in the new mode.

Connector Input Attribute Details

This section details the attributes for connector input.

User

Group

Policy

Domain

SSO Credentials

SSO Resource

SSO Resource Group

See also

Access Manager for e-business