Chapter 4. Login Modules With External Identity Store

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.

principalDNPrefix

String

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

principalDNSuffix

String

Suffix added to the username to form the user DN. You can prompt the user for a username 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 username only. If true, the full user DN is used as the match value. If false, only the username 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 (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 encrypt64(byte[]) method which is called on the object passed in this option.

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 username. If set to false the DN is not parsed for the username. 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 (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.

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 a LDAP search filter.

none

The filter to use to narrow down search results.

searchTimeLimit

integer

10000 (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 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}).

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.

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.

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.

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.