10.5.3.6. LdapExtLoginModule

The org.jboss.security.auth.spi.LdapExtLoginModule is an alternate ldap login module implementation that uses searches for locating both the user to bind as for authentication as well as the associated roles. The roles query will recursively follow distinguished names (DNs) to navigate a hierarchical role structure.

The LoginModule options include whatever options your LDAP JNDI provider supports. Examples of standard property names are:

Context.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"
Context.SECURITY_PROTOCOL = "java.naming.security.protocol"
Context.PROVIDER_URL = "java.naming.provider.url"
Context.SECURITY_AUTHENTICATION = "java.naming.security.authentication"
Context.REFERRAL = "java.naming.referral"

The authentication happens in 2 steps:

An initial bind to the ldap server is done using the bindDN and bindCredential options. The bindDN is some user with the ability to search both the baseCtxDN and rolesCtxDN trees for the user and roles. The user DN to authenticate against is queried using the filter specified by the baseFilter attribute (see the baseFilter option description for its syntax).
2. The resulting user DN is then authenticated by binding to ldap server using the user DN as the InitialLdapContext environment Context.SECURITY_PRINCIPAL. The Context.SECURITY_CREDENTIALS property is either set to the String password obtained by the callback handler.

If this is successful, the associated user roles are queried using the rolesCtxDN, roleAttributeID, roleAttributeIsDN, roleNameAttributeID, and roleFilter options.

The full module properties include:

baseCtxDN: The fixed DN of the context to start the user search from.
bindDN: The DN used to bind against the ldap server for the user and roles queries. This is some DN with read/search permissions on the baseCtxDN and rolesCtxDN values.
bindCredential: The password for the bindDN. This can be encrypted if the jaasSecurityDomain is specified.
jaasSecurityDomain: The JMX ObjectName of the JaasSecurityDomain to use to decrypt the java.naming.security.principal. The encrypted form of the password is that returned by the JaasSecurityDomainencrypt64(byte{FOOTNOTE DEF }) method. The org.jboss.security.plugins.PBEUtils can also be used to generate the encrypted form.
baseFilter: A search filter used to locate the context of the user to authenticate. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a {0} expression is seen. This substitution behavior comes from the standard DirContext.search(Name, String, Object{FOOTNOTE DEF }, SearchControls cons) method. A common example for the search filter is (uid=).
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 (for example, for 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 login module callback 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}).
roleAttributeIsDN: A flag indicating whether the user's role attribute contains the fully distinguished name of a role object, or the users's 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 (for example, 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 should be set to true. The default value of this property is false.
roleAttributeID: The name of 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 the DN of the context to query for the roleNameAttributeID attribute. If the roleAttributeIsDN property is set to false, this property is the attribute name of the role name.
roleNameAttributeID: The name of 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 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.
searchTimeLimit: The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
searchScope: Sets the search scope to one of the strings. The default is SUBTREE_SCOPE.
- 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
allowEmptyPasswords: A flag indicating if empty(length==0) 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 to reject empty passwords, true to have the ldap server validate the empty password. The default is true.