Chapter 4. Login Modules With External Identity Store

4.1. Database Login Module

Short name: Database

Full name: org.jboss.security.auth.spi.DatabaseServerLoginModule

Parent: UsernamePassword Login Module

The Database login module is a JDBC login module that supports authentication and role mapping. This login module is used if user name, password and role information are stored in a relational database. This works by providing a reference to logical tables containing Principals and Roles in the expected format.

Table 4.1. Database Login Module Options

OptionTypeDefaultDescription

dsJndiName

A JNDI resource

java:/DefaultDS

The name of the JNDI resource storing the authentication information.

principalsQuery

prepared SQL statement

select Password from Principals where PrincipalID=?

The prepared SQL query to obtain the information about the principal.

rolesQuery

prepared SQL statement

none

The prepared SQL query to obtain the information about the roles. It should be equivalent to query 'select Role, RoleGroup from Roles where PrincipalID=?', where Role is the role name and the RoleGroup column value should always be either Roles with a capital R or CallerPrincipal.

suspendResume

boolean

true

Whether any existing JTA transaction should be suspended during database operations.

transactionManagerJndiName

JNDI Resource

java:/TransactionManager

The JNDI name of the transaction manager used by the login module.

4.2. DatabaseUsers Login Module

Short name: DatabaseUsers

Full name: org.jboss.security.DatabaseUsers

Alias to Database Login Module for compatibility reasons.

4.3. Ldap Login Module

Short name: Ldap

Full name: org.jboss.security.auth.spi.LdapLoginModule

Parent: UsernamePassword Login Module

The Ldap login module is a login module implementation that authenticates against an LDAP server. The security subsystem connects to the LDAP server using connection information, a java.naming.security.principal that has permissions to search both the baseCtxDN and rolesCtxDN trees for the user and roles, provided using a JNDI initial context. When a user attempts to authenticate, the Ldap login module connects to the LDAP server, and passes the user’s credentials to the LDAP server.

These credentials are formed by concatenating principalDNPrefix, the user input, and principalDNSuffix. For instance, consider the following scenario.

  1. principalDNPrefix is set to uid=.
  2. principalDNSuffix is set to ,ou=People,dc=jboss,dc=org.

If the user input is set to jduke, then the search string is uid=jduke,ou=People,dc=jboss,dc=org. If the user input is instead jduke,ou=Employees, then the search string would be uid=jduke,ou=Employees,ou=People,dc=jboss,dc=org.

Important

Any user input is transformed into a string before the search is performed. Due to this any special characters, such as commas, must be escaped for the search to function successfully.

Upon successful authentication, an InitialLDAPContext is created for that user within JBoss EAP, populated with the user’s roles.

Table 4.2. Ldap Login Module Options

OptionTypeDefaultDescription

principalDNPrefix

String

 

Prefix added to the user name to form the user DN. You can prompt the user for a user name and build the fully qualified DN by using the principalDNPrefix and principalDNSuffix.

principalDNSuffix

String

 

Suffix added to the user name to form the user DN. You can prompt the user for a user name and build the fully qualified DN by using the principalDNPrefix and principalDNSuffix.

rolesCtxDN

fully qualified DN

none

The fully qualified DN for the context to search for user roles.

userRolesCtxDNAttributeName

attribute

none

The attribute in the user object that contains the DN for the context to search for user roles. This differs from rolesCtxDN in that the context to search for a user’s roles may be unique for each user.

roleAttributeID

attribute

roles

Name of the attribute containing the user roles.

roleAttributeIsDN

true or false

false

Whether or not the roleAttributeID contains the fully qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.

roleNameAttributeID

attribute

name

Name of the attribute within the roleCtxDN context 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.

uidAttributeID

attribute

uid

Name of the attribute in the UserRolesAttributeDN that corresponds to the user ID. This is used to locate the user roles.

matchOnUserDN

true or false

false

Whether or not the search for user roles should match on the user’s fully distinguished DN or the user name only. If true, the full user DN is used as the match value. If false, only the user name is used as the match value against the uidAttributeName attribute.

allowEmptyPasswords

true or false

false

