IBM Support

Configuring LDAP Federated Repository for TPAE Maximo

Technical Blog Post


Configuring LDAP Federated Repository for TPAE Maximo


The objective of this post is provide a definitive view of how configuring Maximo authentication using WebSphere and a LDAP Federated Repository.
During the reading, it will be possible to understand some definitions and get tips to take the best of this capability.

This example uses the Federate Repository functionality of WAS, which means, allow one-to-many authentication sources be used as a single view from the application perspective. It is worth considering this approach due its easy configuration and ability to expand to more repositories when necessary.

These are the product versions used on this post:
- WebSphere Application Server 7.x
- TPAE 7.5.x
- ITDS 6.3

Although it has been used WAS 7.x and TPAE 7.5.x., Authentication Federated repository is available on WAS 6.1.x and consequently for TPAE 7.1.1.x. versions (screenshots and menus may vary according the version used).
Configuring WebSphere and Federated Repository

. To get main authentication functions, log in WAS Administrative console and select "Global Security" in Security section on the left pane.
. Now, general security's rules is set and the repository configuration is initiated.
. Make sure "Enable application security" is checked. It means WAS will take over all authentication requests for deployed applications.
Click on "Configure..." button under "User account repository" to add a new authentication point. Confirm if "Federated repositories" is the realm definition chosen.
image . On this step, it is possible to check which are the existent repositories already created and managed each one.
Click on "Add base entry to Realm..." to add the new repository information.
image . On "Repository reference" step, click on "Add repository..." button to define a new reference.
Distinguished names are going to be filled after.
image . On this step ("New"), some points need to be filled in order to get the new repository configured:

Repository Identifier

- LDAP server
- Directory type: many options are available. On WAS 7, different options were added, simplifying compatible versions. ITDS is used on this sample.
- Primary host name: IP or Host name of LDAP machine is installed.
- Port: 389 is the default port number for non-secure operations. LDAP over SSL uses 636, instead.
- Security
- Bind distinguished name: LDAP adminstrative user, that is used to link WAS and LDAP servers. Use distinguished name's format. Ex: CN=root
- Bind password: Bind distinguished name's password.

Notice: These are the standard steps for that configuration . Specific needs won't be covered on this document. Check WebSphere documentation for more details

Click "OK" button to return to previous step.
image Make sure the recent repository's name is select on the Repository Combo box.
Fill both fields according definition bellow:

- Distinguished name that uniquely identifies this set of entries in the realm

Specifies the distinguished name (DN) that uniquely identifies this set of entries in the realm.
If multiple repositories are included in the realm, it is necessary to define an additional distinguished name that uniquely identifies this set of entries within the realm. Overlapping base entries are not supported. You should not define two base entries where one is c=us, and the other is o=myorg,c=us in the same realm; otherwise a search returns duplicate results.

- Distinguished name of a base entry in this repository

Specifies the Lightweight Directory Access Protocol (LDAP) distinguished name (DN) of the base entry within the repository. The entry and its descendents are mapped to the subtree that is identified by the unique base name entry field.

If this field is left blank, then the subtree defaults to the root of the LDAP repository.

Click on "OK" button to return to previous step.
image Now, it is possible to see the additional repository MAXIMO on the repositories' list.
Notice there are 2 entries on this sample, one is MAXIMO and other is identified as InternalFileRepository.

What is InternalFileRepository?

It is the default repository for WAS. Administrative users, their passwords and respective groups are defined on this place, when there is no any other authentication definition created. All configuration data is stored in a system file.

(*) When using both as shown above, check if wasadmin is not created in both structures, otherwise it might create a conflict with that user. In case of having wasadmin in LDAP structure, delete the InternalFileRepository reference, selecting through the check box and hit "Remove" button.

With that done, click on "Save" link on message section on the top of the screen.

Now, it is needed to refresh (stop/start) the Deployment Manager to get all configurations in place.

. After that, login in WAS console as administrator (ex: wasadmin) and navigate to "Users and Groups" section on the left panel.
image. Select "Manage Users" to open the application that lists and manages the existent users on the federated repositories.
image Define the search conditions and click on the "Search"button.
All existent users will be shown on the list, according the criteria used.

Configuring Maximo authentication

While TPAE authentication is under FORM method, the login page is similar to the screen bellow.
Next step is change the way TPAE authentication works.
Find web.xml file under <SMP_FOLDER>\maximo\applications\maximo\maximouiweb\webmodule\WEB-INF\ folder.
Make a backup copy on the same folder.
Follow the steps bellow in order to change TPAE authentication method to BASIC.

Uncomment (it should be commented) the following XML section.
Remove "<!-- -->" from section boundaries.

<web-resource-name>MAXIMO UI pages</web-resource-name>
<description>pages accessible by authorised users</description>
<web-resource-name>MAXIMO UI utility pages</web-resource-name>
<description>pages accessible by authorised users</description>
<description>Roles that have access to MAXIMO UI</description>
<description>data transmission gaurantee</description>

<realm-name>MAXIMO Web Application Realm</realm-name>

To make sure BASIC method is used, comment the following XML section, as shown bellow.

<realm-name>MAXIMO Web Application Realm</realm-name>

