Configuring the Server API

Configuring the Server API on the Server side includes specifying the relevant system properties in global.properties (or solution.properties) and configuring the User Registry file.

Configuring the Server API properties

The Server API engine is configured through a set of properties in the global.properties file (or solution.properties file, if a solution folder is used). Refer to the chapter on Security and TDI, section "Server API Access Security" in the IBM Tivoli Directory Integrator V7.1.1 Installation and Administrator Guide for information on how to configure the Server API.

Setting up the User Registry

Refer to the "Security and TDI" chapter in the IBM Tivoli Directory Integrator V7.1.1 Installation and Administrator Guide for information and examples of how to setup the User Registry, assign user roles and encrypt or decrypt the User Registry file.

Remote client configuration

This section describes what is necessary for a remote client that will use the remote Server API.

Prerequisites:

Java 6 or higher is required on the client side.

Configuring the client:

1. The following jar files must be included in the CLASSPATH of the remote side:
   • jars/common/diserverapi.jar
   • jars/common/diserverapirmi.jar
   • jars/3rdparty/others/log4j-1.2.15.jar
   • jars/common/miconfig.jar
   • jars/common/miserver.jar
   • jars/common/mmconfig.jar
   • jars/common/tdiresource.jar
   • jars/3rdparty/IBM/icu4j_4_2.jar
   • jars/3rdparty/IBM/ITLMToolkit.jar
   • jars/3rdparty/IBM/jlog.jar
   You can copy these jar files from the Tivoli® Directory Integrator installation.
2. If custom non-TDI objects are used in the solution being implemented with the Server API (for example as Attribute values of an Entry that is transferred over the wire) the corresponding Java classes have to be available on the client side as well. These classes must be serializable and they have to be included in the CLASSPATH of the client JVM.

SSL configuration of the remote client

There are two options for configuring SSL on the remote client:

Using Server API specific SSL properties

When the Java System property api.client.ssl.custom.properties.on is set to true, then SSL is configured through the following TDI Server API-specific Java System properties:

• api.client.keystore - specifies the keystore file containing the client certificate
• api.client.keystore.pass - specifies the password of the keystore file specified by api.client.keystore
• api.client.keystore.type - specifies the type of the keystore file specified by api.client.keystore; optional property, if not specified the default keystore format for the JVM will be used
• api.client.key.pass - the password of the private key stored in keystore file specified by api.client.keystore; if this property is missing, the password specified by api.client.keystore.pass is used instead.
• api.client.truststore - specifies the keystore file containing the TDI Server public certificate.
• api.client.truststore.pass - specifies the password for the keystore file specified by api.truststore.
• api.client.truststore.type - specifies the type of the keystore file specified by api.client.truststore; optional property, if not specified the default keystore format for the JVM will be used

Using the Server API-specific SSL properties is convenient when your client application is using the standard Java SSL properties for configuration of another SSL channel used by the same application.

You can specify these properties as JVM arguments on the command line, for example:

java MyTDIServerAPIClientApp 
    -Dapi.client.ssl.custom.properties.on=true 
    -Dapi.client.truststore=C:\TDI\serverapi\testadmin.jks 
    -Dapi.client.truststore.pass=administrator 
    -Dapi.client.keystore=C:\TDI\serverapi\testadmin.jks
    -Dapi.client.keystore.pass=administrator

This example refers to the sample testadmin.jks keystore file shipped with Tivoli Directory Integrator. Note that it contains both the client private key and also the public key of the TDI Server, so it is used as both as a keystore and truststore.

Using the standard SSL Java System properties:

When the Java System property api.client.ssl.custom.properties.on is missing or when it is set to false, then the standard JSSE system properties are used for configuring the SSL channel. Follow the standard JSSE procedure for configuring the keystore and truststore used by the client application.

You can specify these properties as JVM arguments on the command line; for example:

java MyTDIServerAPIClientApp 
-Djavax.net.ssl.keyStore=C:\TDI\serverapi\testadmin.jks 
-Djavax.net.ssl.keyStorePassword=administrator 
-Djavax.net.ssl.trustStore=C:\TDI\serverapi\testadmin.jks 
-Djavax.net.ssl.trustStorePassword=administrator