Whether to allow empty passwords. Most LDAP servers treat empty passwords as anonymous login attempts. To reject empty passwords, set this to false.

searchTimeLimit

integer

10000, or 10 seconds

The timeout in milliseconds for user or role searches.

searchScope

One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE

SUBTREE_SCOPE

The search scope to use.

jaasSecurityDomain

String

none

The JMX ObjectName of the JaasSecurityDomain used to decrypt the java.naming.security.credentials. The encrypted form of the password is returned by the decode64(String) method which is called on the object passed in this option.

Note

For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.

Note

While this login module does inherit the ignorePasswordCase option from its parent, UsernamePassword Login Module, it is not used by this specific login module.

4.4. LdapExtended Login Module

Short name: LdapExtended

Full name: org.jboss.security.auth.spi.LdapExtLoginModule

Parent: UsernamePassword Login Module

The LdapExtended login module searches for the user to bind, as well as the associated roles, for authentication. The roles query recursively follows DNs to navigate a hierarchical role structure. The login module options include whatever options are supported by the chosen LDAP JNDI provider supports.

The authentication happens in two steps:

  1. An initial bind to the LDAP server is done using the bindDN and bindCredential options. The bindDN is an LDAP 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.
  2. The resulting user DN is authenticated by binding to the LDAP server using the user DN as a principal name and the password obtained by the callback handler as the principal’s credentials.

Table 4.3. LdapExtended Login Module Options

OptionTypeDefaultDescription

baseCtxDN

fully qualified DN

none

The fixed DN of the top-level context to begin the user search.

bindCredential

String, optionally encrypted

none

Used to store the credentials for the DN.

bindDN

fully qualified DN

none

The DN used to bind against the LDAP server for the user and roles queries. This DN needs read and search permissions on the baseCtxDN and rolesCtxDN values.

baseFilter

LDAP filter String

none

A search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).

jaasSecurityDomain

String

none

The JMX ObjectName of the JaasSecurityDomain used to decrypt the password.

rolesCtxDN

fully qualified DN

none

The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.

roleFilter

LDAP filter String

none

A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

roleAttributeID

attribute

role

Name of the attribute containing the user roles.

roleAttributeIsDN

true or false

false

Whether or not the roleAttributeID contains the fully qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.

defaultRole

Role name

none

A role included for all authenticated users

parseRoleNameFromDN

true or false

false

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

true or false

false

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

usernameBeginString

String

none

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 and only taken into account if parseUsername is set to true.

usernameEndString

String

none

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 and only taken into account if parseUsername is set to true.

roleNameAttributeID

attribute

name

Name of the attribute within the roleCtxDN context 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.

distinguishedNameAttribute

attribute

distinguishedName

The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters, backslash for example, that prevent correct user mapping. If the attribute does not exist, the entry’s DN is used.

roleRecursion

integer

0

The numbers of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.

searchTimeLimit

integer

10000, or 10 seconds

The timeout in milliseconds for user or role searches.

searchScope

One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE

SUBTREE_SCOPE

The search scope to use.

allowEmptyPasswords

true or false

false

Whether to allow empty passwords. Most LDAP servers treat empty passwords as anonymous login attempts. To reject empty passwords, set this to false.

referralUserAttributeIDToCheck

attribute

none

If you are not using referrals, this option can be ignored. When using referrals, this option denotes the attribute name which contains users defined for a certain role, for example member, if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

Note

For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.

Note

While this login module does inherit the ignorePasswordCase option from its parent, UsernamePassword Login Module, it is not used by this specific login module.

Note

In cases when you are using Microsoft Active Directory with a crossRef object for creating referrals, you should take into account that LDAP Login Modules use only one value for baseCtxDN and only one value for rolesCtxDN. For that reason, initial users and roles should be stored in one Microsoft Active Directory domain to accommodate the possibility of using LDAP referrals.

4.5. AdvancedLdap Login Module

Short name: AdvancedLdap

Full name: org.jboss.security.negotiation.AdvancedLdapLoginModule

Parent: Common Login Module