Save the file and proceed to generate a new EAR file, using buildmaximoear.cmd/sh file under <SMP_FOLDER>\maximo\deployment\ folder.
Redeploy the EAR file using WAS console.

Stop and start the WAS Deployment Manager and its servers (MXServer)

Make sure TPAE administrator users are created on the Authentication repository at this moment.
The default administrator users are: maxadmin, maxreg and mxintadm.

After change the authentication method to BASIC, the following login dialog will appear.
It means WAS is controlling the authentication and no longer TPAE.

Log in as maxadmin and test it.

Check the tips & tricks section out (bellow) in case of any problem.
Tips and Tricks

- User duplicated in more than one repository

As stated before, using Federated Repositories, it is possible to have more than one source to authenticate users from applications.
In case of having duplicated users managed by different repositories, WebSphere won't allow authentication.

It is necessary to remove the user from one repository prior any new attempt to log in.

If, that is the case of wasadmin user, remove the WAS Console security and fix the duplications issue.
Usually it happens when wasadmin is created on a LDAP Server and on InternalFileRepository, at the same time.

- Disabling WebSphere security

In some cases it is necessary to disable the WAS console authentication, allowing access to the console without password confirmation.
It usually happens when WAS administrative user (ex:wasadmin) is under LDAP server control and for some reason, the authentication fails between WAS server and LDAP.

To workaround that situation, it is possible to edit security.xml file and disable the authentication.

Depending on what is the WAS configuration, different steps are needed.

Where security.xml is:

In a standalone version - not in cluster, the file is on following path.
<wsas profile root>/config/cells/cellname/security.xml

In a cluster environment, the file is placed on the path bellow, but
<dmgr profile root>/config/cells/cellname/security.xml

Edit the security.xml file and search for the first instance of "enable=".

<security:Security xmi:version="2.0" xmi:id="Security_1" useLocalSecurityServer="true" useDomainQualifiedUserNames="false" enabled="true" cacheTimeout="600" issuePermissionWarning="true" activeProtocol="BOTH" enforceJava2Security="false" enforceFineGrainedJCASecurity="false" activeAuthMechanism="LTPA_1" activeUserRegistry="CustomUserRegistry_1" defaultSSLSettings="SSLConfig_1">

Change to enable="false". Save the file.

In case of Clustered environmente, copy security.xml file to respective nodes folder:
<node 1 profile>/config/cells/cellname/security.xml
<node 2 profile>/config/cells/cellname/security.xml

Restart the Deployment Manager and all servers. If you have any problems to stop them, kill the server processes manually and then restart them.

- Checking LDAP repositories configuration

Usually when Maximo is deployed it is necessary to know about authentication structure used on a specific WebSphere Application Server, mainly to know which LDAP servers are being used to control accessing of deployed applications.
Instead of using the regular WAS console Web application, it is possible to get all the information (except password) from the file WimConfig.xml.
There it is possible to see additional information about LDAP servers, binding users and prefix used during configuration, but also get details about LDAP entities and Federated repositories.

The file WinConfig.xml is deployed according how WAS is being used:

In a standalone version - not in cluster, the file is on following path.
<wsas profile root>/config/cells/cellname/wim/config/wimconfig.xml

In a cluster environment, the file is placed on the path bellow, but
<dmgr profile root>/config/cells/cellname/wim/config/wimconfig.xml

It is not recommended to edit this file, once it affects directly the runtime behavior. However, if necessary, make sure you a have backup copy the file before act.

- system#invalidsecurityconfig Error

If, for some reason, the error system#invalidsecurityconfig appears when Maximo is loaded on the web browser, it means there is a wrong parameter set on web.xml file.
Get the file on <> and edit it.
Search for "<env-entry-name>useAppServerSecurity</env-entry-name>" and check if its value "<env-entry-value>" is set to 0 - using FORM authentication or 1 - using BASIC authentication. It must be set according the mode chosen.

- LDAP clients

During Maximo installation or any post configuration of LDAP authentication, it is useful have some tools to navigate throughout the directory structure.
Bellow, there are 2 open-source suggestions you must have on your toolset.

Apache Directory Studio -
JExplorer -

- Impact on Integrations (MIF)

When enabling the LDAP security, any existent integrations towards to Maximo, using WebServices, HTTP or REST interfaces, needed to be reviewed. From that moment, all external systems must send the authentication credentials (user and password) embedded on each request.

It won't affect outgoing messages, from Maximo to an external system.


After reading this post, it is expected you are able to:
- Identify main components of Maximo authentication architecture
- Configure WAS and Maximo to enable/disable LDAP authentication
- Identify main pitfalls and workarounds for them

Federated repository capability makes TPAE more flexible and adherent to existent customer scenarios, allowing reuse of authentication resources and reducing management effort.

An additional post is being planned to explain more about Maximo VMMSync functionality - that synchronizes WAS Federated repositories structure to Maximo Users and Groups.


- TPAE: Tivoli Process Automation Engine a.k.a. Maximo
- VMM: Virtual Member Manager
- WAS: WebSphere Application Server
- ITDS: IBM Tivoli Directory Server


- WAS:
- TDS:

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