Remote client configuration

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

Prerequisites:

Java™ 7.0.4 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 IBM Security Directory Integrator installation.
2. If custom non-IBM Security Directory Integrator 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 IBM Security Directory Integrator 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 IBM Security Directory Integrator 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 IBM Security Directory Integrator. Note that it contains both the client private key and also the public key of the IBM Security Directory Integrator 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