LdapExtLoginModule (Red Hat JBoss Enterprise Application Platform 6.4.19.GA public API)

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()

Constructors
Constructor and Description
`LdapExtLoginModule()`

Method Summary

Methods
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

Class LdapExtLoginModule

Field Summary

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

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

Field Detail

bindDN

bindCredential

baseDN

baseFilter

rolesCtxDN

roleFilter

roleAttributeID

roleNameAttributeID

roleAttributeIsDN

parseRoleNameFromDN

recursion

searchTimeLimit

searchScope

distinguishedNameAttribute

parseUsername

usernameBeginString

usernameEndString

isPasswordValidated

referralUserAttributeIDToCheck

Constructor Detail

LdapExtLoginModule

Method Detail

initialize

getUsersPassword

getRoleSets

validatePassword

bindDNAuthentication

rolesSearch

getUsername