Chapter 4. Login Modules With External Identity Store
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 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 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 Jakarta Transactions 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 to uid= . 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 Option Type Default Description 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 Jakarta Management 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: 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. 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 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 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 Jakarta Management 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 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 Jakarta Management 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: 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 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 Option Type Default Description 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 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.