Maximo LDAP - LDAPSYNC Filtering and Configuration

Body

This is the second part of a two-part document on user and group synchronization, the first being Maximo LDAP - VMMSYNC Filtering and Configuration.
There is a lot of overlap between the two processes; some information is repeated here from the VMMSYNC document.

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
• New properties in 7613 IFIX 006 and 7612 IFIX 31
• Creating its own appender and logger

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

The LDAPSYNC cron task has ten 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 - Extra sync parameters separated by commas. Default holds the global catalog 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">
<ldapsync>
	<user>
		<basedn>ou=allmaximousers,dc=mydomain,dc=com</basedn>
		<filter>(&amp;(objectCategory=person)(objectClass=user)) </filter>
		<scope>subtree</scope>
		<attributes>
			<attribute>sAMAccountName</attribute>
			<attribute>givenName</attribute>
			<attribute>sn</attribute>
			<attribute>displayName</attribute>
			<attribute>streetAddress</attribute>
			<attribute>homePhone</attribute>
			<attribute>memberOf</attribute>
			<attribute>telephoneNumber</attribute>
			<attribute>mail</attribute>
			<attribute>st</attribute>
			<attribute>postalCode</attribute>
			<attribute>c</attribute>
			<attribute>l</attribute>
		</attributes>
		<datamap>
			<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>
			<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>
			<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>
			</table>
		</datamap>
	</user>
</ldapsync>

To simplify what usermapping xml does, break down its section.
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 XML includes information that isn't required by Maximo. What can be removed? This is the simplest user sync that can be used:
 

  <?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ldapsync SYSTEM "ldapuser.dtd">
<ldapsync>
	<user>
		<basedn>ou=allmaximousers,dc=mydomain,dc=com</basedn>
		<filter>(&amp;(objectCategory=person)(objectClass=user))</filter>
		<scope>subtree</scope>
		<attributes>
			<attribute>sAMAccountName</attribute>
		</attributes>
		<datamap>
			<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>
			<table name="PERSON">
				<keycolumn name="PERSONID" type="UPPER">sAMAccountName</keycolumn>
			</table>
		</datamap>
	</user>
</ldapsync>

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 want to sync users from. If you want the whole directory, 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 use Microsoft Active Directory User and Computers tool 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 by using a standard LDAP filter. It follows the same format. The only gotcha is the XML formatting problems with the ampersand. If you want just a '&' use the special character &. You can filter on any attribute that objects have. If you have custom or modified attributes in Active Directory, these can be used in LDAPSYNC 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 sync 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 into whether or not the attribute is a referral or not. LDAPSYNC 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 cannot break business rules, and the information must be a one-step process (for example, 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. Hardcoding 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 hardcoded 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. Without these being the same, users will not be able to log in.

Filtering:

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.
 

<filter>(&amp;(objectClass=user)(objectCategory=Person))</filter>

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

<filter>(&amp;(objectClass=user)(memberOf=cn=maximousers,ou=etc))</filter>

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

<filter>(&amp;(objectClass=user)(|(memberOf=cn=maximousers,ou=etc)(memberOf=cn=maximoadminusers,ou=etc)))</filter>

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

<filter>(&amp;(objectClass=user)(!(sAMAccountName=*$*))(|(&amp;(employeeType=Regular)(department=office))(&amp;(employeeType=Contract)(department=maximo))))</filter>

New properties in 7613 IFIX 006 and 7612 IFIX 31:

Two new properties were added in order to help with certain error conditions during LDAPSYNC that could not be handled by configuration, routing or other means. These are not added by default, and would need to be added manually through System Properties. Will only be used and applicable on the versions mentioned above and later.

mxe.ldap.user_search_page_size - A number from 1-10000. This property default is 500. Sets to LDAP page return results from the directory. If running into the exception Unprocessed Continuation Error.
mxe.ldap.context.follow - 1 or 0, or true or false. This will set the LDAP to follow references received. Will require DNS on the domain and can possibly allow for nested group usage.

Debugging:

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. Complete the required fields.

(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. Complete the required fields.

(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.