Appendix A. Advanced LDAP Login Module: Full LDAP Authentication
The JBoss Negotiation project includes the AdvancedLdapLoginModule to handle the LDAP role searching requirements.
The AdvancedLdapLoginModule is based on the LdapExtLoginModule; however, AdvancedLdapLoginModule differs in the following aspects:
- The accumulated subject roles do no include the role name of the first matching context.
- When the roleAttributeIsDN module property is set to
false, the recursive role search is disabled even if the recurseRoles module option is set totrue.
You can use the AdvancedLdapLoginModule module in a chained configuration with the SPNEGOLoginModule to allow a GSSAPI authentication to allow authentication through LDAP (refer to Section 2.4, “Role Mapping” or use the module for a full authentication through LDAP. You can also configure it to skip the user search, the authentication, or the role search if required.
A.1. Configuration
The fully qualified classname of the new login module is
org.jboss.security.negotiation.AdvancedLdapLoginModule.
Warning
In Beta releases the class name was
org.jboss.security.negotiation.spnego.AdvancedLdapLoginModule. The login module is still available under this name; however, it has been deprecated and will be removed in a future release.
The AdvancedLdapLoginModule supports password-stacking: if you want to use the module in conjunction with other login modules, make sure the password-stacking property is set to
useFirstPass.
A.1.1. Defining Initial LDAP Context
First, you need to define the user credentials, which are used to obtain the InitialLdapContext and then used to search for the user and the user roles.
Note
The login module supports obtaining this InitialLdapContext using a username and credential or using GSSAPI for a previously authenticated user. Here we use the user credentials. For configuration with GSSAPI, refer to Section 2.4, “Role Mapping”.
To authenticate with a username and password the following define the following settings:
- bindDN
- defines the DN used to bind to the LDAP server. This is a DN with read/search permissions to the defined baseCtxDN and rolesCtxDN.
- bindCredential
- defines the bindDN password. The password can be encrypted if the jaasSecurityDomain is specified.
- jaasSecurityDomain
- defines the JMX ObjectName of the jaasSecurityDomain. This is the jaasSecurityDomain used to decrypt the java.naming.security.principal. The JaasSecurityDomain#encrypt64(byte[]) method of the domain returns the encrypted form of the password. You can use also org.jboss.security.plugins.PBEUtils to generate the encrypted form.
A.1.2. Defining DN Search
After the module has created the LDAP initial context, it takes the provided username and searches for the user DN. To define the properties of the search, provide the following properties:
- baseCtxDN
- defines 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 located but the DN of where the objects containing the user roles are located (that is, for active directory, this is the DN with the user account).
- baseFilter
- defines the search filter used to locate the context of the user to authenticate. The input username/userDN as obtained from the login module callback substitutes the
{0}expression. This substitution behavior comes from the standard DirContext?.search(Name, String, Object[], SearchControls? cons) method. An common example search filter is"(uid={0}) - searchTimeLimit
- defines the timeout for the user and role searches in milliseconds (defaults to 10000, that is 10 seconds).
Note
To disable the user DN search omit the
baseCtxDN property: the provided username will be used as the DN in this login module.
A.1.3. User Authentication
Note
If the LDAP login module is not the first login module and a previous login module has already authenticated the user, the user authentication is skipped.
If no previous login module has authenticated the user this step takes the User DN from the User DN search and their provided credential and attempts to create a new InitialLdapContext and verify that the User DN and credential combination is valid.
For user authentication, you can define the following property:
- allowEmptyPassword
- If empty (length==0) passwords are passed to the LDAP server. An empty password is treated as an anonymous log in by an LDAP servers. Set the property to
falseto reject empty passwords or totrueto allow the LDAP server to validate an empty password (the default isfalse).
A.1.4. Defining Role Search
The LDAP login module passes the properties to define the search for a particular user and its roles to the LDAP server.
Important
The following role search settings are similar to the LdapExtLoginModule settings; however, the recursion now finds the roles listed within a DN.
- 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 active directory, this is the DN where the user account is)
- roleFilter
- defines a search filter used to locate the roles associated with the authenticated user. The input username/userDN as obtained from the login module callback substitutes the
{0}expression in the filter definition. The authenticated userDN substitutes the{1}in the filter definition. An example search filter that matches the input username is(member={0}). An alternative that matches the authenticated userDN is(member={1}).Note
If you omit the roleFilter attribute, the role search will use the UserDN as the DN to obtain the roleAttributeID value. - roleAttributeID
- defines the role attribute of the context that corresponds to the name of the role. If the roleAttributeIsDN property is set to
true, this property is the DN of the context to query for the roleNameAttributeID attribute. If the roleAttributeIsDN property is set tofalse, this property is the attribute name of the role name. - roleAttributeIsDN
- defines if the role attribute contains the fully distinguished name of a role object or the role name. If
false, the role name is taken from the value of the user's role attribute. Iftrue, 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 (for example, Microsoft Active Directory), role (group)attributes in the user object are stored as DNs to role objects and not as simple names. In such case, set this property totrue. The default value of this property isfalse. - roleNameAttributeID
- defines the role attribute of the context which corresponds to the name of the role. If the roleAttributeIsDN property is set to
true, this property is used to find the name attribute of the role object. If the roleAttributeIsDN property is set tofalse, this property is ignored. - recurseRoles
- Enables a recursive role search. The login module tracks already added roles to handle cyclic references.
- searchScope
- sets the search scope to one of the following (the default value is
SUBTREE_SCOPE):- OBJECT_SCOPE - searches the named roles context only.
- ONELEVEL_SCOPE - searches directly in the named roles context.
- SUBTREE_SCOPE - searches only the object if the role context is not a DirContext?. If the roles context is a DirContext?, the subtree rooted at the named object and the named object itself are searched.
- searchTimeLimit
- defines the timeout for the user and role searches in milliseconds (defaults to 10000, that is 10 seconds).
Note
Both searches use the same searchTimeLimit setting.
