IBM Support

Maximo LDAP - LDAPSYNC Filtering and Configuration

Technical Blog Post


Maximo LDAP - LDAPSYNC Filtering and Configuration


This is the second part to go with my previous blog on VMMSYNC, except this time we're going to be discussing LDAPSYNC.
There is a lot of overlap between the two processes so there will be some information repeated here from VMMSYNC, however
it will be focusing on LDAPSYNC instead.
If you're looking for the discussion on VMMSYNC you can find it here:

Edit: Missed the section on custom attributes, added!


Topics to be discussed:
Overview of LDAPSYNC parameters
The user synchronization xml.
      -From where do I want the information?
            -Defining the basedn
            -Optimally filtering information
      -What information do I want?
            -How to choose attributes
            -Rules for using attributes
            -Using custom attributes
      -Where do I want the information to go?
            -Rules for synced data
            -Keeping synced fields consistent
Filtering with LDAPSYNC
      -Common attributes to use for filtering
      -Examples of filters and syntax

Debugging LDAPSYNC
      -Creating its own appender and logger

LDAPSYNC is similar to VMMSYNC in that they both perform the same function. The main advantage LDAPSYNC has over VMMSYNC is that it is more customizable and less instrusive to a running environment when making changes  and customizations. It also matches 1:1 with Active Directory(AD) (almost completely), and due to this can be easier to see what's happening "under the hood." LDAPSYNC connects directly to the AD repository and as such only  works with Active Directory and is not designed to work with other directories. In this respect is it limited to only one platform. It can be used to sync from multiple directories or forests. It does this through the global catalog, or through  running multiple instances of LDAPSYNC cron task.
It should be noted that while the sync goes directly to AD, when users are synced via the LDAPSYNC cron task, it does not gaurantee authentication, as authentication is still controlled by the Application Server (WebSphere or  WebLogic).

The cron task has 10 different Cron Task Parameters.

Credential - The password of the principal user.
GroupMapping - The xml used to choose what groups and group members to sync.
Host - The IP or dns name of the Active Directory server.
Port - Port to connect to Active Directory.
Principal - The principal user that connects to the directory to query for information.
SSLEnabled - Where SSL is required for connecting to the directory.
SynchAdapter - Class to get user data.
SynchClass - Class to sync user data.
SynchParameter - Additional synch parameters separated by commas. Default holds the globalcatalog connection port.
UserMapping - The XML used to choose what users and attributes to sync to maximo.

User sync XML:

<?xml version="1.0" encoding="UTF-8" ?><!DOCTYPE ldapsync SYSTEM "ldapuser.dtd">
<filter>(&amp;(objectCategory=person)(objectClass=user)) </filter>
<table name="MAXUSER">
<keycolumn name="USERID" type="UPPER">sAMAccountName</keycolumn>
<column name="LOGINID" type="ALN">sAMAccountName</column>   
<column name="PERSONID" type="UPPER">sAMAccountName</column>                  
<table name="PERSON">   
<keycolumn name="PERSONID" type="UPPER">sAMAccountName</keycolumn>
<column name="FIRSTNAME" type="ALN">givenName</column>   
<column name="LASTNAME" type="ALN">sn</column>
<column name="DISPLAYNAME" type="ALN">displayName</column>
<column name="ADDRESSLINE1" type="ALN">streetAddress</column>   
<column name="STATEPROVINCE" type="ALN">st</column>
<column name="CITY" type="ALN">l</column>   
<column name="POSTALCODE" type="ALN">postalCode</column>
<column name="COUNTRY" type="ALN">c</column>        
<column name="STATUSDATE" type="ALN">{:sysdate}</column>             
<table allowdelete="true" name="PHONE">   
<keycolumn name="PERSONID" type="UPPER">sAMAccountName</keycolumn>
<keycolumn name="TYPE" type="UPPER">{WORK}</keycolumn>   
<keycolumn name="ISPRIMARY" type="YORN">{1}</keycolumn>  
<column name="PHONENUM" required="true" type="ALN">telephoneNumber</column>  
</table><table allowdelete="true" name="PHONE">   
<keycolumn name="PERSONID" type="UPPER">sAMAccountName</keycolumn>
<keycolumn name="TYPE" type="UPPER">{HOME}</keycolumn>   
<keycolumn name="ISPRIMARY" type="YORN">{0}</keycolumn>    
<column name="PHONENUM" required="true" type="ALN">homePhone</column>
</table>  <table allowdelete="true" name="EMAIL">   
<keycolumn name="PERSONID" type="UPPER">sAMAccountName</keycolumn>
<keycolumn name="TYPE" type="UPPER">{WORK}</keycolumn>   
<keycolumn name="ISPRIMARY" type="YORN">{1}</keycolumn>  
<column name="EMAILADDRESS" required="true" type="ALN">mail</column>  


