Chapter 12. Login Modules

Distinguished Name (DN)

In Lightweight Directory Access Protocol (LDAP), the distinguished name uniquely identifies an object in a directory. Each distinguished name must have a unique name and location from all other objects, which is achieved using a number of attribute-value pairs (AVPs). The AVPs define information such as common names, organization unit, among others. The combination of these values results in a unique string required by the LDAP.

java.naming.factory.initial

InitialContextFactory implementation class name. This defaults to the Sun LDAP provider implementation com.sun.jndi.ldap.LdapCtxFactory.

java.naming.provider.url

LDAP URL for the LDAP server.

java.naming.security.authentication

Security protocol level to use. The available values include none, simple, and strong. If the property is undefined, the behavior is determined by the service provider.

java.naming.security.protocol

Transport protocol to use for secure access. Set this configuration option to the type of service provider (for example, SSL). If the property is undefined, the behavior is determined by the service provider.

java.naming.security.principal

Specifies the identity of the Principal for authenticating the caller to the service. This is built from other properties as described below.

java.naming.security.credentials

Specifies the credentials of the Principal for authenticating the caller to the service. Credentials can take the form of a hashed password, a clear-text password, a key, or a certificate. If the property is undefined, the behavior is determined by the service provider.

principalDNPrefix

Prefix added to the user name to form the user distinguished name . See principalDNSuffix for more info.

principalDNSuffix

Suffix added to the user name when forming the user distinguished name. This is useful if you prompt a user for a user name and you do not want the user to have to enter the fully distinguished name. Using this property and principalDNSuffix the userDN will be formed as principalDNPrefix + username + principalDNSuffix

rolesCtxDN

Fixed, distinguished name to the context for searching user roles.

userRolesCtxDNAttributeName

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.

roleAttributeID

Name of the attribute containing the user roles. If not specified, this defaults to roles.

roleAttributeIsDN

Flag indicating whether the roleAttributeID contains the fully distinguished name of a role object, or the role name. The role name is taken from the value of the roleNameAttributeId attribute of the context name by the distinguished name.

If true, the role attribute represents the distinguished name of a role object. If false, the role name is taken from the value of roleAttributeID. The default is false.

Note

In certain directory schemas (e.g., MS ActiveDirectory), role attributes in the user object are stored as DNs to role objects instead of simple names. For implementations that use this schema type, roleAttributeIsDN must be set to true.

roleNameAttributeID

Name of the attribute of the context pointed to by the roleCtxDN distinguished name value which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object's name attribute. The default is group.

uidAttributeID

Name of the attribute in the object containing the user roles that corresponds to the user ID. This is used to locate the user roles. If not specified this defaults to uid.

matchOnUserDN

Flag that specifies whether the search for user roles should match on the user's fully distinguished name. If true, the full userDN is used as the match value. If false, only the user name is used as the match value against the uidAttributeName attribute. The default value is false.

unauthenticatedIdentity

Principal name to assign to requests containing no authentication information. This behavior is inherited from the UsernamePasswordLoginModule superclass.

allowEmptyPasswords

A flag indicating if empty (length 0) passwords should be passed to the LDAP server. An empty password is treated as an anonymous log in by some LDAP servers, and this may not be a desirable feature. To reject empty passwords, set this to false . If set to true, the LDAP server will validate the empty password. The default is true.

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. Other supported values include:

• 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.

jaasSecurityDomain

The JMX ObjectName of the JaasSecurityDomain used to decrypt the java.naming.security.principal. The encrypted form of the password is that returned by the JaasSecurityDomainencrypt64(byte[]) method. The org.jboss.security.plugins.PBEUtils can also be used to generate the encrypted form.

LDAP Data Interchange Format (LDIF)

Plain text data interchange format used to represent LDAP directory content and update requests. Directory content is represented as one record for each object or update request. Content consists of add, modify, delete, and rename requests.

Distinguished Name (DN)

In Lightweight Directory Access Protocol (LDAP), the distinguished name uniquely identifies an object in a directory. Each distinguished name must have a unique name and location from all other objects, which is achieved using a number of attribute-value pairs (AVPs). The AVPs define information such as common names, organization unit, among others. The combination of these values results in a unique string required by the LDAP.

LdapExtLoginModule Properties

baseCtxDN

Specifies the fixed DN of the context to start the user search from.

bindDN

Specifies the DN used to bind against the LDAP server for the user and role queries. Set bindDN to a DN with read/search permissions on the baseCtxDN and rolesCtxDn properties.

bindCredential

The password for the bindDN. bindCredential can be encrypted if jaasSecurityDomain is specified. This property allows an external command to read the password. For example {EXT}cat file_with_password.

jaasSecurityDomain

