org.jboss.security.auth.spi

Class LdapLoginModule

java.lang.Object

org.jboss.security.auth.spi.AbstractServerLoginModule

org.jboss.security.auth.spi.UsernamePasswordLoginModule

org.jboss.security.auth.spi.LdapLoginModule

All Implemented Interfaces:

LoginModule

public class LdapLoginModule
extends UsernamePasswordLoginModule

An implementation of LoginModule that authenticates against an LDAP server using JNDI, based on the configuration properties.

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 Context.SECURITY_PRINCIPAL is set to the distinguished name of the user as obtained by the callback handler and the Context.SECURITY_CREDENTIALS property is either set to the String password or Object credential depending on the useObjectCredential option.

Additional module properties include:

• principalDNPrefix, principalDNSuffix : A prefix and suffix to add to the username when forming the user distinguished name. This is useful if you prompt a user for a username and you don't want them to have to enter the fully distinguished name. Using this property and principalDNSuffix the userDN will be formed as:

      String userDN = principalDNPrefix + username + principalDNSuffix;
   

• useObjectCredential : indicates that the credential should be obtained as an opaque Object using the org.jboss.security.plugins.ObjectCallback type of Callback rather than as a char[] password using a JAAS PasswordCallback.
• rolesCtxDN : The fixed distinguished name to the context to search for user roles.
• userRolesCtxDNAttributeName : The name of an attribute in the user object that contains the distinguished name to the context to search for user roles. This differs from rolesCtxDN in that the context to search for a user's roles can be unique for each user.
• uidAttributeID : The name of the attribute that in the object containing the user roles that corresponds to the userid. This is used to locate the user roles.
• matchOnUserDN : A flag indicating if the search for user roles should match on the user's fully distinguished name. If false just the username is used as the match value. If true, the userDN is used as the match value.
• 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.
• 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.
• java.naming.security.principal (4.0.3+): This standard JNDI property if specified in the login configuration, it is used to rebind to the ldap server after user authentication for the role searches. This may be necessary if the user does not have permission to perform these queres. If specified, the java.naming.security.credentials provides the rebind credentials.
• java.naming.security.credentials (4.0.3+): This standard JNDI property if specified in the login configuration, it is used to rebind to the LDAP server after user authentication for the role searches along with the java.naming.security.principal value. This can be encrypted using the jaasSecurityDomain.
• jaasSecurityDomain (4.0.3+): 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.

A sample login config:

 testLdap {
 org.jboss.security.auth.spi.LdapLoginModule required
 java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
 java.naming.provider.url="ldap://ldaphost.jboss.org:1389/"
 java.naming.security.authentication=simple
 principalDNPrefix=uid=
 uidAttributeID=userid
 roleAttributeID=roleName
 principalDNSuffix=,ou=People,o=jboss.org
 rolesCtxDN=cn=JBossSX Tests,ou=Roles,o=jboss.org
 };

 testLdap2 {
 org.jboss.security.auth.spi.LdapLoginModule required
 java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
 java.naming.provider.url="ldap://ldaphost.jboss.org:1389/"
 java.naming.security.authentication=simple
 principalDNPrefix=uid=
 uidAttributeID=userid
 roleAttributeID=roleName
 principalDNSuffix=,ou=People,o=jboss.org
 userRolesCtxDNAttributeName=ou=Roles,dc=user1,dc=com
 };

 testLdapToActiveDirectory {
 org.jboss.security.auth.spi.LdapLoginModule required
 java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
 java.naming.provider.url="ldap://ldaphost.jboss.org:1389/"
 java.naming.security.authentication=simple
 rolesCtxDN=cn=Users,dc=ldaphost,dc=jboss,dc=org
 uidAttributeID=userPrincipalName
 roleAttributeID=memberOf
 roleAttributeIsDN=true
 roleNameAttributeID=name
 };
 

Version:

$Revision$

Author:

Scott.Stark@jboss.org

Field Summary

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

Method Summary

Methods

Modifier and Type	Method and Description
protected Group[]	getRoleSets() Overridden by subclasses to return the Groups that correspond to the to the role sets assigned to the user.
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<String,?> sharedState, Map<String,?> options) Override the superclass method to look for the following options after first invoking the super version.
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, getUsername, 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

Constructor Detail

LdapLoginModule

public LdapLoginModule()

Method Detail

initialize

public void initialize(Subject subject,
              CallbackHandler callbackHandler,
              Map<String,?> sharedState,
              Map<String,?> 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.