JAAS LDAP Authentication Plug-In

Overview

The LDAP authentication plug-in enables you to perform authentication by checking the incoming credentials against user data stored in a central X.500 directory server. For systems that already have an X.500 directory server in place, this means that you can rapidly integrate FUSE Message Broker with the existing security database and user accounts can be managed using the X.500 system.

Specifying the login.config file location

The simplest way to make the login configuration available to JAAS is to add the directory containing the file, login.config, to your CLASSPATH.

Alternatively, you can set the java.security.auth.login.config system property at the command line, setting it to the pathname of the login configuration file (for example, edit the bin/activemq script, adding an option of the form, -Djava.security.auth.login.config=Value to the Java command line). If you are working on the Windows platform, note that the pathname of the login configuration file must use forward slashes, /, in place of backslashes, \.

login.config file

Example 3.5 shows an example of a login entry for the LDAP authentication plug-in, connecting to a directory repository with the URL, ldap://localhost:10389.

Example 3.5. LDAP Login Entry

LDAPLogin {
    org.apache.activemq.jaas.LDAPLoginModule required
        debug=true
        initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
        connectionURL="ldap://localhost:10389"
        connectionUsername="uid=admin,ou=system"
        connectionPassword=secret
        connectionProtocol=""
        authentication=simple
        userBase="ou=users,ou=system"
        userSearchMatching="(uid={0})"
        userSearchSubtree=false
        roleSearchMatching="(uid={1})"
        ;
};

The preceding login entry is configured to search for users under the ou=users,ou=system level in the Directory Information Tree (DIT). For example, an incoming username, jdoe, would match the entry whose DN is uid=jdoe,ou=users,ou=system.

LDAP login entry options

The LDAP login entry supports the following options:

debug—boolean debugging flag. If true, enable debugging. This is used only for testing or debugging. Normally, it should be set to false, or omitted.
initialContextFactory—(mandatory) must always be set to com.sun.jndi.ldap.LdapCtxFactory.
connectionURL—(mandatory) specify the location of the directory server using an ldap URL, ldap://Host:Port. You can optionally qualify this URL, by adding a forward slash, /, followed by the DN of a particular node in the directory tree. For example, ldap://ldapserver:10389/ou=system.
connectionUsername—(optional)the DN of the user that opens the connection to the directory server. For example, uid=admin,ou=system.
Directory servers generally require clients to present username/password credentials in order to open a connection.
connectionPassword—(optional)the password that matches the DN from connectionUsername. In the directory server, in the DIT, the password is normally stored as a userPassword attribute in the corresponding directory entry.
connectionProtocol—(mandatory)currently, the only supported value is a blank string. In future, this option will allow you to select the Secure Socket Layer (SSL) for the connection to the directory server.
Note
This option must be set explicitly to an empty string, because it has no default value.
authentication—(mandatory)can take either of the values, simple or none.
userBase—(mandatory)selects a particular subtree of the DIT to search for user entries. The subtree is specified by a DN, which specifes the base node of the subtree. For example, by setting this option to ou=users,ou=system, the search for user entries is restricted to the subtree beneath the ou=users,ou=system node.
userSearchMatching—(mandatory)specifies an LDAP search filter, which is applied to the subtree selected by userBase. Before passing to the LDAP search operation, the string value you provide here is subjected to string substitution, as implemented by the java.text.MessageFormat class. Essentially, this means that the special string, {0}, is substituted by the username, as extracted from the incoming client credentials.
After substitution, the string is interpreted as an LDAP search filter, where the LDAP search filter syntax is defined by the IETF standard, RFC 2254. A short introduction to the search filter syntax is available from Sun's JNDI tutorial, Search Filters.
For example, if this option is set to (uid={0}) and the received username is jdoe, the search filter becomes (uid=jdoe) after string substitution. If the resulting search filter is applied to the subtree selected by the user base, ou=users,ou=system, it would match the entry, uid=jdoe,ou=users,ou=system (and possibly more deeply nested entries, depending on the specified search depth—see the userSearchSubtree option).
userSearchSubtree—(optional)specify the search depth for user entries, relative to the node specified by userBase. This option can take boolean values, as follows:
- false—(default) try to match one of the child entries of the userBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE).
- true—try to match any entry belonging to the subtree of the userBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).
userRoleName—(optional)specifies the name of the multi-valued attribute of the user entry that contains a list of role names for the user (where the role names are interpreted as group names by the broker's authorization plug-in). If you omit this option, no role names are extracted from the user entry.
roleBase—if you want to store role data directly in the directory server, you can use a combination of role options (roleBase, roleSearchMatching, roleSearchSubtree, and roleName) as an alternative to (or in addition to) specifying the userRoleName option.
This option selects a particular subtree of the DIT to search for role entries. The subtree is specified by a DN, which specifes the base node of the subtree. For example, by setting this option to ou=roles,ou=system, the search for user entries is restricted to the subtree beneath the ou=roles,ou=system node.
roleSearchMatching—(mandatory)specifies an LDAP search filter, which is applied to the subtree selected by roleBase. This works in a similar manner to the userSearchMatching option, except that it supports two substitution strings, as follows:
- {0} substitutes the full DN of the matched user entry (that is, the result of the user search). For example, for the user, jdoe, the substituted string could be uid=jdoe,ou=users,ou=system.
- {1} substitutes the received username. For example, jdoe.
For example, if this option is set to (uid={1}) and the received username is jdoe, the search filter becomes (uid=jdoe) after string substitution. If the resulting search filter is applied to the subtree selected by the role base, ou=roles,ou=system, it would match the entry, uid=jdoe,ou=roles,ou=system (and possibly more deeply nested entries, depending on the specified search depth—see the roleSearchSubtree option).
Note
This option must always be set, even if role searching is disabled, because it has no default value.
roleSearchSubtree—(optional)specify the search depth for role entries, relative to the node specified by roleBase. This option can take boolean values, as follows:
- false—(default) try to match one of the child entries of the roleBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE).
- true—try to match any entry belonging to the subtree of the roleBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).
roleName—(optional)specifies the name of the multi-valued attribute of the role entry that contains a list of role names for the current user. If you omit this option, the role search feature is effectively disabled.

	Note
This option must be set explicitly to an empty string, because it has no default value.

	Note
This option must always be set, even if role searching is disabled, because it has no default value.

<beans>
  <broker ...>
    ...
    <plugins>
      <jaasAuthenticationPlugin configuration="LDAPLogin" />
    </plugins>
    ...
  </broker>
</beans>

The configuration attribute specifies the label of a login entry from the login configuration file (for example, see Example 3.5). In the preceding example, the LDAPLogin login entry is selected.