The AdvancedLdap login module is a module which provides additional functionality, such as SASL and the use of a JAAS security domain. In cases where users wish to use LDAP with the SPNEGO authentication or skip some of the authentication phases while using an LDAP server, consider using the AdvancedLdap login module chained with the SPNEGO login module or only the AdvancedLdap login module.

AdvancedLdap login module differs from LdapExtended login module in the following ways:

  • The top level role is queried only for roleAttributeID and not for roleNameAttributeID.
  • When the roleAttributeIsDN module property is set to false, the recursive role search is disabled even if the recurseRoles module option is set to true.

Table 4.4. AdvancedLdap Login Module Options

OptionTypeDefaultDescription

bindDN

fully qualified DN

none

The DN used to bind against the LDAP server for the user and roles queries. This DN needs read and search permissions on the baseCtxDN and rolesCtxDN values.

bindCredential

String, optionally encrypted

none

Used to store the credentials for the DN.

jaasSecurityDomain

String

none

The JMX ObjectName of the JaasSecurityDomain used to decrypt the password.

java.naming.provider.url

String

If the value of java.naming.security.protocol is SSL, ldap://localhost:686, otherwise ldap://localhost:389

The URI of the directory server.

baseCtxDN

fully qualified DN

none

The distinguished name to use as the base for searches.

baseFilter

String representing an LDAP search filter.

none

The filter to use to narrow down search results.

searchTimeLimit

integer

10000, or 10 seconds

The timeout in milliseconds for user or role searches.

roleAttributeID

String value representing an LDAP attribute.

none

The LDAP attribute which contains the names of authorization roles.

roleAttributeIsDN

true or false

false

Whether the role attribute is a Distinguished Name, DN.

rolesCtxDN

fully qualified DN

none

The fully qualified DN for the context to search for user roles.

roleFilter

LDAP filter String

none

A search filter used to locate the roles associated with the authenticated user. The input user name or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input user name is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

recurseRoles

true or false

false

Whether to recursively search the roleAttributeID for roles.

roleNameAttributeID

String representing an LDAP attribute.

none

The attribute contained within the roleAttributeID which contains the actual role attribute.

referralUserAttributeIDToCheck

attribute

none

If you are not using referrals, this option can be ignored. When using referrals, this option denotes the attribute name which contains users defined for a certain role, for example member, if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

searchScope

One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE

SUBTREE_SCOPE

The search scope to use.

allowEmptyPassword

true or false

false

Whether to allow empty passwords. Most LDAP servers treat empty passwords as anonymous login attempts. To reject empty passwords, set this to false.

bindAuthentication

String

If the system property java.naming.security.authentication is set, it uses that value, otherwise it defaults to simple.

The type of SASL authentication to use for binding to the directory server.

Note

For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.

Note

In cases when you are using Microsoft Active Directory with a crossRef object for creating referrals, you should take into account that LDAP Login Modules use only one value for baseCtxDN and only one value for rolesCtxDN. For that reason, initial users and roles should be stored in one Microsoft Active Directory domain to accommodate the possibility of using LDAP referrals.

4.6. AdvancedAdLdap Login Module

Short name: AdvancedAdLdap

Full name: org.jboss.security.negotiation.AdvancedADLoginModule

Parent: AdvancedLdap Login Module

The AdvancedAdLdap login module adds extra parameters that are relevant to Microsoft Active Directory but has no additional configurable options beyond the ones available in AdvancedLdap Login Module.

Note

For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.

4.7. LDAP Connectivity Options

The LDAP connectivity information is provided as configuration options that are passed through to the environment object used to create JNDI initial context. These configuration options can be utilized by the Ldap Login Module, LdapExtended Login Module, AdvancedLdap Login Module, and AdvancedAdLdap Login Module.

The standard LDAP JNDI properties used include the following:

OptionTypeDefaultDescription

java.naming.factory.initial

class name

com.sun.jndi.ldap.LdapCtxFactory

InitialContextFactory implementation class name.

java.naming.provider.url

ldap:// URL

If the value of java.naming.security.protocol is SSL, ldap://localhost:636, otherwise ldap://localhost:389

URL for the LDAP server.

