Configuring i2 Analyze for LDAP authentication

Enable authorization and authentication using WebSphere Liberty and LDAP


Configuring WebSphere Liberty to work with LDAP in the context of the i2 Analyze application involves several steps and has ramifications for the i2 Analyze security schema itself. Knowing how i2 Analyze handles both authentication and authorization of users and groups in an LDAP repository affects the configuration of the i2 Analyze security schema.

In this article, you will learn how to integrate WebSphere Liberty with LDAP for the i2 Analyze application as I describe:

  • How your system should be set up
  • How to configure the registry files based on your version level of WebSphere Liberty
  • How to troubleshoot authentication and authorization issues

This article is suggested for i2 Analyze site administrators or anyone who wants to install, configure, or administer i2 Analyze.

Meeting system prerequisites

Your system should already have the following tasks completed:

  • i2 Analyze installed and configured with basic registry per the i2 Analyze installation guide. If you can successfully log in with the example user in the <basicRegistry>, then i2 Analyze is working as it should for the WebSphere Liberty configuration task.
  • Security schema finalized and available. To ensure authorization beyond authentication, the i2 Analyze security schema needs to be finalized prior to the configuration of i2 Analyze for LDAP. The security tags or security dimensions must be configured for the customer for a production environment. These security groups need to reflect the groups in the LDAP repository. Full configuration of the security schema is beyond the scope of this article; refer to the i2 Analyze installation guide if needed. The examples used in this article are from the security schema that is packaged with i2 Analyze, so you need access to those examples.
  • LDAP server connection information, including the full connection path of the LDAP, bindings, and passwords.
  • Users and groups populated in LDAP.
  • Users assigned to groups. In case of an OpenLDAP, users must also be defined by their long names. Aliases or short names will not authorize.

Completing configuration tasks

Complete the following tasks to configure your environment.

Step 1. Comment out the basic registry

Once you have a working i2 Analyze installation with the basic registry file-based authentication, you need to remove file-based authentication in order to use LDAP. If it is not removed, an error occurs upon attempting to start WebSphere Liberty stating that there are multiple user registries available and Liberty doesn't know which one to use. To remove file-based authentication, go to \i2analyze\deploy\wlp\usr\shared\config\user.registry.xml, and delete or comment out the entire <basicRegistry> element within the <server> tags, as shown below.

<!--<basicRegistry id="basic" realm="WebRealm">
	<user name="Jenny" password="{xor}FToxMSY="/>
		<group name="Controlled">
			<member name="Jenny"/>
		<group name="Unclassified">
			<member name="Jenny"/>
		<group name="Human Informants">
			<member name="Jenny"/>
		<group name="Open Source Intelligence">
			<member name="Jenny"/>
		<group name="Security Controller">
			<member name="Jenny"/>
		<group name="Other">
			<member name="Jenny"/>
		<group name="Administrator">
			<member name="Jenny"/>

Step 2. Edit the user.registry.xml file

After you remove the file-based authentication, customize the Liberty profile to the LDAP environment. The primary XML file is server.xml, located in the i2 Analyze toolkit directory. To simplify file administration and to streamline changes made to the file, I recommend that you create a user.registry.xml file or download the one I used. This file is already referenced by the server.xml file, and all configuration changes will still be in place after any upgrade.

Step 3. Add Liberty runtime features

To configure LDAP, start by adding specific features to the Liberty runtime.

  1. Open the user.registry.xml file, and add the following lines between the existing <server> tags:
  2. Add the code that Liberty requires to add the needed features.

Step 4. Add LDAP-related elements

Add LDAP-related elements to your user.registry.xml file. The following is the content of my user.registry.xml file for this article. I describe the individual elements below the example.

	<ldapRegistry id="ActiveDirectoryLDAP" realm="myrealm"
        host="" port="389" ignoreCase="true"
        ldapType="Microsoft Active Directory">
		<primaryRealm name="myrealm">
			<participatingBaseEntry name="dc=foo,dc=bar,dc=baz"/>
			<groupSecurityNameMapping inputProperty="cn" outputProperty="cn"/>

The specific attributes added to the <ldapRegistry> element depends on the LDAP type to which you are connecting Liberty. The IBM Knowledge Center has specifics on the needed attributes and sub-elements. The id attribute uniquely identifies this ldapRegistry throughout all of the server configuration files for Liberty. In this article, I used Microsoft Active Directory.

  • The realm attribute identifies this particular <ldapRegistry> when making federated repositories, which must be done and is discussed further below.
  • Host is the active directory server IP address.
  • The port is almost always 389, but check with the LDAP administrator.
  • The baseDN attribute is the starting search point for LDAP searches.
  • The bindDN attribute is the distinguished name for the application server. bindDN uses the specified value to bind to the directory service. Some LDAP systems allow anonymous binding, but Active Directory does not.
  • The bindPassword attribute contains the password for the bindDN. Note that it is not good practice to store passwords in clear text. You can use the secureUtility tool to encode the password. This tool is also described in the i2 Analyze installation guide.
  • The ldaptype attribute is restricted to a list of LDAP providers with which Liberty can interact. Refer to the current list of LDAP providers.
    • Microsoft Active Directory
    • Custom (select this option if using OpenLDAP)
    • IBM Lotus Domino
    • Novell eDirectory
    • IBM Tivoli Directory Server
    • Sun Java System Directory Server
    • Netscape Directory Server
    • IBM SecureWay Directory Server

