Category Archives: ISIM

ISIM 6 API Access from a remote machine

This question appears on many sites and blogs in separate parts, but I’ve not seen a complete description yet of the whole setup. Either way – this post documents my working example of getting the ISIM API working from a remote machine.

If you’re using IDI then the setup in terms of the classpath is the same apart from needing to put the jars either in your TDI installation directory JRE folder (under 3rdparty) or as specified by in your file. The code will obviously need to be re-written in Javascript, but largely that’s just a matter of specifying methods with the full class name prefixed with “Packages.”.

I should also say that while the ISIM Web Services API is the initial client of choice it’s still a little limited so if you want to do more, then running a full remote API can be necessary. And of course if you need full beans functionality then you need to run inside the ISIM server itself to get the full API.

Anyway – back to Java an ISIM API on a remote machine.

Setup steps;

  • Download the IBM JDK for eclipse for your environment from here
  • Build a client directory – lets say that’s called C:\ISIM6_Client
  • Copy sas.client.props from the ISIM server. Use the one under <WAS_HOME> /profiles/AppSrv01/properties. Put the file into C:\ISIM6_Client\etc
  • Copy ssl.client.props from the ISIM server. Use the one under <WAS_HOME> /profiles/AppSrv01/properties. Put the file into C:\ISIM6_Client\etc
    • Edit this file and change the “user.root” at the top of the file to “C:\ISIM6_Client”
  • Copy (or create) key.p12 and trust.p12 in C:\ISIM6_Client\etc. You can copy these files from the ISIM server under <WAS_HOME>/profiles/AppSrv01/etc
    • Putting these files into C:\ISIM_Client\etc and updating ssl.client.props means that the ssl.client.props properties “” and “” will refer to them correctly.
    • These will contain the certificate of your ISIM server. If you point to a new ISIM server make sure “” is set in ssl.client.props and then you will get a certificate import prompt that you can just accept to add the certificate for the new server to your trust store.
  • Either copy from <WAS_HOME>/java/jre/lib/ into <JAVA_HOME>/lib or create one with the following contents;
# IBM JDK properties

 # WS Plugins

 # WS Interceptors

 # WS ORB &amp; Plugins properties
  • Create the JAAS login file in C:\ISIM6_Client\etc\jaas_login_was.conf that contains the following line for ISIM 6;
