Login Module Reference

principalClass

A fully-qualified classname

org.jboss.security.SimplePrincipal

A Principal implementation class which contains a constructor that takes String argument for the principal name.

module

String

none

A reference to a jboss-module that can be used to load a custom callback/validator.

unauthenticatedIdentity

String

none

This defines the principal name that should be assigned to requests that contain no authentication information. This can allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and can only access unsecured EJBs or EJB methods that are associated with the unchecked permission constraint. See the Unauthenticated Identity section for more details.

password-stacking

useFirstPass or false

false

See the Password Stacking section for more details.

ignorePasswordCase

boolean

false

A flag indicating if the password comparison should ignore case.

digestCallback

A fully-qualified classname

none

The class name of the org.jboss.crypto.digest.DigestCallback implementation that includes pre/post digest content like salts for hashing the input password. Only used if hashAlgorithm has been specified and hashUserPassword is set to true.

storeDigestCallback

A fully-qualified classname

none

The class name of the org.jboss.crypto.digest.DigestCallback implementation that includes pre/post digest content like salts for hashing the store/expected password. Only used if hashStorePassword is true and hashAlgorithm has been specified.

throwValidateError

boolean

false

A flag that indicates whether validation errors should be exposed to clients or not.

inputValidator

A fully-qualified classname

none

The instance of the org.jboss.security.auth.spi.InputValidator implementation used to validate the username and password supplied by the client.

principal

String

guest

The name to use for the principal.

roles

comma-separated list of Strings

none

A comma-delimited list of roles which will be assigned to the subject.

usersProperties

Path to a file or resource.

users.properties

The file or resource which contains the user-to-password mappings. The format of the file is username=password

rolesProperties

Path to a file or resource.

roles.properties

The file or resource which contains the user-to-role mappings. The format of the file is username=role1,role2,role3

defaultUsersProperties

String

defaultUsers.properties

The name of the properties resource containing the username-to-password mappings that will be used as the default properties passed to the usersProperties properties.

defaultRolesProperties

String

defaultRoles.properties

The name of the properties resource containing the username-to-roles mappings that will be used as the default properties passed to the usersProperties properties.

roleGroupSeperator

String

.

The character used to seperate the role group name from the username (e.g. . in jduke.CallerPrincipal=…​).

username

String

none

The username for authentication.

password

encrypted String

""

The password to use for authentication. To encrypt the password, use the module directly at the command line (e.g. java org.picketbox.datasource.security.SecureIdentityLoginModule password_to_encrypt) and paste the result of this command into the module option’s value field. The default value is an empty String.

managedConnectionFactoryName

JCA resource

none

The name of the JCA connection factory for your datasource.

username

String

none

The username for authentication.

password

encrypted String

""

The password to use for authentication, which can be encrypted via the vault mechanism. The default value is an empty String.

principal

Name of a principal

none

The principal which will be associated with any subject authenticated against the module.

jboss.security.security_domain

String

Name of security domain to display in error message.

roleName

role name

nobody

The name of the role to use as the run as role during the login phase.

principalName

principal name

nobody

Name of the principal to use as the run as principal during login phase. If not specified a default of nobody is used.

principalClass

A fully-qualified classname.

org.jboss.security.SimplePrincipal

A Principal implementation class which contains a constructor that takes String arguments for the principal name.

rolesProperties

The fully-qualified file path and name of a properties file or resource

none

The fully-qualified file path and name of a properties file or resource which maps roles to replacement roles. The format is original_role=role1,role2,role3

replaceRole

true or false

false

Whether to add to the current roles, or replace the current roles with the mapped ones. Replaces if set to true.

realm

String

ApplicationRealm

Name of the desired realm.

realm

String

ApplicationRealm

Name of the desired realm.

hashAlgorithm

String

REALM

Static value set by login module for option from inherited UsernamePasswordLoginModule.

hashStorePassword

String

false

Static value set by login module for option from inherited UsernamePasswordLoginModule.

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.

securityDomain

String

other

Name of the security domain that has the JSSE configuration for the truststore holding the trusted certificates.

verifier

class

none

The class name of the org.jboss.security.auth.certs.X509CertificateVerifier to use for verification of the login certificate.

rolesProperties

String

roles.properties

The name of the resource or file containing the roles to assign to each user. The role properties file must be in the format username=role1,role2 where the username is the DN of the certificate, escaping any = (equals) and space characters. The following example is in the correct format: CN\=unit-tests-client,\ OU\=Red\ Hat\ Inc.,\ O\=Red\ Hat\ Inc.,\ ST\=North\ Carolina,\ C\=US

defaultRolesProperties

String

defaultRoles.properties

Name of the resource or file to fall back to if the rolesProperties file cannot be found.

roleGroupSeparator

A single character.

. (a single period)

Which character to use as the role group separator in the rolesProperties file.

dsJndiName

A JNDI resource

java:/DefaultDS

The name of the JNDI resource storing the authentication information.

rolesQuery

prepared SQL statement

select Role,RoleGroup from Roles where PrincipalID=?

SQL prepared statement to be executed in order to map roles. It should be an equivalent to the 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

true or false

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.

useClientCert

boolean

false

If true, the login module will obtain the SSLSession of the connection and substitute the peer’s X509Certificate in place of the password.

multi-threaded

true or false

true

Set to true if each thread has its own principal and credential storage. Set to false to indicate that all threads in the VM share the same identity and credential.

password-stacking

useFirstPass or false

false

Set to useFirstPass to indicate that this login module should look for information stored in the LoginContext to use as the identity. This option can be used when stacking other login modules with this one.

restore-login-identity

true or false

false

Set to true if the identity and credential seen at the start of the login() method should be restored after the logout() method is invoked.