java.naming.security.authentication

none, simple, or the name of a SASL mechanism

The default is simple. If the property is explicitly undefined, the behavior is determined by the service provider.

The security level to use to bind to the LDAP server.

java.naming.security.protocol

transport protocol

If unspecified, determined by the provider.

The transport protocol to use for secure access, such as SSL.

java.naming.security.principal

String

none

The name of the principal for authenticating the caller to the service. This is built from other properties described below.

java.naming.security.credentials

credential type

none

The type of credential used by the authentication scheme. Some examples include hashed password, clear-text password, key, or certificate. If this property is unspecified, the behavior is determined by the service provider.

User authentication is performed by connecting to the LDAP server, based on the login module configuration options. Connecting to the LDAP server is done by creating an InitialLdapContext with an environment composed of the LDAP JNDI properties. The initial context implementation that is actually used depends on the initial context factory method configured. The initial context factory is defined using the java.naming.factory.initial property and gets its configuration from environment properties provided, for example java.naming.provider.url. This allows for arbitrary properties, as well as related login module options, to be used for custom initial context factories.

Note

Additional default and common options available for creating an initial context available in the javax.naming.Context interface javadoc.

4.8. LdapUsers Login Module

Short name: LdapUsers

Full name: org.jboss.security.auth.spi.LdapUsersLoginModule

Parent: UsernamePassword Login Module

The LdapUsers module is superseded by the LdapExtended and AdvancedLdap modules.

4.9. Kerberos Login Module

Short name: Kerberos

Full name: org.jboss.security.negotiation.KerberosLoginModule

The Kerberos login module performs Kerberos login authentication, using GSSAPI. This login module wraps the JDK supplied module, com.sun.security.auth.module.Krb5LoginModule for the Oracle JDK and com.ibm.security.auth.module.Krb5LoginModule for the IBM JDK, and provides additional logic for credential delegation and adding a GSSCredential to the populated Subject.

This module needs to be paired with another module which handles the authentication and roles mapping.

Important

The below table lists the options available for org.jboss.security.negotiation.KerberosLoginModule, but options from the module supplied by the JDK can also be configured. For more details on each JDK’s module options, please consult the Oracle and IBM Javadocs.

Table 4.5. Kerberos Login Module Options

OptionTypeDefaultDescription

delegationCredential

IGNORE, REQUIRE, or USE

IGNORE

Defines how this login module handles delegation. IGNORE specifies to not use the delegate credential and to perform normal Kerberos authentication. USE specifies to use a GSSCredential if available to populate a Subject, otherwise fall back to standard Kerberos authentication if unavailable. REQUIRE specifies to use a GSSCredential and fail authentication if one is not available.

addGSSCredential

boolean

false

Enables adding a GSSCredential to the private credentials of the populated Subject.

wrapGSSCredential

boolean

false

Specifies if any GSSCredential being added to the Subject should be wrapped to prevent disposal. This has no effect if a GSSCredential is not being added to the Subject.

credentialLifetime

integer

GSSCredential.DEFAULT_LIFETIME

The lifetime in seconds of the GSSCredential, a negative value will set this to GSSCredential.INDEFINITE_LIFETIME.

4.10. SPNEGO Login Module

Short name: SPNEGO

Full name: org.jboss.security.negotiation.spnego.SPNEGOLoginModule

Parent: Common Login Module

The SPNEGO login module is an implementation of login module that establishes caller identity and credentials with a KDC. The module implements SPNEGO, Simple and Protected GSSAPI Negotiation mechanism, and is a part of the JBoss Negotiation project. This authentication can be used in the chained configuration with the AdvancedLdap login module to allow cooperation with an LDAP server.

Table 4.6. SPNEGO Login Module Options

OptionTypeDefaultDescription

serverSecurityDomain

String

null

Defines the domain that is used to retrieve the identity of the server service through the kerberos login module. This property must be set.

removeRealmFromPrincipal

boolean

false

Specifies that the Kerberos realm should be removed from the principal before further processing.

usernamePasswordDomain

String

null

Specifies another security domain within the configuration that should be used as a failover login when Kerberos fails.