WSLogin { required;
  • Finally, we need the jars that will make the client. I’m using Netbeans so I just create a new Library Tools->Libraries. Click the “New Library” button and add the following jars.
    • Note that tmsMessages.jar is a jar of the tmsMessages.* files from the ISIM server.

  • Next, create a new project in Netbeans;
    • Right click the project name, chose properties. Click Libraries.
      • Add or select the IBM JDK as your Java Platform – you may need create a new platform in “Manage Platforms” that points to the IBM JDK you downloaded in the first step.
      • Under the Compile tab add the ISIM6_Client library created in the previous step
  • Now, add some code to your project. This example is all about the setup of the client so I’m not spending time on the client code in particular, but the example below should be sufficient to get you going. Note that this code is not intended to be production ready – it’s a stripped down example to show exactly what’s happening. Also, check where you need to enter your usernames and passwords below;
package isimapiclient;
import java.rmi.RemoteException;
import java.util.Hashtable;
import java.util.logging.Level;
import java.util.logging.Logger;

 public class IsimApiClient {

     public static void main(String[] args) {

         try {
            IsimApiClient client = new IsimApiClient();
            PlatformContext itimPlatform = client.getPlatform();
            Subject subject = client.getSubject();

             System.out.println("loginContext: "+itimPlatform.toString() + " - " + subject);

             DistinguishedName empDN = new DistinguishedName("erglobalid=SOMEERGLOBALID,ou=0,ou=people,erglobalid=00000000000000000000,ou=ibm,dc=com");
            PersonMO employeeMO = new PersonMO(itimPlatform, subject, empDN);
            Person emp = employeeMO.getData();
            System.out.println("Data: " + emp.getProfileName());
            System.out.println("Name: " + emp.getName());

         } catch (RemoteException ex) {
            Logger.getLogger(IsimApiClient.class.getName()).log(Level.SEVERE, null, ex);
        } catch (ApplicationException ex) {
            Logger.getLogger(IsimApiClient.class.getName()).log(Level.SEVERE, null, ex);
        } catch (LoginException ex) {
            Logger.getLogger(IsimApiClient.class.getName()).log(Level.SEVERE, null, ex);


     public PlatformContext getPlatform() {

         String hostname = "YOUR HOSTNAME";
        String port = "2809";    (Check BOOTSTRAP_ADDRESS on the ISIM server)

         System.setProperty("", "file:C:/ISIM6_Client/etc/jaas_login_was.conf");
    System.setProperty("", "file: C:/ISIM6_Client/etc/sas.client.props");
    System.setProperty("", "file: C:/ISIM6_Client/etc/ssl.client.props");
    System.setProperty("", hostname);
    System.setProperty("", port);
    String appServerURL = "corbaloc:iiop:" + hostname + ":" + port;
    String platformContextFactory = "";
    String itimRealm = "itimCustomRealm";
    String ejbUser = "isimsystem@" + itimRealm;        // Really important to include the @realm part
    String ejbPwd = "&lt;EJBPASSWORD&gt;";  (Check

         Hashtable env = new java.util.Hashtable();
    env.put(InitialPlatformContext.CONTEXT_FACTORY, platformContextFactory);
    env.put(PlatformContext.PLATFORM_URL, appServerURL);
    env.put(PlatformContext.PLATFORM_PRINCIPAL, ejbUser);
    env.put(PlatformContext.PLATFORM_CREDENTIALS, ejbPwd);
    env.put(PlatformContext.PLATFORM_REALM, itimRealm);

         PlatformContext platform = null;
        platform = new InitialPlatformContext(env);
        System.out.println("Successfully got platform context");

    catch(RemoteException e)
        System.out.println("Error Class: " + e.getClass());
        System.out.println("Error Message: " + e.getMessage());
        System.out.println("Error LocalizedMessage: " + e.getLocalizedMessage());

     } catch (ApplicationException ex) {
            Logger.getLogger(IsimApiClient.class.getName()).log(Level.SEVERE, null, ex);
        return platform;

     private Subject getSubject() throws LoginException {

             String itimPswd = "&lt;ITIM MANAGER PASSWORD&gt;";
            String itimRealm = "itimCustomRealm";
            String itimUser = "itim manager";

             // Create the JAAS CallbackHandler
            CallbackHandler handler = null;
            if (itimRealm == null) {
                    System.out.println("getSubject: Realm is NULL");
                    handler = new WSCallbackHandlerImpl(itimUser, itimPswd);
            } else {
                    System.out.println("getSubject: Building callback handler: ["+itimUser+"]/["+itimRealm+"]/["+itimPswd+"]");
                    handler = new WSCallbackHandlerImpl(itimUser, itimRealm, itimPswd);

             LoginContext loginContext = new LoginContext("WSLogin", handler);

                    System.out.println("Attempting login");
                    System.out.println("Logged in");
                    System.out.println("Obtained loginContext, subject is: " + loginContext.getSubject().toString());
            catch(Exception e)
                    System.out.println("Error Class: " + e.getClass());
                    System.out.println("Error Message: " + e.getMessage());
                    System.out.println("Error LocalizedMessage: " + e.getLocalizedMessage());

            return loginContext.getSubject();





Some of the errors and solutions I have experienced along the way with this one;


If you don’t have the right port for your websphere server, then you can get the following error. In this case I have two clusters – one has the application server with a bootstrap port on 2811, the other on 2810 – my error below is when I mixed the two up (doh!).

SEVERE: null 
Context: myserverCell01/clusters/ITIM_Messaging_Cluster, 
name: enroleejb.ManagedObjectImplHome: First component in name enroleejb.ManagedObjectImplHome not found. 

This error is similar – completely the wrong port and there is no process listening on it.  As usual, search for BOOTSTRAP_ADDRESS and locate the port for your Application Server WAS instance;

getSubject: Error Class: class getSubject: 
Error Message: SECJ0395E: Could not locate the SecurityServer at host/port:{0} to validate the userid and password entered. 
You might need to specify valid securityServerHost/Port in ${WAS_INSTALL_ROOT}/profiles/profile_name/properties/sas.client.props file. 
getSubject: Error LocalizedMessage: SECJ0395E: Could not locate the SecurityServer at host/port:{0} to validate the userid and password entered. 
You might need to specify valid securityServerHost/Port in ${WAS_INSTALL_ROOT}/profiles/profile_name/properties/sas.client.props file. loginContext: null

Name resolution

I remember this problem from back in the day with very old CORBA servers. What I didn’t realise was that my VPN connection from home was giving me a different reverse resolution to that in the office. Oh well – out with the hosts file in the end, but as usual it took a while to realise what the problem was.

It is also strange because I was providing the FQDN of my server in “” and “PlatformContext.PLATFORM_URL”, but for some reason the client code was changing this to the shortname (at least that’s what appeared in the logs below). The problem in this case was environmental and some of my own making probably. While we have an ISIM cluster and load balancer in front of that for https traffic, the load balancer doesn’t handle the API port (BOOTSTRAP_PORT in WAS). So that meant I was doing this setup by going straight to a single AppServer. For some reason my VPN from home would resolve the AppServer hostname to IP correctly, but then when it attempted a reverse lookup for the IP address it got the load balancer FQDN back – no chance that would work! Two simple answers; 1) local hosts file to correct the name resolution while developing and 2) add the BOOTSTRAP_PORT to the loadbalancer configuration and use that fqdn instead. Either way the message is that you have to have your forward and reverse name resolution in place such that it resolves both ways to the same host/ip

My error;

getSubject: Error Class: class
getSubject: Error Message: SECJ0395E: Could not locate the SecurityServer at host/port:{0} to validate the userid and password entered. You might need to specify valid securityServerHost/Port in ${WAS_INSTALL_ROOT}/profiles/profile_name/properties/sas.client.props file.
getSubject: Error LocalizedMessage: SECJ0395E: Could not locate the SecurityServer at host/port:{0} to validate the userid and password entered. You might need to specify valid securityServerHost/Port in ${WAS_INSTALL_ROOT}/profiles/profile_name/properties/sas.client.props file.
loginContext: null


If you read this article from IBM, at the bottom it describes how to configure tracing for the corba client & doing this generated a log which turns the above ISIM message into something useful & that’s what showed me my UnknownHostException!;

11:08:57.801 getHostIPAddress:134 P=735951:O=0:CT ORBRas[default] MYHOSTNAME: MYHOSTNAME


More errors

To be honest I had many, but didn’t capture them all. I’ve got more work to do on this client code so will update this post with what will be some more inevitable problems. That said, the configuration in this post should help you avoid most problems.

ITIM Custom Authentication

ITIM allows you to provide your own custom authentication module which can be very useful to meet corporate authentication standards – such as authenticating with an authoritative LDAP, database or perhaps & more likely, AD.

ITIM ships with an example for a custom AD authentication provider in ${ITIM_HOME}/extensions/examples/authentication/adauthentication which is a really good place to start.

This shipped example covers enough about how to create the module so there is no need to repeat that here, but there are a couple of things that are worth pointing out to make things go a little better.

First of all, make sure your authentication factory matches the interface definition exactly;

public class ADProviderFactory implements
 AuthenticationProviderFactory {

 public ADProviderFactory() { }

 public AuthenticationProvider getProvider(Hashtable env)
 throws ConfigurationException {
 return (AuthenticationProvider)new ADAuthenticationProvider(env);

I’ve added in the class cast to AuthenticationProvider from the example that’s shipped to ensure there is no chance that the caller thinks that we’re not meeting the interface – although it certainly does work without it.

Personally I found the example a useful base for the ADAuthenticationProvider and ADAuthenticationHelper classes, but feel free to add your own customisation in there as needed.  In particular in a large enterprise there can be issues for *nix based ITIM servers using the example’s way of determining the AD domain controller to connect to.   Windows based ITIM servers won’t have this problem (I’ll try to make that into another post).

In the design of your AuthenticationProvider class I’d suggest considering some of the following;

  • The AuthenticationProvider has to end up returning a SystemUser.  It should really check that the ITIM user that’s returned is active.  It wouldn’t be great to allow active AD users to login to their inactive ITIM admin accounts…..gulp!
  • There is no need to be exclusive about the authentication provider.  You can try AD, then maybe go off and try a database, and perhaps if none of that works trying the plain old ITIM login itself.  Also, consider adding properties to the file to control which providers are active.
  • If you don’t mind a slight performance loss, move the loadProperties() call in the example into the authenticate method.  That way all your properties are dynamic and you don’t have to restart ITIM to pick up flag changes.
  • Be sure to add sufficient logging so you can see your module functioning.  Don’t over do it because although ITIM admins logging in won’t cause problems, if you have a lot of JNDI or web services happening then you may make your logs too noisy.  Also make sure you don’t do the usual security give-away’s by telling an attacker that an account name is wrong, or just the password was wrong – authentication failures should just state that the authentication failed – nothing more.
  • Don’t expose unnecessary details about your user repositories in the logs either.  Generic names should suffice so you can monitor progress.


When it comes to deployment there are a couple of points to add in;

  • First of all, put your new module in the classes directory of each of your WebSphere application servers.  So that’s /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/classes/ for a default install.  This is actually covered in an ISIM interim fix bit of doco update, but I’ve repeated it because it’s a pain to dig out the IV zip file just for that line.
  • Now, if you’re using a cluster you will also need to copy the jar into /opt/IBM/WebSphere/AppServer/profiles/DMgr/classes/.  If you don’t do this then you may see “class not found” errors for your AuthenticationProvider class when you’re in the WAS console.  Actually – I found these only when I was trying to change the ISIMSecurityDomain properties.
  • Finally, you need to add your new jar to the ITIM_LIB shared library.  Now, this isn’t that obvious at first, but it would appear that there are multiple classloaders working in ISIM so what I found is that login/authentication works fine, web services work fine, but JNDI calls from TDI don’t.  The solution is to add the class to ITIM_LIB.  The error I had was;
  • com.myorg.adauthentication.ADProviderFactory incompatible with ( class java.lang.ClassCastException)

Now that’s a little unpleasant, and it directs you back to your AuthenticationProviderFactory.  This problem is actually a classloader problem.  Because the classloader that is the login page loads the class and then the classloader that is the JNDI event handler also loads the class, they consider the classes to be different and then throw this exception.  So, by putting the jar into the ITIM_LIB shared library, you’re allowing the parent classloader to load the class – then when the child classloaders load it they can resolve the class to the common type that the parent loaded and this exception is avoided.  Ok – that was the longest explanation for putting something into ITIM_LIB ever…..


Now – with that in hand, restart the application servers (and the DMgr) if you’re in a cluster) and you should be ok.  I would  expect that you could use a symlink to the jar to avoid having multiple copies of the jar (not tested so don’t shoot me).

That’s it – you should now have your custom authentication provider working and authenticating your various clients – user’s logging in, web services, JNDI, etc…