The following sub-elements for the <ldapRegistry> might be necessary if your particular LDAP does not use the usual defaults, although this example configuration does not need them:

  • The <activatedFilters> element is specific to Active Directory (there are other elements for the other LDAP types). Use it when the Active Directory service does not follow default values. For a complete list of the ldapRegistry sub-elements, refer to the Knowledge Center.
  • A <federatedRepository> element must be added because of the i2 Analyze security schema, even if you are using only one repository. If a <federatedRepository> element is not present, then the security schema would require the fully qualified domain name (FQDN) of the LDAP security groups. This can be cumbersome, increases risks of exposure, and can lead to problems with maintenance and administration. This is true regardless of whether security dimensions or security tags are used in the i2 Analyze security schema.

Once you complete the edits to the user.registry.xml file, save and close the file. You are now ready to test your configuration.

Testing and debugging your configuration

To test your configuration, complete the following steps:

  1. Stop the i2 Analyze application using setup -t stopLiberty.
  2. Start the i2 Analyze application using setup -t startLiberty. Refer to the i2 Analyze installation guide if you need additional start commands.
  3. Open the intelligence portal.
  4. Log in using the credentials specified in the LDAP server to which you connected the i2 Analyze Liberty profile.

If you have issues with your configuration, start to debug in the console.log file located at i2analyze\deploy\wlp\usr\servers\i2analyze\logs. That console.log file records what is happening within Liberty after you start the server. If the server.xml and related configuration files are malformed, Liberty will fail to start properly, and the logs will show it.

Fix authentication issues

Authentication is the process of making sure that a user is really who he claims to be.

If a user is unable to log into the intelligence portal, then authentication might be failing. Possible reasons include:

  • Incorrect credentials
  • Incorrect LDAP settings
  • Firewalls blocking the connection

To resolve this, work with the local LDAP administrator. If using openLDAP, check that all users and all groups have full names defined in the configuration.

Fix authorization issues

Authorization refers to rules that determine what a user is allowed to do. Authorization is crucial to data security in i2 Analyze, and it ties into the LDAP groups and the security schema. The names of the groups in the LDAP directory must be the same as the names of the security dimension values in the security schema.

For example, in the example security schema packaged with i2 Analyze, there are six values:

  • Controlled
  • Unclassified
  • Human informants
  • Open source intelligence
  • Security controller
  • Other

Each of these values must exist as a group within your LDAP repository. Additionally, users must be members of at least one of these groups. If a user does not belong to the appropriate groups, he can authenticate, but he has no authorization. If a user is able to log in, but cannot see any data, then authorization might be failing.

The default logging level might be too low for you to troubleshoot authorization. To increase the logging level of detail, complete the following steps. This will add a large amount of security-related logging to the console.log file.

  1. Edit the file in i2analyze\toolkit\configuration\fragments\common\WEB-INF\classes, and uncomment the line
  2. Redeploy the i2 Analyze application using setup -t deploy.
  3. Restart Liberty using setup -t startLiberty.
  4. Log into the intelligence portal again.

You will see entries like the following in the console.log:

  • [] - Authenticated UserName 'Manager', member of groups [Other, Unclassified, Open Source Intelligence]
  • [] - Authenticated UserName 'Demo', member of groups [Controlled, Open Source Intelligence, Other, Security Controller, Human Informants]
  • [] - Authenticated UserName 'Analyst', member of groups [Security Controller, Human Informants, Controlled]

The following log entry indicates an authorization issue:

  • [] - Authenticated UserName 'Demo', member of groups []

This entry means that the user is not authorized, because that user does not belong to any groups as specified in the security schema (member of groups []). Add that user to the appropriate groups within the LDAP repository, and try logging in again. Be sure to return logging to the default level after debugging is complete.

Additional logs, including trace.log, messages.log, and IBM_i2_Analysis_Repository.log are contained within the logs directory and can assist with troubleshooting.


In order for WebSphere Liberty to work with LDAP in the case of the i2 Analyze application, complete these steps:

  1. Verify that the basic installation of i2 Analyze is in good working order and that you can authenticate with the <basicRegistry>.
  2. Make sure you have a specified the security schema and the correct LDAP repository connection information.
  3. Edit the user.registry.xml file. If required, download additional features for the <LDAPRegistry> element to function.
  4. Troubleshoot authentication and authorization issues, increasing then decreasing the logging level, if needed.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Big data and analytics, WebSphere
ArticleTitle=Configuring i2 Analyze for LDAP authentication