This can be broken down into three different sections for simplification.
The first is the basedn and the filter -> From where do I want the information?
The second is the attributes -> What information do I want?
The third is the table mappings -> Where do I want the information to go?


The out of the box sync has a lot of extra information that isn't necessarily required by Maximo. If you're wondering what can be removed, here is the simplest user sync that can be used:
<?xml version="1.0" encoding="UTF-8" ?><!DOCTYPE ldapsync SYSTEM "ldapuser.dtd">
<filter>(&amp;(objectCategory=person)(objectClass=user)) </filter>
<table name="MAXUSER">
<keycolumn name="USERID" type="UPPER">sAMAccountName</keycolumn>
<column name="LOGINID" type="ALN">sAMAccountName</column>   
<column name="PERSONID" type="UPPER">sAMAccountName</column>                  
<table name="PERSON">   
<keycolumn name="PERSONID" type="UPPER">sAMAccountName</keycolumn>        

From where do I want the information?
The basedn is the base domain name of your directory. LDAPSYNC connects directly to your directory so this will be the lowest point you wish to sync users from. If you want the whole directory then you can point it at the DC level. If there is only a small set of users, then you can go deeper into the container (OU) structure to limit the users synced into Maximo. If you're not sure what basedn to use then you will need to contact your system administrator or consult  Microsoft's Active Directory User and Computers to find the required users and most ideal location. Combined with the basedn, the filter is the other piece that specifies where you want the information from. This uses a standard LDAP filter and follows the same format. The only gotcha is the XML formatting problems with the ampersand. Note in the example above, if you want just a '&' then it should be displayed in the filter as '&amp;'. You can filter on any attribute  that the objects have. This means that if you have any custom or modified attributes in Active Directory, these can be used here with no additional configuration from the Maximo side.


What Information do I want?

This is probably the most important part of setting up LDAP with Maximo. The attributes you choose to pull in, will define how users login, how they get assigned work, how their person records are  viewed and how they are associated within the system (and possibly outside the system!). The trick to remember here is that attributes synced from Active Directory are pulled from the Global Catalog. The Global Catalog is a part of AD and most are not aware that it exists or what it does. A very common problem for choosing attributes from the directory is that the attributes simply do not exist in the Global catalog. This is especially important to note when you are syncing custom attributes to either loginid, personid or userid. As once these users are synced in to Maximo, getting rid of them is not an easy task, and due to this ALWAYS make a database backup before doing a new sync task. Users cannot be deleted from the front end of Maximo permanently. This means that once the users are added, removing them needs to be done from the backend, and there are a lot of references to these user properties. It's best to get it right the first time you do a full sync, this means that using either test users (a few would suffice) or only a small set of users to do your initial configuration is recommended. This way you don't do a full sync and pull in every user with incorrect attributes from Active Directory. You also want to make sure it's working as intended.

It is common to user sAMAccountName as the personid, userid and loginid. However this doesn't have to be the case. I would recommend that keeping loginids consistent across applications is easier to track and easier for users to maintain. These all need to be unique in Maximo which means they must also be unique coming from the directory. Once set, changing them would require deleting the users from the backend. The main tables are maxuser, person and groupuser. Note that deleting users from the backend is not officially supported and can cause data integrity issues. Make sure you evaluate the risk thoroughly before committing to this.

