8.2. Cached LDAP Authorization Plug-In

Overview

Using the cached LDAP authorization plug-in, you can configure a broker to retrieve its authorization data from an X.500 directory server. For better efficiency, this plug-in caches authorization data in the broker and provides support for updating the cached data at regular intervals.

Updating the cache

Two alternative mechanisms for updating the authorization cache are supported:
  • Push mechanism—some LDAP directory server implementations support a persistent search feature, which enables applications to receive live updates from the LDAP server (push mechanism). By default, the cached LDAP authorization plug-in attempts to register with the LDAP server to receive these updates.
  • Pull mechanism—if your LDAP directory server does not support live updates, you can configure the cached LDAP authorization plug-in to poll the LDAP server at regular intervals instead (pull mechanism). To enable the pull mechanism, you must set the refreshInterval property on the cached LDAP authorization plug-in.

Sample configuration

Example 8.3, “Cached LDAP Authorization Plug-In Configuration” shows an example of how to configure the cached LDAP authorization plug-in. The authorizationPlugin element must be added as a child of the plugins element.

Example 8.3. Cached LDAP Authorization Plug-In Configuration

<beans ... >
  <broker ... >
    ...
    <plugins>
      ...
      <authorizationPlugin>
          <map>
            <cachedLDAPAuthorizationMap
                  legacyGroupMapping="false"
                  connectionURL="ldap://localhost:10389"
                  connectionUsername="uid=admin,ou=system"
                  connectionPassword="secret"
                  queueSearchBase="ou=Queue,ou=Destination,ou=ActiveMQ,ou=system"
                  topicSearchBase="ou=Topic,ou=Destination,ou=ActiveMQ,ou=system"
                  tempSearchBase="ou=Temp,ou=Destination,ou=ActiveMQ,ou=system"
                  refreshInterval="20000"
                  />
          </map>
      </authorizationPlugin>
    </plugins>
    ...
  </broker>
</beans>

Configuration properties

The cached LDAP authorization plug-in supports the following properties:
adminPermissionGroupSearchFilter
Specifies the filter used to search for admin permission groups. This filter is used when searching under the nodes specified by queueSearchBase, topicSearchBase, or tempSearchBase, to obtain the permission groups for queues, topics, or temporary destinations, respectively.
Default is (cn=Admin).
authentication
The authentication method to use when connecting to the LDAP server.
Default is simple.
connectionPassword
The password that matches the DN from connectionUsername. In the directory server, the password is normally stored as a userPassword attribute in the corresponding directory entry.
Default is secret.
connectionProtocol
The connection protocol to use when connecting to the LDAP server.
Default is s.
connectionURL
Specifies the location of the directory server using an LDAP URL, ldap://Host:Port.
Default is ldap://localhost:1024.
connectionUsername
The DN of the user that opens the connection to the directory server.
Default is uid=admin,ou=system.
groupClass
Type of the class that implements the role principal. For example, in order to reuse roles defined for the Apache Karaf JAAS authentication plug-in, you would need to set this property to org.apache.karaf.jaas.boot.principal.RolePrincipal.
Default is org.apache.activemq.jaas.GroupPrincipal.
groupNameAttribute
Specifies which attribute of a permission group node is interpreted as the group name.
Default is cn.
groupObjectClass
Specifies the object class of the LDAP nodes used to store permission groups. Typical values are groupOfNames or groupOfUniqueNames.
Default is groupOfNames.
legacyGroupMapping
If true, specifies that the role members of a privilege group must be specified using just the Common Name RDN, cn=CNValue, of the role group; or if false, specifies that the role members of a privilege group must be specified using the full Distinguished Name.
Default is true.
permissionGroupMemberAttribute
Specifies which attribute of a permission group node defines a member. For example, if the groupObjectClass is set to groupOfNames, this attribute should usually be set to member. Alternatively, if the groupObjectClass is set to groupOfUniqueNames, this attribute should usually be set to uniquemember.
Default is member.
queueSearchBase
The base DN of queue authorization entries.
Default is ou=Queue,ou=Destination,ou=ActiveMQ,ou=system.
readPermissionGroupSearchFilter
Specifies the filter used to search for read permission groups. This filter is used when searching under the nodes specified by queueSearchBase, topicSearchBase, or tempSearchBase, to obtain the permission groups for queues, topics, or temporary destinations, respectively.
Default is (cn=Read).
refreshDisabled
If true, disables cache refreshing.
Default is false.
refreshInterval
Time interval between refreshes of the cache, expressed in milliseconds (where the cache is refreshed by pulling data from the LDAP server). The special value, -1, disables the pull mechanism for refreshing the cache (but does not affect the push mechanism, if the LDAP server supports it).
Default is -1.
tempSearchBase
The base DN of authorization entries for temporary destinations.
Default is ou=Temp,ou=Destination,ou=ActiveMQ,ou=system.
topicSearchBase
The base DN of topic authorization entries.
Default is ou=Topic,ou=Destination,ou=ActiveMQ,ou=system.
userNameAttribute
Specifies which attribute of a user node is interpreted as the username.
Default is uid.
userObjectClass
Specifies the object class of the LDAP nodes used to store users.
Default is person.
writePermissionGroupSearchFilter
Specifies the filter used to search for write permission groups. This filter is used when searching under the nodes specified by queueSearchBase, topicSearchBase, or tempSearchBase, to obtain the permission groups for queues, topics, or temporary destinations, respectively.
Default is (cn=Write).

Authorization settings for different directory servers

The most significant differences between directory servers arise in connection with the object class settings in the cached LDAP authorization plug-in. The precise settings depend ultimately on the organisation of your DIT, but the following table gives an idea of the typical object class settings required for different directory servers:
Directory ServerObject Class Settings
389-DS
Red Hat DS 
userObjectClass="inetorgperson"
groupObjectClass="groupOfUniqueNames"
permissionGroupMemberAttribute="uniqueMember"
Apache DS 
userObjectClass="person"
groupObjectClass="groupOfNames"
permissionGroupMemberAttribute="member"