The JMX ObjectName of the JaasSecurityDomain used to decrypt the java.naming.security.principal. The encrypted form of the password is that returned by the JaasSecurityDomainencrypt64(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 is substituted into the filter anywhere a {0} expression exists. This substitution behavior originates 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. This is not the DN of where the actual roles are; this is the DN of where the objects containing the user roles are. For example, in active directory, this is the DN where the user account is.

roleFilter

Search filter used to locate the roles associated with the authenticated user. The input username/userDN as obtained from the login module callback is substituted into the filter anywhere a {0} expression exists. The authenticated userDN is 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

Flag indicating whether the roleAttributeID contains the full DN of a role object, or the role name. The role name is derived from the value of the roleNameAttributeId attribute of the context name by the distinguished name.

If set to true, the role attribute represents the distinguished name of a role object. If set to false, the role name is taken from the value of roleAttributeID. The default is false.

Note

In certain directory schemas (e.g., MS ActiveDirectory), role attributes in the user object are stored as DNs to role objects instead of simple names. For implementations that use this schema type, roleAttributeIsDN must be set to true.

roleAttributeID

Name of the attribute containing the user roles. If roleAttributeIsDN 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

Name of the attribute of the context pointed to by the roleCtxDN distinguished name value which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object's name attribute. The default is group.

roleRecursion

Specifies how many levels the role search traverses a given matching context. The default is 0 (deactivated).

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. Other supported values include:

• 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 log in by some LDAP servers. If set to false, empty passwords are rejected. If set to true, the LDAP server validates the empty password. The default is true.

defaultRole

A role included for all authenticated users.

parseRoleNameFromDN

A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameAttributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.

parseUsername

A flag indicating if the DN is to be parsed for the username. If set to true, the DN is parsed for the username. If set to false the DN is not parsed for the username. This option is used together with usernameBeginString and usernameEndString.

usernameBeginString

Defines the string which is to be removed from the start of the DN to reveal the username. This option is used together with usernameEndString.

usernameEndString

Defines the string which is to be removed from the end of the DN to reveal the username. This option is used together with usernameBeginString.

distinguishedNameAttribute

Defines a distinguished name to provide a unique 'path' to any object in the LDAP database.

hashAlgorithm

Name of the java.security.MessageDigest algorithm to use to hash the password. There is no default so this option must be specified to enable hashing. Typical values are MD5 and SHA.

hashEncoding

String that specifies one of three encoding types: base64, hex or rfc2617. The default is base64.

hashCharset

Encoding character set used to convert the clear text password to a byte array. The platform default encoding is the default.

hashUserPassword

Specifies the hashing algorithm must be applied to the password the user submits. The hashed user password is compared against the value in the login module, which is expected to be a hash of the password. The default is true.

hashStorePassword

Specifies the hashing algorithm must be applied to the password stored on the server side. This is used for digest authentication, where the user submits a hash of the user password along with a request-specific tokens from the server to be compare. The hash algorithm (for digest, this would be rfc2617) is utilized to compute a server-side hash, which should match the hashed value sent from the client.

usersProperties

Name of the properties resource (file) containing the user name to password mappings. This defaults to <file_prefix>-users.properties.

rolesProperties

Name of the properties resource (file) containing the user name to roles mappings. This defaults to <file_prefix>-roles.properties.

dsJndiName

The JNDI name for the DataSource of the database containing the logical Principals and Roles tables. If not specified this defaults to java:/DefaultDS.

principalsQuery

The prepared statement query equivalent to: select Password from Principals where PrincipalID=?. If not specified this is the exact prepared statement that will be used.

rolesQuery

The prepared statement query equivalent to: select Role, RoleGroup from Roles where PrincipalID=?. If not specified this is the exact prepared statement that will be used.

ignorePasswordCase

A boolean flag indicating if the password comparison should ignore case. This can be useful for hashed password encoding where the case of the hashed password is not significant.

principalClass

An option that specifies a Principal implementation class. This must support a constructor taking a string argument for the principal name.

transactionManagerJndiName

The JNDI name of the transaction manager used by the login module. If no value is provided, the default java:/TransactionManager is used.

suspendResume

A boolean flag indicating whether an active transaction associated with the current thread should be suspended during a database operation and resumed after the operation is completed. The default value is true.

principal

This is the name to use for the SimplePrincipal all users are authenticated as. The principal name defaults to guest if no principal option is specified.

roles

This is a comma-delimited list of roles that will be assigned to the user.

roleName

Name of the role to use as the run as role during log in phase. If not specified a default of nobody is used.

multi-threaded

Value that specifies the way login threads connect to principal and credential storage sources. When set to true, each login thread has its own principal and credential storage and each separate thread must perform its own log in. This is useful in client environments where multiple user identities are active in separate threads. When set to false the login identity and credentials are global variables that apply to all threads in the VM. The default setting is false.

password-stacking

Activates client-side authentication of clients using other login modules such as the LdapLoginModule. When password-stacking option is set to useFirstPass, the module first looks for a shared user name and password using javax.security.auth.login.name and javax.security.auth.login.password respectively in the login module shared state map. This allows a module configured prior to this one to establish a valid JBoss user name and password.

restore-login-identity

Value that specifies whether the SecurityAssociation principal and credential seen on entry to the login() method are saved and restored on either abort or logout. This is necessary if you must change identities and then restore the original caller identity. If set to true, the principal and credential information is saved and restored on abort or logout. If set to false, abort and logout clear the SecurityAssociation. The default value is false.

rolesProperties

Name of the properties file that defines the addition/substitution rules; the value defines the file in the form as located using Classloader or with its absolute location given by the java.net.url pattern (for example, file:/rolesMap.properties)

replaceRole

Flag determining if the key role is replaced with the mapped roles or the mapped roles are added to the key role (set to true to have the key role replaced with the mapped roles)