User authorization with LDAP on JBoss

This document describes how to configure JBoss Application Server to use LDAP for both user authentication and authorization. This is an advanced option which does not apply to most installations. If you "only want to configure LDAP", you should refer to Configure JBoss authentication method installation option and not this document.

Authentication is the process of establishing the identity of a user. This is typically done with a user name and a password. Authorization is the process of deciding if the user is allowed to log on to Extended Server and takes place after the user has been authenticated.

Normally in Extended Server, users are authorized using Oracle database roles. With the procedure described here, users are authorized based on membership of LDAP groups instead.

Note: The procedure describe here makes manual changes to the JBoss server instance. All those changes will be lost if the instance is reconfigured using the installation tool.

Prerequisites

Actions

  1. Stop the JBoss Application Server instance you want to reconfigure.
  2. Open <ifs_home>\jboss\server\<instance_name>\conf\login-config.xml file in a text editor, preferably one that supports XML syntax highlighting.
  3. Locate the <application-policy name="IFSApplications"> section of the file.
  4. From the <authentication> sub-section, remove (or disable by commenting out) all <login-module> configuration entries.
  5. Add the following <login-module> configuration to the <authentication> section:
    <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="requisite" >
      <module-option name="java.naming.provider.url">ldap://ldap_server_hostname:389</module-option>
      <module-option name="bindDN">userid</module-option>
      <module-option name="bindCredential">password</module-option>
      <module-option name="baseCtxDN">CN=Users,DC=company,DC=com</module-option>
      <module-option name="baseFilter">(sAMAccountName={0})</module-option>
      <module-option name="rolesCtxDN">CN=Users,DC=company,DC=com</module-option>
      <module-option name="roleFilter">(sAMAccountName={0})</module-option>
      <module-option name="roleAttributeID">memberOf</module-option>
      <module-option name="roleAttributeIsDN">true</module-option>
      <module-option name="roleNameAttributeID">cn</module-option>
      <module-option name="roleRecursion">0</module-option>
      <module-option name="searchScope">SUBTREE_SCOPE</module-option>
      <module-option name="allowEmptyPasswords">false</module-option>
    </login-module>
    This configuration is an example for Microsoft Active Directory. Other LDAP servers may require more configuration changes than described in this document. Please consult the documentation for JBoss Application Server for more information.
  6. Complete the configuration for your installation. At minimum, the following module options' values needs to be edited: java.naming.provider.url, bindDN, bindCredential, baseCtxDN, rolesCtxDN. See Login module options below for more information on the options.
  7. Save the file.
  8. Start the JBoss Application Server instance.

Login module options

The following module options are available for the org.jboss.security.auth.spi.LdapExtLoginModule login module.

Option Description
java.naming.provider.url The address to the LDAP server to use in the form ldap://<hostname>:<port>. Default port number for LDAP is 389.
bindDN The distinguished name (DN) used to bind against the LDAP server for the user and
roles queries. This is some user with read/search permissions on the baseCtxDN and
rolesCtxDN values.
bindCredential The password for the bindDN user.
baseCtxDN The fixed DN of the context to start the user search from.
baseFilter A search filter used to locate the context of the user to authenticate. The input username/userDN as obtained from the client application will be substituted into the filter anywhere a "{0}" expression is seen.
rolesCtxDN The fixed DN of the context to search for user roles. Consider that this is not the Distinguished Name of where the actual roles are; rather, this is the DN of where the objects containing the user roles are (e.g. for Microsoft Active Directory, this is the DN where the user account is).
roleFilter A search filter used to locate the roles associated with the authenticated user. The input username/userDN as obtained from the client application will be substituted into the filter anywhere a "{0}" expression is seen. The authenticated userDN will be substituted into the filter anywhere a "{1}" is seen. An example search filter that matches on the input username is: "(member={0})". An alternative that matches on the authenticated userDN is: "(member={1})".
roleAttributeID The name of the attribute of the role object which corresponds to the name of the role. If the roleAttributeIsDN option is set to true, this property is used to find the role object's name attribute. If the roleAttributeIsDN option is set to false, this property is ignored.
roleAttributeIsDN A flag indicating whether the user's role attribute contains the fully distinguished name of a role object, or the users' role attribute contains the role name. If false, the role name is taken from the value of the user's role attribute. If true, the role attribute represents the distinguished name of a role object. The role name is taken from the value of the roleNameAttributeID attribute of the corresponding object. In certain directory schemas (e.g., Microsoft Active Directory), role (group) attributes in the user object are stored as DNs to role objects instead of as simple names, in which case, this property must be set to true. The default value of this property is false.
roleNameAttributeID The name of the attribute of the role object which corresponds to the name of the role. If the roleAttributeIsDN property is set to true, this property is used to find the role object's name attribute. If the roleAttributeIsDN property is set to false, this property is ignored.
roleRecursion How deep the role search will go below a given matching context. Disable with 0, which is the default.
searchScope Sets the search scope to one of the strings:
  • OBJECT_SCOPE : only search the named roles context.
  • ONELEVEL_SCOPE : search directly under the named roles context.
  • SUBTREE_SCOPE : If the roles context is not a DirContext, search only the
    object. If the roles context is a DirContext, search the subtree rooted at the
    named object, including the named object itself

The default is SUBTREE_SCOPE.

searchTimeLimit The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
allowEmptyPasswords A flag indicating if empty passwords should be passed to the LDAP server. An empty password is treated as an anonymous login by some LDAP servers and this may not be a desirable feature. Set this to false (recommended) to reject empty passwords, true to have the LDAP server validate the empty password. The default is true.

In addition, the login module options include whatever options your LDAP JNDI provider supports. Please see the documentation for Java Naming and Directory Interfaces (JNDI) for more information.

Helpful tools

An LDAP browsing tool is an excellent help for examining the structure of your LDAP server. Softerra has one called LDAP Browser, available at www.ldapbrowser.com.

Wireshark, http://www.wireshark.org, is a network analyzer (also known as a sniffer) that can be used to see how the JBoss login module searches the LDAP server for users and roles. If a configuration isn't working, this tool can be very helpful in discovering in which stage there is a problem (authentication or authorization or if there is some other problem).