The preceding discussion of the general JBoss security layer states that the JBossSX security extension framework is an implementation of the security layer interfaces. This is the primary purpose of the JBossSX framework. The details of the implementation are interesting in that the implementation offers a great deal of customization for integration into existing security infrastructures. A security infrastructure can be anything from a database or an LDAP server to a sophisticated security software suite. The integration flexibility is achieved by using the pluggable authentication model that is available in the JAAS framework. The heart of the JBossSX framework is org.jboss.security.plugins.JaasSecurityManager. This is the default implementation of the AuthenticationManager and RealmMapping interfaces. Figure 8.11 shows how JaasSecurityManager integrates into the EJB and web container layers, based on the security-domain element of the corresponding component deployment descriptor. Figure 8.11. The relationship between the security-domain component deployment descriptor value, the component container, and JaasSecurityManager.
Figure 8.11 depicts an enterprise application that contains both EJBs and web content, secured under the security domain jwdomain. The EJB and web containers have a request interceptor architecture that includes a security interceptor, which enforces the container security model. At deployment time, the security-domain element value in the jboss.xml and jboss-web.xml descriptors is used to obtain the security manager instance associated with the container. The security interceptor then uses the security manager to perform its role. When a secured component is requested, the security interceptor delegates security checks to the security manager instance associated with the container. The JBossSX JaasSecurityManager implementation performs security checks based on the information associated with the Subject instance that results from executing the JAAS login modules configured under the name that matches the security-domain element value. The following section drills into the JaasSecurityManager implementation and its use of JAAS. How JaasSecurityManager Uses JAASJaasSecurityManager uses the JAAS packages to implement the AuthenticationManager and RealmMapping interface behavior. In particular, its behavior derives from the execution of the login module instances that are configured under the name that matches the security domain to which JaasSecurityManager has been assigned. The login modules implement the security domain's principal authentication and role-mapping behavior. Thus, you can use the JaasSecurityManager across different security domains simply by plugging in different login module configurations for the domains. To illustrate the details of JaasSecurityManager's usage of the JAAS authentication process, you will walk through a client invocation of an EJB home method invocation. The prerequisite setting is that the EJB has been deployed in the JBoss server, its home interface methods have been secured by using method-permission elements in the ejb-jar.xml descriptor, and it has been assigned a security domain named jwdomain, using the jboss.xml descriptor security-domain element. Figure 8.12 provides a view of the client-to-server communication discussed in this section. Figure 8.12. The steps involved in the authentication and authorization of a secured EJB home method invocation.
The following are the numbered steps shown in Figure 8.12:
The final step of the security interceptor check is to verify that the authenticated user has permission to invoke the requested method. Performing the authorization entails the following processes:
Every secured EJB method invocation or secured web content access requires the authentication and authorization of the caller because security information is handled as a stateless attribute of the request that must be presented and validated on each request. This can be an expensive operation if the JAAS login involves client-to-server communication. Therefore, JaasSecurityManager supports the notion of an authentication cache that is used to store principal and credential information from previous successful logins. You can specify the authentication cache instance to use as part of the JaasSecurityManager configuration, as you will see in the following section. In the absence of any user-defined cache, a default cache that maintains credential information for a configurable period of time is used. The JaasSecurityManagerService MBeanThe JaasSecurityManagerService MBean service manages security managers. Although its name begins with Jaas, the security managers it handles need not use JAAS in their implementation. The name arose from the fact that the default security manager implementation is JaasSecurityManager. The primary role of JaasSecurityManagerService is to externalize the security manager implementation. You can change the security manager implementation by providing an alternate implementation of the AuthenticationManager and RealmMapping interfaces. The second fundamental role of JaasSecurityManagerService is to provide a JNDI javax.naming.spi.ObjectFactory implementation to allow for simple code-free management of the JNDI name-to-security manager implementation mapping. As mentioned previously, you enable security by specifying the JNDI name of the security manager implementation via the security-domain deployment descriptor element. When you specify a JNDI name, there has to be an object-binding to use. To simplify the setup of the JNDI name-to-security manager bindings, JaasSecurityManagerService manages the association of security manager instances to names by binding the next naming system reference with itself as the JNDI ObjectFactory under the name java:/jaas. This allows you to use a naming convention in the form java:/jaas/XYZ as the value for the security-domain element, and the security manager instance for the XYZ security domain will be created as needed for you. The security manager for the domain XYZ is created on the first lookup against the java:/jaas/XYZ binding by creating an instance of the class specified by the SecurityManagerClassName attribute, using a constructor that takes the name of the security domain. For example, consider the following container security configuration snippet: <jboss> <!-- Configure all containers to be secured under the "hades" security domain --> <security-domain>java:/jaas/hades</security-domain> <!-- ... --> </jboss> Any lookup of the name java:/jaas/hades will return a security manager instance that has been associated with the security domain named hades. This security manager will implement the AuthenticationManager and RealmMapping security interfaces and will be of the type specified by the JaasSecurityManagerService SecurityManagerClassName attribute. The JaasSecurityManagerService MBean is configured by default for use in the standard JBoss distribution, and you can often use the default configuration as is. The configurable attributes of the JaasSecurityManagerService include the following:
JaasSecurityManagerService also supports a number of useful operations. These include flushing any security domain authentication cache at runtime, getting the list of active users in a security domain authentication cache, and using any of the security manager interface methods. You can flush a security domain authentication cache in order to drop all cached credentials when the underlying store has been updated and you want the store state to be used immediately. The MBean operation signature is public void flushAuthenticationCache(String securityDomain). The following code invokes this operation: MBeanServer server = ...; String jaasMgrName = "jboss.security:service=JaasSecurityManager"; ObjectName jaasMgr = new ObjectName(jaasMgrName); Object[] params = {domainName}; String[] signature = {"java.lang.String"}; server.invoke(jaasMgr, "flushAuthenticationCache", params, signature); Getting the list of active users provides a snapshot of the unexpired Principals keys in a security domain authentication cache. The MBean operation signature is public List getAuthenticationCachePrincipals(String securityDomain). The following code invokes this operation: MBeanServer server = ...; String jaasMgrName = "jboss.security:service=JaasSecurityManager"; ObjectName jaasMgr = new ObjectName(jaasMgrName); Object[] params = {domainName}; String[] signature = {"java.lang.String"}; server.invoke(jaasMgr, "flushAuthenticationCache", params, signature); The security manager has a few additional access methods: public boolean isValid(String securityDomain, Principal principal, Object credential); public Principal getPrincipal(String securityDomain, Principal principal); public boolean doesUserHaveRole(String securityDomain, Principal principal, Object credential, Set roles); public Set getUserRoles(String securityDomain, Principal principal, Object credential); These access methods provide access to the corresponding AuthenticationManager and RealmMapping interface method of the associated security domain named by the securityDomain argument. The JaasSecurityDomain MBeanorg.jboss.security.plugins.JaasSecurityDomain is an extension of JaasSecurityManager that adds the notion of a KeyStore, a JSSE KeyManagerFactory, and a TRustManagerFactory for supporting SSL and other cryptographic use cases. The additional configurable attributes of the JaasSecurityDomain include the following:
An XML JAAS Login Configuration MBeanXMLLoginConfig is a service that loads standard JAAS application configurations from a local configuration file. This MBean supports the following attributes:
The XML configuration file conforms to the DTD shown in Figure 8.13. This DTD can be found in docs/dtd/security_config.dtd. Figure 8.13. The XMLLoginConfig DTD.The name attribute of application-policy is the login configuration name. This corresponds to the portion of the jboss.xml and jboss-web.xml security-domain element value after the java:/jaas/ prefix. The code attribute of the login-module element specifies the classname of the login module implementation. The flag attribute controls the overall behavior of the authentication stack. The allowed values and meanings are as follows:
Zero or more module-option elements may be specified as child elements of a loginmodule. These define name/value string pairs that are made available to the login module during initialization. The name attribute specifies the option name, and the module-option body provides the value. An example of a login configuration is shown in Listing 8.10. Listing 8.10. A Sample Login Module Configuration Suitable for Use with XMLLoginConfig[View full width] <policy> <application-policy name="srp-test"> <authentication> <login-module code="org.jboss.security.srp.jaas.SRPCacheLoginModule" flag="required"> <module-option name="cacheJndiName">srp-test/AuthenticationCache< /module-option> </login-module> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required"> <module-option name="password-stacking">useFirstPass</module-option> </login-module> </authentication> </application-policy> </policy> The MBean also supports the following operations that allow you to dynamically extend the login configurations at runtime. Note that any operation that attempts to alter the login configuration requires a javax.security.auth.AuthPermission ("refreshLoginConfiguration") when running with a security manager. The org.jboss.chap8.service.SecurityConfig service demonstrates how you can use this to add/remove a deployment-specific security configuration dynamically:
The JAAS Login Configuration Management MBeanThe installation of the custom javax.security.auth.login.Configuration is managed by the org.jboss.security.plugins.SecurityConfig MBean. There is one configurable attribute:
In addition to allowing for a custom JAAS login configuration implementation, this service allows configurations to be chained together in a stack at runtime. This enables you to push a login configuration onto the stack and later pop it. The security unit tests use this feature to install custom login configurations into a default JBoss installation. Pushing a new configuration is done using the following: public void pushLoginConfig(String objectName) throws JMException, MalformedObjectNameException; The objectName parameter specifies an MBean similar to the LoginConfig attribute. You can remove the current login configuration by using the following: public void popLoginConfig() throws JMException; Using and Writing JBossSX Login ModulesThe JaasSecurityManager implementation allows complete customization of the authentication mechanism, using JAAS login module configurations. By defining the login module configuration entry that corresponds to the security domain name you have used to secure access to your J2EE components, you define the authentication mechanism and integration implementation. The JBossSX framework includes a number of bundled login modules that are suitable for integration with standard security infrastructure store protocols, such as LDAP and JDBC. It also includes standard base class implementations that help enforce the expected LoginModule-to-Subject usage pattern that is described later in this chapter, in the section "Writing Custom Login Modules." These implementations allow for easy integration of your own authentication protocol if none of the bundled login modules prove suitable. The following sections first describe the useful bundled login modules and their configuration, and then discuss how to create your own custom LoginModule implementations for use with JBoss. org.jboss.security.auth.spi.IdentityLoginModule IdentityLoginModule is a simple login module that associates the principal specified in the module options with any subject authenticated against the module. It creates a SimplePrincipal instance, using the name specified by the principal option. Although this is certainly not an appropriate login module for production-strength authentication, it can be of use in development environments when you want to test the security associated with a given principal and associated roles. The supported login module configuration options include the following:
The following is a sample XMLLoginConfig configuration entry that would authenticate all users as the principal named jduke and assign the role names TheDuke and AnimatedCharacter: <policy> <application-policy name="testIdentity"> <authentication> <login-module code="org.jboss.security.auth.spi.IdentityLoginModule" flag="required"> <module-option name="principal">jduke</module-option> <module-option name="roles">TheDuke,AnimatedCharater </module-option> </login-module> </authentication> </application-policy> </policy> org.jboss.security.auth.spi.UsersRolesLoginModule UsersRolesLoginModule is a simple login module that supports multiple users and user roles loaded from Java properties files. The username-to-password mapping file is called users.properties, and the username-to-roles mapping file is called roles.properties. The properties files are loaded during initialization, using the initialize method thread context class loader. This means that these files can be placed into the J2EE deployment JAR, the JBoss configuration directory, or any directory on the JBoss server or system classpath. The primary purpose of this login module is to easily test the security settings of multiple users and roles, using properties files deployed with the application. The users.properties file uses a username=password format with each user entry on a separate line, as shown here: username1=password1 username2=password2 ... The roles.properties file uses the username=role1,role2,... format, with an optional group name value. Here's an example: username1=role1,role2,... username1.RoleGroup1=role3,role4,... username2=role1,role3,... 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=..., where the Roles group name is the standard name the JaasSecurityManager expects to contain the roles that define the user's permissions. The following would be equivalent definitions for the jduke username: jduke=TheDuke,AnimatedCharacter jduke.Roles=TheDuke,AnimatedCharacter The supported login module configuration options include the following:
The following is a sample legacy XMLLoginConfig configuration entry that assigns unauthenticated users the principal name nobody and contains Base 64encoded MD5 hashes of the passwords in a usersb64.properties file: <policy> <application-policy name="testUsersRoles"> <authentication> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required"> <module-option name="usersProperties">usersb64.properties</module-option> <module-option name="hashAlgorithm">MD5</module-option> <module-option name="hashEncoding">base64</module-option> <module-option name="unauthenticatedIdentity">nobody </module-option> </login-module> </authentication> </application-policy> </policy> org.jboss.security.auth.spi.LdapLoginModule LdapLoginModule is a LoginModule implementation that authenticates against an LDAP server, using JNDI login, using the login module configuration options. You would use LdapLoginModule if your username and credential information are stored in an LDAP server that is accessible via a JNDI LDAP provider. The LDAP connectivity information is provided as configuration options that are passed through to the environment object used to create the JNDI initial context. The standard LDAP JNDI properties used include the following:
The supported login module configuration options include the following:
The authentication of a user 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 described previously in this section. The Context.SECURITY_PRINCIPAL is set to the distinguished name of the user, as obtained by the callback handler in combination with the principalDNPrefix and principalDNSuffix option values, and the Context. SECURITY_CREDENTIALS property is either set to the String password or the Object credential, depending on the useObjectCredential option. When authentication has succeeded by virtue of being able to create an InitialLdapContext instance, the user's roles are queried by performing a search on the rolesCtxDN location with search attributes set to the roleAttributeName and uidAttributeName option values. The role names are obtained by invoking the toString method on the role attributes in the search result set. The following is a sample login-config.xml entry: <policy> <application-policy name="testLDAP"> <authentication> <login-module code="org.jboss.security.auth.spi.LdapLoginModule" flag="required"> <module-option name="java.naming.factory.initial"> com.sun.jndi.ldap.LdapCtxFactory </module-option> <module-option name="java.naming.provider.url"> ldap://ldaphost.jboss.org:1389/ </module-option> <module-option name="java.naming.security.authentication"> simple </module-option> <module-option name="principalDNPrefix">uid=</module-option> <module-option name="principalDNSuffix"> ,ou=People,dc=jboss,dc=org </module-option> <module-option name="rolesCtxDN"> ou=Roles,dc=jboss,dc=org </module-option> <module-option name="uidAttributeID">member</module-option> <module-option name="matchOnUserDN">true</module-option> <module-option name="roleAttributeID">cn</module-option> <module-option name="roleAttributeIsDN">false </module-option> </login-module> </authentication> </application-policy> </policy> An LDIF file representing the structure of the directory this data operates against is shown here: dn: dc=jboss,dc=org objectclass: top objectclass: dcObject objectclass: organization dc: jboss o: JBoss dn: ou=People,dc=jboss,dc=org objectclass: top objectclass: organizationalUnit ou: People dn: uid=jduke,ou=People,dc=jboss,dc=org objectclass: top objectclass: uidObject objectclass: person uid: jduke cn: Java Duke sn: Duke userPassword: theduke dn: ou=Roles,dc=jboss,dc=org objectclass: top objectclass: organizationalUnit ou: Roles dn: cn=JBossAdmin,ou=Roles,dc=jboss,dc=org objectclass: top objectclass: groupOfNames cn: JBossAdmin member: uid=jduke,ou=People,dc=jboss,dc=org description: the JBossAdmin group If you look back at the testLDAP login module configuration, you see that the java.naming.factory.initial, java.naming.factory.url, and java.naming.security options indicate that the Sun LDAP JNDI provider implementation will be used, the LDAP server is located on host ldaphost.jboss.org on port 1389, and the LDAP simple authentication method will be use to connect to the LDAP server. The login module attempts to connect to the LDAP server by using a DN that represents the user it is trying to authenticate. This DN is constructed from the principalDNPrefix, passed in the username of the user, and the principalDNSuffix, as described earlier in this chapter. In this example, the username jduke would map to uid=jduke, ou=People,dc=jboss,dc=org. Here we assume that the LDAP server authenticates users by using the user-Password attribute of the user's entry (theduke, in this example). This is the way most LDAP servers work; however, if your LDAP server handles authentication differently, you need to set the authentication credentials in a way that makes sense for your server. When authentication succeeds, you retrieve the roles on which authorization will be based by performing a subtree search of the rolesCtxDN for entries whose uidAttributeID matches the user. If matchOnUserDN is true, the search is based on the full DN of the user. Otherwise, the search is based on the actual username entered. In this example, the search is under ou=Roles,dc=jboss,dc=org for any entries that have a member attribute equal to uid=jduke,ou=People,dc=jboss,dc=org. The search would locate cn=JBossAdmin under the roles entry. The search returns the attribute specified in the roleAttributeID option. In this example, the attribute is cn. The value returned would be JBossAdmin, so the jduke user is assigned to the JBossAdmin role. It's often the case that a local LDAP server provides identity and authentication services but is unable to use the authorization services. This is because application roles don't always map well to LDAP groups, and LDAP administrators are often hesitant to allow external application-specific data in central LDAP servers. For this reason, the LDAP authentication module is often paired with another login module, such as the database login module, that can provide roles more suitable to the application being developed. org.jboss.security.auth.spi.DatabaseServerLoginModule DatabaseServerLoginModule is a JDBC-based login module that supports authentication and role mapping. You would use this login module if you have your username, password, and role information in a relational database. DatabaseServerLoginModule is based on two logical tables: Table Principals(PrincipalID text, Password text) Table Roles(PrincipalID text, Role text, RoleGroup text) The Principals table associates the user PrincipalID with the valid password, and the Roles table associates the user PrincipalID with its role sets. The roles used for user permissions must be contained in rows, with a RoleGroup column value of Roles. The tables are logical in that you can specify the SQL query that the login module uses. All that is required is that the java.sql.ResultSet has the same logical structure as the Principals and Roles tables described previously. The actual names of the tables and columns are not relevant because the results are accessed based on the column index. To clarify this notion, consider a database with two tables, Principals and Roles, as already declared. The following statements build the tables to contain a PrincipalID java with the Password of echoman in the Principals table, a PrincipalID java with a role named Echo in the Roles RoleGroup in the Roles table, and a PrincipalID java with a role named caller_java in the CallerPrincipal RoleGroup in the Roles table: INSERT INTO Principals VALUES('java', 'echoman') INSERT INTO Roles VALUES('java', 'Echo', 'Roles') INSERT INTO Roles VALUES('java', 'caller_java', 'CallerPrincipal') The supported login module configuration options include the following:
As an example of a DatabaseServerLoginModule configuration, consider a custom table schema like the following: CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64)) CREATE TABLE UserRoles(username VARCHAR(64), userRoles VARCHAR(32)) A corresponding login-config.xml entry would look like this: <policy> <application-policy name="testDB"> <authentication> <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="required"> <module-option name="dsJndiName">java:/MyDatabaseDS</module-option> <module-option name="principalsQuery"> select passwd from Users username where username=?</module-option> <module-option name="rolesQuery"> select userRoles, 'Roles' from UserRoles where username=?</module-option> </login-module> </authentication> </application-policy> </policy> BaseCertLoginModule BaseCertLoginModule is a login module that authenticates users based on X509 certificates. A typical use case for this login module is CLIENT-CERT authentication in the web tier. This login module only performs authentication. You need to combine it with another login module that is capable of acquiring the authorization roles to completely define access to a secured web or EJB component. Two subclasses of this login module, CertRolesLoginModule and Database-CertLoginModule, extend its behavior to obtain the authorization roles from either a properties file or database. BaseCertLoginModule needs a KeyStore to perform user validation. This is obtained through an org.jboss.security.SecurityDomain implementation. Typically, the SecurityDomain implementation is configured using the org.jboss.security.plugins.JaasSecurityDomain MBean, as shown in this jboss-service.xml configuration fragment: <mbean code="org.jboss.security.plugins.JaasSecurityDomain" name="jboss.web:service=SecurityDomain"> <constructor> <arg type="java.lang.String" value="jmx-console"/> </constructor> <attribute name="KeyStoreURL">resource:localhost.keystore</attribute> <attribute name="KeyStorePass">unit-tests-server</attribute> </mbean> This creates a security domain with the name jmx-console whose SecurityDomain implementation is available via JNDI under the name java:/jaas/jmx-console, following the JBossSX security domain naming pattern. To secure a web application such as the jmx-console.war by using client certificates and role-based authorization, you would first modify web.xml to declare the resources to be secured, along with the allowed roles and security domain to be used for authentication and authorization, as shown here: <?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> ... <security-constraint> <web-resource-collection> <web-resource-name>HtmlAdaptor</web-resource-name> <description>An example security config that only allows users with the role JBossAdmin to access the HTML JMX console web application </description> <url-pattern>/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>JBossAdmin</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>JBoss JMX Console</realm-name> </login-config> <security-role> <role-name>JBossAdmin</role-name> </security-role> </web-app> Next, you need to specify the JBoss security domain in jboss-web.xml: <jboss-web> <security-domain>java:/jaas/jmx-console</security-domain> </jboss-web> Finally, you need to define the login module configuration for the jmx-console security domain you just specified. You do this in the conf/login-config.xml file: <application-policy name="jmx-console"> <authentication> <login-module code="org.jboss.security.auth.spi.BaseCertLoginModule" flag="required"> <module-option name="password-stacking">useFirstPass</module-option> <module-option name="securityDomain">java:/jaas/jmx-console</module-option> </login-module> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required"> <module-option name="password-stacking">useFirstPass</module-option> <module-option name="usersProperties">jmx-console-users.properties</module-option> <module-option name="rolesProperties">jmx-console-roles.properties</module-option> </login-module> </authentication> </application-policy> Here BaseCertLoginModule is used for authentication of the client certificate, and UsersRolesLoginModule is only used for authorization due to the password-stacking=useFirstPass option. Both localhost.keystore and jmx-console-roles.properties need an entry that maps to the principal associated with the client certificate. By default, the principal is created using the client certificate distinguished name. Consider the following certificate: [starksm@banshee9100 conf]$ keytool -printcert -file unit-tests-client.export Owner: CN=unit-tests-client, OU=JBoss Inc., O=JBoss Inc., ST=Washington, C=US Issuer: CN=jboss.com, C=US, ST=Washington, L=Snoqualmie Pass, EMAILADDRESS=admin @jboss.com, OU=QA, O=JBoss Inc. Serial number: 100103 Valid from: Wed May 26 07:34:34 PDT 2004 until: Thu May 26 07:34:34 PDT 2005 Certificate fingerprints: MD5: 4A:9C:2B:CD:1B:50:AA:85:DD:89:F6:1D:F5:AF:9E:AB SHA1: DE:DE:86:59:05:6C:00:E8:CC:C0:16:D3:C2:68:BF:95:B8:83:E9:58 localhost.keystore would need this certificate to be stored with an alias of CN=unit-tests-client,OU=JBoss Inc.,O=JBoss Inc.,ST=Washington,C=US, and jmx-console-roles.properties would also need an entry for the same entry. Because the DN contains many characters that are normally treated as delimiters, you need to escape the problem characters with a backslash (\), as shown here: # A sample roles.properties file for use with the UsersRolesLoginModule CN\=unit-tests-client,\ OU\=JBoss\ Inc.,\ O\=JBoss\ Inc.,\ ST\=Washington,\ C\=US=JBossAdmin admin=JBossAdmin org.jboss.security.auth.spi.RunAsLoginModule JBoss has a helper login module called RunAsLoginModule that pushes a run-as role for the duration of the login phase of authentication, and it pops the run-as role in either the commit or abort phase. The purpose of this login module is to provide a role for other login modules that need to access secured resources in order to perform their authentication. An example is a login module that accesses a secured EJB; this login module must be configured ahead of the login module(s) that needs a run-as role established. The only login module configuration option is roleName, which is the name of the role to use as the run-as role during the login phase. If not specified, the default of nobody is used. org.jboss.security.ClientLoginModule ClientLoginModule is an implementation of LoginModule for use by JBoss clients for the establishment of the caller identity and credentials. This simply sets org.jboss.security.SecurityAssociation.principal to the value of the NameCallback filled in by the callbackhandler, and it sets org.jboss.security.SecurityAssociation.credential to the value of the PasswordCallback filled in by the callbackhandler. This is the only supported mechanism for a client to establish the current thread's caller. Both standalone client applications and server environments, acting as JBoss EJB clients where the security environment has not been configured to use JBossSX transparently, need to use ClientLoginModule. Of course, you could always set the org.jboss.security.SecurityAssociation information directly, but this is considered an internal API that is subject to change without notice. Note that this login module does not perform any authentication. It merely copies the login information provided to it into the JBoss server EJB invocation layer for subsequent authentication on the server. If you need to perform client-side authentication of users, you need to configure another login module in addition to ClientLoginModule. The supported login module configuration options include the following:
A sample login configuration for ClientLoginModule is the default configuration entry found in the JBoss distribution client/auth.conf file, which is as follows: other { // Put your login modules that work without jBoss here // jBoss LoginModule org.jboss.security.ClientLoginModule required; // Put your login modules that need jBoss here }; Writing Custom Login ModulesIf the login modules bundled with the JBossSX framework do not work with your security environment, you can write your own custom login module implementation that does. Recall from the section "The JBossSX Architecture," earlier in this chapter, that the JaasSecurityManager expects a particular usage pattern of the Subject principals set. You need to understand the JAAS Subject class's information storage features and the expected usage of these features to be able to write a login module that works with the JaasSecurityManager. This section examines this requirement and introduces two abstract base LoginModule implementations that can help you implement your own custom login modules. You can obtain security information associated with a Subject in six ways in JBoss, using the following methods: java.util.Set getPrincipals() java.util.Set getPrincipals(java.lang.Class c) java.util.Set getPrivateCredentials() java.util.Set getPrivateCredentials(java.lang.Class c) java.util.Set getPublicCredentials() java.util.Set getPublicCredentials(java.lang.Class c) For Subject identities and roles, JBossSX has selected the most natural choice: the principals' sets obtained via getPrincipals() and getPrincipals(java.lang.Class). The usage pattern is as follows:
Support for the Subject Usage PatternTo simplify correct implementation of the Subject usage patterns described in the preceding section, JBossSX includes two abstract login modules that handle the population of the authenticated Subject with a template pattern that enforces correct Subject usage. The most generic of the two is the org.jboss.security.auth.spi.AbstractServerLoginModule class. It provides a concrete implementation of the javax.security.auth.spi.LoginModule interface and offers abstract methods for the key tasks that are specific to an operation environment security infrastructure. The key details of the class are shown in the following class fragment, and the JavaDoc comments detail the responsibilities of subclasses: package org.jboss.security.auth.spi; /** * This class implements the common functionality required for a JAAS * server-side LoginModule and implements the JBossSX standard * Subject usage pattern of storing identities and roles. Subclass * this module to create your own custom LoginModule and override the * login(), getRoleSets(), and getIdentity() methods. */ public abstract class AbstractServerLoginModule implements javax.security.auth.spi.LoginModule { protected Subject subject; protected CallbackHandler callbackHandler; protected Map sharedState; protected Map options; protected Logger log; /** Flag indicating if the shared credential should be used */ protected boolean useFirstPass; /** * Flag indicating if the login phase succeeded. Subclasses that * override the login method must set this to true on successful * completion of login */ protected boolean loginOk; // ... /** * Initialize the login module. This stores the subject, * callbackHandler and sharedState and options for the login * session. Subclasses should override if they need to process * their own options. A call to super.initialize(...) must be * made in the case of an override. * * <p> * The options are checked for the <em>password-stacking</em> parameter. * If this is set to "useFirstPass", the login identity will be taken from the * <code>javax.security.auth.login.name</code> value of the sharedState map, * and the proof of identity from the * <code>javax.security.auth.login.password</code> value of the sharedState map. * * @param subject the Subject to update after a successful login. * @param callbackHandler the CallbackHandler that will be used to obtain * the user identity and credentials. * @param sharedState a Map shared between all configured login module instances * @param options the parameters passed to the login module. */ public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { // ... } /** * Looks for javax.security.auth.login.name and * javax.security.auth.login.password values in the sharedState * map if the useFirstPass option was true and returns true if * they exist. If they do not or are null this method returns * false. * Note that subclasses that override the login method * must set the loginOk ivar to true if the login succeeds in * order for the commit phase to populate the Subject. This * implementation sets loginOk to true if the login() method * returns true, otherwise, it sets loginOk to false. */ public boolean login() throws LoginException { // ... } /** * Overridden by subclasses to return the Principal that * corresponds to the user primary identity. */ abstract protected Principal getIdentity(); /** * Overridden by subclasses to return the Groups that correspond * to the role sets assigned to the user. Subclasses should * create at least a Group named "Roles" that contains the roles * assigned to the user. A second common group is * "CallerPrincipal," which provides the application identity of * the user rather than the security domain identity. * * @return Group[] containing the sets of roles */ abstract protected Group[] getRoleSets() throws LoginException; } You need to pay attention to the loginOk instance variable. Any subclasses that override the login method must set this to true if the login succeeds and false otherwise. Failure to set this variable correctly results in the commit method either not updating the subject when it should or updating the subject when it should not. Tracking the outcome of the login phase was added to allow login modules to be chained together with control flags that do not require that the login module succeed in order for the overall login to succeed. The second abstract base login module suitable for custom login modules is org.jboss.security.auth.spi.UsernamePasswordLoginModule. This login module further simplifies custom login module implementation by enforcing a string-based username as the user identity and a char[] password as the authentication credentials. It also supports the mapping of anonymous users (indicated by null username and password) to a principal with no roles. The key details of the class are shown in the following class fragment, and the JavaDoc comments detail the responsibilities of subclasses: package org.jboss.security.auth.spi; /** * An abstract subclass of AbstractServerLoginModule that imposes a * an identity == String username, credentials == String password * view on the login process. Subclasses override the * getUsersPassword() and getUsersRoles() methods to return the * expected password and roles for the user. */ public abstract class UsernamePasswordLoginModule extends AbstractServerLoginModule { /** The login identity */ private Principal identity; /** The proof of login identity */ private char[] credential; /** The principal to use when a null username and password are seen */ private Principal unauthenticatedIdentity; /** * The message digest algorithm used to hash passwords. If null then * plain passwords will be used. */ private String hashAlgorithm = null; /** * The name of the charset/encoding to use when converting the * password String to a byte array. Default is the platform's * default encoding. */ private String hashCharset = null; /** The string encoding format to use. Defaults to base64. */ private String hashEncoding = null; // ... /** * Override the superclass method to look for an * unauthenticatedIdentity property. This method first invokes * the super version. * * @param options, * @option unauthenticatedIdentity: the name of the principal to * assign and authenticate when a null username and password are * seen. */ public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { super.initialize(subject, callbackHandler, sharedState, options); // Check for unauthenticatedIdentity option. Object option = options.get("unauthenticatedIdentity"); String name = (String) option; if (name != null) { unauthenticatedIdentity = new SimplePrincipal(name); } } // ... /** * A hook that allows subclasses to change the validation of the * input password against the expected password. This version * checks that neither inputPassword or expectedPassword are null * and that inputPassword.equals(expectedPassword) is true; * * @return true if the inputPassword is valid, false otherwise. */ protected boolean validatePassword(String inputPassword, String expectedPassword) { if (inputPassword == null || expectedPassword == null) { return false; } return inputPassword.equals(expectedPassword); } /** * Get the expected password for the current username available * via the getUsername() method. This is called from within the * login() method after the CallbackHandler has returned the * username and candidate password. * * @return the valid password String */ abstract protected String getUsersPassword() throws LoginException; } The choice of subclassing the AbstractServerLoginModule versus UsernamePasswordLoginModule is simply based on whether a string-based username and credentials are usable for the authentication technology you are writing the login module for. If the string-based semantic is valid, then you should subclass UsernamePasswordLoginModule; otherwise, you should subclass AbstractServerLoginModule. The steps you are required to perform when writing a custom login module depend on which base login module class you choose. When writing a custom login module that integrates with your security infrastructure, you should start by subclassing AbstractServerLoginModule or UsernamePassword-LoginModule to ensure that your login module provides the authenticated Principal information in the form that the JBossSX security manager expects. When subclassing AbstractServerLoginModule, you need to override the following:
When subclassing the UsernamePasswordLoginModule, you need to override the following:
A Custom LoginModule ExampleIn this section, you will develop a custom login module example that extends the UsernamePasswordLoginModule and obtains a user's password and role names from a JNDI lookup. The idea is that there is a JNDI context that returns a user's password if you perform a lookup on the context by using a name in the form password/<username>, where <username> is the current user being authenticated. Similarly, a lookup in the form roles/<username> returns the requested user's roles. The source code for the example is located in the src/main/org/jboss/chap8/ex2 directory of the book examples. Listing 8.11 shows the source code for the JndiUserAndPass custom login module. Note that because this extends the JBoss UsernamePasswordLoginModule, all the JndiUserAndPass does is obtain the user's password and roles from the JNDI store. The JndiUserAndPass does not concern itself with the JAAS LoginModule operations. Listing 8.11. A JndiUserAndPass Custom Login Modulepackage org.jboss.chap8.ex2; import java.security.acl.Group; import java.util.Map; import javax.naming.InitialContext; import javax.naming.NamingException; import javax.security.auth.Subject; import javax.security.auth.callback.CallbackHandler; import javax.security.auth.login.LoginException; import org.jboss.security.SimpleGroup; import org.jboss.security.SimplePrincipal; import org.jboss.security.auth.spi.UsernamePasswordLoginModule; /** * An example custom login module that obtains passwords and roles * for a user from a JNDI lookup. * * @author Scott.Stark@jboss.org * @version $Revision: 1.5 $ */ public class JndiUserAndPass extends UsernamePasswordLoginModule { /** The JNDI name to the context that handles the password/username lookup */ private String userPathPrefix; /** The JNDI name to the context that handles the roles/ username lookup */ private String rolesPathPrefix; /** * Override to obtain the userPathPrefix and rolesPathPrefix options. */ public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { super.initialize(subject, callbackHandler, sharedState, options); userPathPrefix = (String) options.get("userPathPrefix"); rolesPathPrefix = (String) options.get("rolesPathPrefix"); } /** * Get the roles the current user belongs to by querying the * rolesPathPrefix + '/' + super.getUsername() JNDI location. */ protected Group[] getRoleSets() throws LoginException { try { InitialContext ctx = new InitialContext(); String rolesPath = rolesPathPrefix + '/' + super.getUsername(); String[] roles = (String[]) ctx.lookup(rolesPath); Group[] groups = {new SimpleGroup("Roles")}; log.info("Getting roles for user="+super.getUsername()); for(int r = 0; r < roles.length; r ++) { SimplePrincipal role = new SimplePrincipal(roles[r]); log.info("Found role="+roles[r]); groups[0].addMember(role); } return groups; } catch(NamingException e) { log.error("Failed to obtain groups for user="+super.getUsername(), e); throw new LoginException(e.toString(true)); } } /** * Get the password of the current user by querying the * userPathPrefix + '/' + super.getUsername() JNDI location. */ protected String getUsersPassword() throws LoginException { try { InitialContext ctx = new InitialContext(); String userPath = userPathPrefix + '/' + super.getUsername(); log.info("Getting password for user="+super.getUsername()); String passwd = (String) ctx.lookup(userPath); log.info("Found password="+passwd); return passwd; } catch(NamingException e) { log.error("Failed to obtain password for user="+super.getUsername(), e); throw new LoginException(e.toString(true)); } } } You can find the details of the JNDI store in the org.jboss.chap8.ex2.service.JndiStore MBean. This service binds an ObjectFactory that returns a javax.naming.Context proxy into JNDI. The proxy handles lookup by checking the prefix of the lookup name against password and roles. When the name begins with password, a user's password is being requested. When the name begins with roles, the user's roles are being requested. The sample implementation always returns the password theduke and an array of role names equal to {"TheDuke","Echo"}, regardless of the username. You can experiment with other implementations as you wish. The example's code includes a simple session bean for testing the custom login module. To build, deploy, and run the example, you execute the following command in the examples directory: [examples]$ ant -Dchap=chap8 -Dex=2 run-example ... run-example2: [copy] Copying 1 file to /tmp/jboss-4.0.1/server/default/deploy [echo] Waiting for 5 seconds for deploy... [java] [INFO,ExClient] Login with username=jduke, password=theduke [java] [INFO,ExClient] Looking up EchoBean2 [java] [INFO,ExClient] Created Echo [java] [INFO,ExClient] Echo.echo('Hello') = Hello 19:06:13,266 INFO [EjbModule] Deploying EchoBean2 19:06:13,482 INFO [JndiStore] Start, bound security/store 19:06:13,486 INFO [SecurityConfig] Using JAAS AuthConfig: jar:file: /private/tmp/jboss-4.0.1/server/default/tmp/deploy/ tmp23012chap8-ex2.jar-contents/chap8-ex2.sar!/META-INF/login-config.xml 19:06:13,654 INFO [EJBDeployer] Deployed: file:/private/tmp/jboss-4.0.1/ server/default/deploy/chap8-ex2.jar Whether to use the JndiUserAndPass custom login module for the server-side authentication of the user is determined based on the login configuration for the sample security domain. The EJB JAR META-INF/jboss.xml descriptor sets the security domain as follows: <?xml version="1.0"?> <jboss> <security-domain>java:/jaas/chap8-ex2</security-domain> </jboss> The SAR META-INF/login-config.xml descriptor defines the login module configuration as follows: <application-policy name = "chap8-ex2"> <authentication> <login-module code="org.jboss.chap8.ex2.JndiUserAndPass" flag="required"> <module-option name = "userPathPrefix">/security/store/password </module-option> <module-option name = "rolesPathPrefix">/security/store/roles </module-option> </login-module> </authentication> </application-policy> The DynamicLoginConfig ServiceSecurity domains defined in the login-config.xml file are essentially static. They are read when JBoss starts up, but there is no easy way to add a new security domain or change the definition for an existing one. The DynamicLoginConfig service allows you to dynamically deploy security domains. This allows you to specify JAAS login configuration as part of a deployment (or just as a standalone service) rather than having to edit the static login-config.xml file. The service supports the following attributes:
Here is an example of an MBean definition that uses the DynamicLoginConfig service: <server> <mbean code="org.jboss.security.auth.login.DynamicLoginConfig" name="..."> <attribute name="AuthConfig">login-config.xml</attribute> <!-- The service which supports dynamic processing of login-config.xml configurations. --> <depends optional-attribute-name="LoginConfigService"> jboss.security:service=XMLLoginConfig </depends> <!-- Optionally specify the security mgr service to use when this service is stopped to flush the auth caches of the domains registered by this service. --> <depends optional-attribute-name="SecurityManagerService"> jboss.security:service=JaasSecurityManager </depends> </mbean> </server> This loads the specified AuthConfig resource, using the specified LoginConfigService MBean by invoking loadConfig with the appropriate resource URL. When the service is stopped, the configurations are removed. The resource that is specified may be either an XML file or a Sun JAAS login configuration. |