| |
This section documents key login module implementations that are bundled with the JBossSX framework. There are two types of login modules; those that run on the client and those that run in the JBoss server. Client side login modules primarily are used to acquire the user identity and credentials that are associated with EJB method invocations. Server side login modules are used to implement the behavior of the JaasSecurityManager and thus perform authentication and role mapping used during authorization.
To understand how server side login modules are used in JBoss, you need to understand the information storage features of the JAAS Subject class. There are six ways a one can obtain security information that has been associated with a Subject:
For Subject identities and roles, the most natural choice is to use the Principal Set obtained via getPrincipals() and getPrincipals(java.lang.Class). This is the what JBossSX has choosen to use and the usage pattern is as follows:
The identities of a user(username, SSN, employeeID, etc.) are stored as java.security.Principal objects in the Subject Principals set. The roles assigned to a user are also stored in the Principals set, but they are stored in named role sets using java.security.acl.Group instances. The Group interface is a subinterface of java.security.Principal. A Group is a collection of Principals and or Groups. There can be any number of role sets assigned to a Subject. Currently the JBossSX framework uses two well known roles sets named "Roles" and "CallerPrincipal". The "Roles" set is the set of Principals for the named roles as known in the application domain the Subject has been assigned. This role set is used by methods like the EJBContext.isCallerInRole(String) which is used by EJBs to see if the current caller belongs to the named application domain role. The CallerPrincipal role set consists of the Principal identity assigned to the user in the application domain. It is used by the EJBContext.getCallerPrincipal() method to allow the application domain to map from the operation environment identity to a user identity suitable for the application. If a Subject does not have a CallerPrincipal role set then the application identity is that of the operational environment identity.
The AbstractServerLoginModule is an abstract base class suitable that simplifies writing custom modules for the JBoss server. It implements the Subject to Principals/Groups usage pattern described the section called “LoginModule Subject Usage Patterns”. Any custom module you write should be a subclass of AbstractServerLoginModule to ensure that it associates information with the authenticated Subject in a manner consistent with the JBossSX supplied security managers.
The JaasServerLoginModule is a simple properties file based login module that consults two Java Properties formatted text files for username to password("users.properties") and username to roles("roles.properties") mapping. The properties files are loaded during initialization using the thread context class loader. This means that these files can be placed into the J2EE deployment jar or the JBoss config directory. The users.properties file uses a format:
username1=password1
username2=password2
...to define all valid usernames and their corresponding passwords.
The roles.properties file uses a format: username1=role1,role2,...
username1.RoleGroup1=role3,role4,...
username2=role1,role3,...to define the sets of roles for valid usernames. The "username.XXX" form of
property name is used to assign the username roles to a particular named
group of roles where the XXX portion of the property name is the group name.
The "username=..." form is an abbreviation for "username.Roles=...".
The following are therefore equivalent: jduke=TheDuke,AnimatedCharacter
jduke.Roles=TheDuke,AnimatedCharacter
The ProxyLoginModule is a login module that loads a delegate LoginModule using the current thread context class loader. The purpose of this module is to work around the current JAAS class loader limitation that requires LoginModules to be on the classpath. Some LoginModules use core JBoss classes that would have to be moved into the jboss-jaas.jar and packaging becomes a mess. Instead, these LoginModules are left in the JBoss server classpath in jars under lib/ext and the roxyLoginModule is used to bootstrap the non-classpath LoginModule.
An implementation of LoginModule that authenticates against an LDAP server using JNDI based on the configuration properties. The LoginModule options include whatever options your LDAP JNDI provider support. Examples of standard LDAP JNDI properties include:
A prefix and suffix to add to the username when forming the user distiguished name. This is useful if you prompt a user for a username and you don't want them to have to enter the fully distinguished name. Using this property and principalDNSuffix the userDN will be formed as:String userDN = principalDNPrefix + username + principalDNSuffix;
indicates that the credential should be obtained as an opaque Object using the org.jboss.security.auth.callback.ObjectCallback type of Callback rather than as a char[] password using a JAAS PasswordCallback.
The distinguished name to the context to search for user roles.
The name of the attribute that in the object containing the user roles that corresponds to the userid. This is used to locate the user roles.
Example 9.5. Sample LdapLoginModule Configuration Entry
testLdap {
org.jboss.security.plugins.samples.LdapLoginModule required
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
principalDNPrefix=uid=
uidAttributeID=userid
roleAttributeID=rolenames
principalDNSuffix=,ou=People,o=displayscape.com
rolesCtxDN=ou=Users,cn=Project1,ou=Projects,o=displayscape.com
java.naming.provider.url=ldap://siren-int/
java.naming.security.authentication=simple
};DatabaseServerLoginModule is a JDBC based login module that supports authentication and role mapping. It is based on two logical tables, Principals and Roles. A simple view of the schema is given in Figure 9.8.
The Principals table associates the user principalID with the valid password and the Roles table associates the principalIDd with its role sets. The tables are logical in that you can specify the sql query that the login module uses so as long as the result set has the same structure the tables and columns can be called anything. The module options are:The name of the DataSource of the database containing the Principals and Roles tables
The prepared statement query equivalent to, “select Password from Principals where PrincipalID=?”
The prepared statement query equivalent to,“select Role, RoleGroup from Roles where PrincipalID=?”
SRPCacheLoginModule is server side login module that validates a username and session client challenge response against the cache of authentication info maintained by the SRPService mbean. This module needs a CallbackHandler that supplies the user principal and credential via the SecurityAssociationCallback object. The module options are:
The login modules docuemented in this section are used by clients to bind the identity and credentials that will passed to the JBoss server with each EJB method invocation.
The ClientLoginModule is a simple client side login module that passes the username and credentials obtained during login to the org.jboss.security.SecurityAssociation class so that each EJB method invocation is associated with the given username and credentials. Validation of the username and credentials occurs on the JBoss server according to the security domain settings of the EJB the client is invoking. The ClientLoginModule is often chained with other login modules that perform validation of the client and then pass the authenticated information onto the ClientLoginModule so that the information is attached to the EJB method invocations.
 | |
