このコンテンツは選択した言語では利用できません。
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.
Option | Type | Default | Description |
---|---|---|---|
dsJndiName | A JNDI resource | java:/DefaultDS | The name of the JNDI resource storing the authentication information. |
principalsQuery | prepared SQL statement |
select | 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 |
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.
-
principalDNPrefix
is set touid=
. -
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
.
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.
Option | Type | Default | Description |
---|---|---|---|
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 |
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, or 10 seconds | The timeout in milliseconds for user or role searches. |
searchScope |
One of: |
| The search scope to use. |
jaasSecurityDomain | String | none |
The JMX ObjectName of the JaasSecurityDomain used to decrypt the |
For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.
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:
-
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 thebaseCtxDN
androlesCtxDN
trees for the user and roles. The user DN to authenticate against is queried using the filter specified by thebaseFilter
attribute. - 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.
Option | Type | Default | Description |
---|---|---|---|
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 |
baseFilter | LDAP filter String | none |
A search filter used to locate the context of the user to authenticate. The input |
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 |
roleAttributeID | attribute | role | Name of the attribute containing the user roles. |
roleAttributeIsDN | true or false | false |
Whether or not the |
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 |
parseUsername | true or false | false |
A flag indicating if the DN is to be parsed for the |
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 | String | none |
Defines the String which is to be removed from the end of the DN to reveal the |
roleNameAttributeID | attribute | name |
Name of the attribute within the |
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: |
| 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 |
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 |
For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.
While this login module does inherit the ignorePasswordCase option from its parent, UsernamePassword Login Module, it is not used by this specific login module.
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 forroleNameAttributeID
. -
When the
roleAttributeIsDN
module property is set tofalse
, the recursive role search is disabled even if therecurseRoles
module option is set totrue
.
Option | Type | Default | Description |
---|---|---|---|
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 | 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 username or userDN obtained from the login module callback is substituted into the filter anywhere a |
recurseRoles | true or false | false |
Whether to recursively search the |
roleNameAttributeID | String representing an LDAP attribute. | none |
The attribute contained within the |
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 |
searchScope |
One of: |
| 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 | The type of SASL authentication to use for binding to the directory server. |
For information about additional LDAP context properties related to connecting to an LDAP server and creating an initial context, see LDAP Connectivity Options.
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.
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:
Option | Type | Default | Description |
---|---|---|---|
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 | 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.
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.
Option | Type | Default | Description |
---|---|---|---|
delegationCredential |
|
|
Defines how this login module handles delegation. |
addGSSCredential | boolean | false |
Enables adding a |
wrapGSSCredential | boolean | false |
Specifies if any |
credentialLifetime | integer |
|
The lifetime in seconds of the |
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.
Option | Type | Default | Description |
---|---|---|---|
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. |