How can I identify the correct LDAPAuthenticationRealm settings for my company?

Use an LDAP browser to identify configuration settings

LDAP structures and naming conventions vary greatly from company to company. You will need to do some investigation. The following steps provide a general approach to discovering the correct configuration values.

Security Realm Logging for Troubleshooting

While troubleshooting, use this Logback configuration to report useful security status messages into the console log. This file overrides the default "logback.xml" file using engine HOCON configuration setting:

systemProperties = {
     "logback.configurationFile" = "debug-security.xml"
}

Place this file in your project's src/main/resources/ folder. Do not use this configuration for production deployment. Remove it after LDAP is correctly configured.

DEBUG logging configuration "debug-security.xml":

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 
  <appender name="RootConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss.}%usecs%d{Z} [%process:%thread] %-5level %logger: %msg%n</pattern>
    </encoder>
  </appender>
  
   <logger name="com.tibco.ep.security.realm">
     <level value="debug"/>
     <appender-ref ref="RootConsoleAppender"/>
   </logger>

   <logger name="com.tibco.ep.security.comm">
     <level value="debug"/>
     <appender-ref ref="RootConsoleAppender"/>>
   </logger>
      
  <root>
    <level value="info"/>    
    <appender-ref ref="RootConsoleAppender" />
  </root>

</configuration>

 

Discovering LDAP Settings

For the main investigation, use an LDAP browser tool that will show you the structure of your LDAP system, such as "Active Directory Explorer" (https://docs.microsoft.com/en-us/sysinternals/downloads/adexplorer).

To find the LDAP container in which users are defined (the principalSearchRoots) and the container in which roles are defined (the roleSearchRoots) follow these steps:

1. Search for your own record:
  Class: User -- user
  Attribute: E-Mail Address -- mail

This returns your Distinguished Name (DN). Open that record.

The common root of where all users are defined becomes and entry in the configuration "principalSearchRoots", as so:

principalSearchRoots = [
  "OU=Users,DC=example,DC=com",
]

2. Set the "principalSearchFilter" to some user-record attribute

It should match either:
  {0} for the username, for example: 'joeuser'
  {1} for the user's DN, for example: CN=Joe User,OU=Users,DC=example,DC=com
Examples:

principalSearchFilter = "cn={0}"

principalSearchFilter = "distinguishedName={1}"

3. Find your group memberships

This is typically an Attribute with name "groups" "memberOf", or "memberships". Open this record. The common root of each entry will identify where groups are defined in your LDAP structure. This becomes an entry in the "roleSearchRoots", as so:

roleSearchRoots = [
  "OU=Roles,DC=example,DC=com"
]

4. Set "roleSearchFilter" 

This is the name of the attribute which has the list of members by either:
  {0} for the username
  {1} for the user's DN
For example:

roleSearchFilter = "member={1}"

The remaining settings are:
  host -- the hostname of your LDAP server
  portNumber -- the port number of your LDAP service (usually port 389)
  systemPrincipal -- the Distinguished Name of the user allowed to access LDAP records
  systemPassword -- the password of the user allowed to access LDAP records
  secureCommunicationProfileName -- (optional) the name of the secure client profile, if communication to the LDAP server is to be encrypted.