A common problem seen when syncing custom attributes is that attributes seem to not be pulled in to Maximo, or the field ends up being null. Everything is typed correctly, the field referenced can be found in an LDAP browser or in the directory, but Maximo is not pulling in the attribute. First thing to check is if the attribute you are trying to sync is in the Global Catalog for AD. As I mentioned earlier, the sync tries to pull from there by default. If the attribute does not exist there, then the first way to get it synced is to get it added to the Global Catalog. If it can't be added to the Global Catalog then it is possible to change the synch parameter to point to the LDAP port (389 by default, assuming no SSL), and it will pull it from there. If after changing it there, it still does not work (Cron task changed and reloaded and a new sync run), then it is probably worth looking in to whether or not the attribute is a referral or not. Maximo's LDAP sync does not support referrals or nested attributes/groups.


Where do I want the information to go?
Now that we have the information we need to get, we can put it where we want it. There are few limitations to putting data into Maximo. All tables must meet table requirements, meaning required fields. The information can not break  business rules, and the information must be a one step process (e.g. you can't put a workorder in approved status). As stated previously, the fields must match across all same-as relationships, e.g. personid must be the same for  every table. Hard coding values that you are going to change via another process is also not recommended. Let's say you want to set a user's supervisor to be a specific person, then later you want to do a lookup to see who their  supervisor should be, every time the sync runs, it will update this field to be the hard coded value, and the changes made via the lookup will be overwritten.

While keeping personid is important to be the same across different tables in your sync, you will also want to ensure that loginid matches the login property in WebSphere. Even though you're using LDAP for authentication, Maximo  still does its own authorization. This means that when you enter your credentials into the login page, Maximo will get the token from WebSphere, then compare that loginid to its own database in order to grant authorization and know who  the user is. If you are syncing the loginid in LDAPSYNC as the attribute sAMAccountName, then the login property in WebSphere (located in the admin console -> Global Security -> Configure -> Repository. It will be under the principal user used to connect to the domain). If you sync mail as your loginid, then the login property for WebSphere should be mail also. With out these being the same, users will not be able to log in.



The syntax of filtering on LDAPSYNC is best determined by business needs. The best way to see possible filters is by using examples.
Practical attributes to sync with and using them. sAMAccountName, memberOf, employeeNumber, employeeType, cn, email and department.

This is the basic filter for all objects that are classed as users and are persons.

This filter means all objects are users and are members of the group maximousers.

This filter does all users and each user is either a member of maximousers or maximoadminusers groups.

This filter does a few different things. First it says that all objects are users, and their sAMAccountName can NOT contain a $ in it. It then says in addition to those conditions, these users either have to be a regular employee
and have a department of office, or be a contract employee with a department of maximo.


Debugging LDAPSYNC is as important as setting it up. Is the sync doing what I want it to be doing? Are all users successfully coming in to Maximo? Are all attributes coming in to Maximo?

As some directories can be quite large, it means the amount of information being retrieved is also quite large. Due to this, I would recommend separating out LDAPSYNC to its own appender and keeping it in a separate log
in order to track any potential problems or failures.

To do this, go to the Logging application in Maximo.
Under Select Action go to Manage Appenders.
In Manage Appenders, select new row, Fill in the required fields.

image(Fig. LDAPAppend)


After creating the appender, under Root Loggers find the crontask logger (not crontaskmgr).
Select crontask and in the bottom section under Loggers, select new row.
Fill in the required fields.

image(Fig. LDAPLogger)


Thank you for taking the time to go over this and I hope I've helped clear up any questions or concerns when using LDAPSYNC, or LDAP in general.
Please feel free to leave any comments with further questions or things that can be added.

[{"Business Unit":{"code":"BU005","label":"IoT"}, "Product":{"code":"SSLKT6","label":"Maximo Asset Management"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":""}]