org.jboss.security.auth.spi

Class LdapExtLoginModule

java.lang.Object

org.jboss.security.auth.spi.AbstractServerLoginModule

org.jboss.security.auth.spi.UsernamePasswordLoginModule

org.jboss.security.auth.spi.LdapExtLoginModule

All Implemented Interfaces:

LoginModule

public class LdapExtLoginModule
extends UsernamePasswordLoginModule

The org.jboss.security.auth.spi.LdapExtLoginModule, added in jboss-4.0.3, 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" 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 __baseDN__ 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). # 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 odule 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 JaasSecurityDomain#encrypt64(byte[]) 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 substituion behavior comes from the standard __DirContext.search(Name, String, Object[], SearchControls cons)__ method. An common example search filter is "(uid={0})". __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__ : 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 (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 should 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. __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.

Version:

$Revision$

Author:

Andy Oliver, Scott.Stark@jboss.org

Field Summary

Fields

Modifier and Type	Field and Description
protected String	baseDN
protected String	baseFilter
protected String	bindCredential
protected String	bindDN
protected String	distinguishedNameAttribute
protected boolean	isPasswordValidated
protected boolean	parseRoleNameFromDN
protected boolean	parseUsername
protected int	recursion
protected String	referralUserAttributeIDToCheck
protected String	roleAttributeID
protected boolean	roleAttributeIsDN
protected String	roleFilter
protected String	roleNameAttributeID
protected String	rolesCtxDN
protected int	searchScope
protected int	searchTimeLimit
protected String	usernameBeginString
protected String	usernameEndString

Fields inherited from class org.jboss.security.auth.spi.AbstractServerLoginModule

callbackHandler, jbossModuleName, log, loginOk, options, principalClassModuleName, principalClassName, sharedState, subject, unauthenticatedIdentity, useFirstPass

Constructor Summary

Constructors

Constructor and Description
LdapExtLoginModule()

Method Summary

Modifier and Type	Method and Description
protected String	bindDNAuthentication(InitialLdapContext ctx, String user, Object credential, String baseDN, String filter)
protected Group[]	getRoleSets() Overridden by subclasses to return the Groups that correspond to the to the role sets assigned to the user.
protected String	getUsername()
protected String	getUsersPassword() Overridden to return an empty password string as typically one cannot obtain a user's password.
void	initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) Override the superclass method to look for the following options after first invoking the super version.
protected void	rolesSearch(LdapContext ctx, SearchControls constraints, String user, String userDN, int recursionMax, int nesting)
protected boolean	validatePassword(String inputPassword, String expectedPassword) Validate the inputPassword by creating a LDAP InitialContext with the SECURITY_CREDENTIALS set to the password.

Methods inherited from class org.jboss.security.auth.spi.UsernamePasswordLoginModule

createPasswordHash, getCredentials, getIdentity, getUnauthenticatedIdentity, getUsernameAndPassword, getValidateError, login, safeClose, setValidateError

Methods inherited from class org.jboss.security.auth.spi.AbstractServerLoginModule

abort, addValidOptions, checkOptions, commit, createGroup, createIdentity, getCallerPrincipalGroup, getUseFirstPass, logout

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

bindDN

protected String bindDN

bindCredential

protected String bindCredential

baseDN

protected String baseDN

baseFilter

protected String baseFilter

rolesCtxDN

protected String rolesCtxDN

roleFilter

protected String roleFilter

roleAttributeID

protected String roleAttributeID

roleNameAttributeID

protected String roleNameAttributeID

roleAttributeIsDN

protected boolean roleAttributeIsDN

parseRoleNameFromDN

protected boolean parseRoleNameFromDN

recursion

protected int recursion

searchTimeLimit

protected int searchTimeLimit

searchScope

protected int searchScope

distinguishedNameAttribute

protected String distinguishedNameAttribute

parseUsername

protected boolean parseUsername

usernameBeginString

protected String usernameBeginString

usernameEndString

protected String usernameEndString

isPasswordValidated

protected boolean isPasswordValidated

referralUserAttributeIDToCheck

protected String referralUserAttributeIDToCheck

Constructor Detail

LdapExtLoginModule

public LdapExtLoginModule()

Method Detail

initialize

public void initialize(Subject subject,
                       CallbackHandler callbackHandler,
                       Map sharedState,
                       Map options)

Description copied from class: UsernamePasswordLoginModule

Override the superclass method to look for the following options after first invoking the super version.

Specified by:

initialize in interface LoginModule

Overrides:

initialize in class UsernamePasswordLoginModule

Parameters:

subject - the Subject to update after a successful login.

callbackHandler - the CallbackHandler that will be used to obtain the the user identity and credentials.

sharedState - a Map shared between all configured login module instances

options - : option: hashAlgorithm - the message digest algorithm used to hash passwords. If null then plain passwords will be used. option: hashCharset - the name of the charset/encoding to use when converting the password String to a byte array. Default is the platform's default encoding. option: hashEncoding - the string encoding format to use. Defaults to base64. option: ignorePasswordCase: A flag indicating if the password comparison should ignore case. option: digestCallback - The class name of the DigestCallback DigestCallback implementation that includes pre/post digest content like salts for hashing the input password. Only used if hashAlgorithm has been specified. option: hashStorePassword - A flag indicating if the store password returned from #getUsersPassword() should be hashed . option: hashUserPassword - A flag indicating if the user entered password should be hashed. option: storeDigestCallback - The class name of the DigestCallback DigestCallback implementation that includes pre/post digest content like salts for hashing the store/expected password. Only used if hashStorePassword or hashUserPassword is true and hashAlgorithm has been specified.

getUsersPassword

protected String getUsersPassword()
                           throws LoginException

Overridden to return an empty password string as typically one cannot obtain a user's password. We also override the validatePassword so this is ok.

Specified by:

getUsersPassword in class UsernamePasswordLoginModule

Returns:

and empty password String

Throws:

LoginException

getRoleSets

protected Group[] getRoleSets()
                       throws LoginException

Overridden by subclasses to return the Groups that correspond to the to the role sets assigned to the user. Subclasses should create at least a Group named "Roles" that contains the roles assigned to the user. A second common group is "CallerPrincipal" that provides the application identity of the user rather than the security domain identity.

Specified by:

getRoleSets in class AbstractServerLoginModule

Returns:

Group[] containing the sets of roles

Throws:

LoginException

validatePassword

protected boolean validatePassword(String inputPassword,
                                   String expectedPassword)

Validate the inputPassword by creating a LDAP InitialContext with the SECURITY_CREDENTIALS set to the password.

Overrides:

validatePassword in class UsernamePasswordLoginModule

Parameters:

inputPassword - the password to validate.

expectedPassword - ignored

Returns:

true if the inputPassword is valid, false otherwise.

bindDNAuthentication

protected String bindDNAuthentication(InitialLdapContext ctx,
                                      String user,
                                      Object credential,
                                      String baseDN,
                                      String filter)
                               throws NamingException

Parameters:

ctx - - the context to search from

user - - the input username

credential - - the bind credential

baseDN - - base DN to search the ctx from

filter - - the search filter string

Returns:

the userDN string for the successful authentication

Throws:

NamingException

rolesSearch

protected void rolesSearch(LdapContext ctx,
                           SearchControls constraints,
                           String user,
                           String userDN,
                           int recursionMax,
                           int nesting)
                    throws NamingException

Parameters:

ctx -

constraints -

user -

userDN -

recursionMax -

nesting -

Throws:

NamingException

getUsername

protected String getUsername()

Overrides:

getUsername in class UsernamePasswordLoginModule