10.5. Defining Security Domains

The standard way of configuring security domains for authentication and authorization in JBoss is to use the XML login configuration file. The login configuration policy defines a set of named security domains that each define a stack of login modules that will be called upon to authenticate and authorize users.
The XML configuration file conforms to the DTD given by Figure 10.13, “The XMLLoginConfig DTD”. This DTD can be found in docs/dtd/security_config.dtd.
The XMLLoginConfig DTD
The XMLLoginConfig DTD

Figure 10.13. The XMLLoginConfig DTD

The following example shows a simple configuration named jmx-console that is backed by a single login module. The login module is configured by a simple set of name/value configuration pairs that have meaning to the login module in question. We'll see what these options mean later, for now we'll just be concerned with the structure of the configuration file. 
<application-policy name="jmx-console">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
            <module-option name="usersProperties">props/jmx-console-users.properties</module-option>
            <module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>
        </login-module>
    </authentication>
</application-policy>
The name attribute of the application-policy is the login configuration name. Applications policy elements will be bound by that name in JNDI under the the java:/jaas context. Applications will link to security domains through this JNDI name in their deployment descriptors. (See the security-domain elements in jboss.xml, jboss-web.xml and jboss-service.xml files for examples)
The code attribute of the login-module element specifies the class name of the login module implementation. The required flag attribute controls the overall behavior of the authentication stack. The allowed values and meanings are:
  • required: The login module is required to succeed for the authentication to be successful. If any required module fails, the authentication will fail. The remaining login modules in the stack will be called regardless of the outcome of the authentication.
  • requisite: The login module is required to succeed. If it succeeds, authentication continues down the login stack. If it fails, control immediately returns to the application.
  • sufficient: The login module is not required to succeed. If it does succeed, control immediately returns to the application. If it fails, authentication continues down the login stack.
  • optional: The login module is not required to succeed. Authentication still continues to proceed down the login stack regardless of whether the login module succeeds or fails.
The following example shows the definition of a security domain that uses multiple login modules. Since both modules are marked as sufficient, only one of them need to succeed for login to proceed. 
<application-policy name="todo">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.LdapLoginModule" 
                      flag="sufficient">
            <!-- LDAP configuration -->
        </login-module>
        <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" 
                      flag="sufficient">
            <!-- database configuration -->
        </login-module>
    </authentication>
</application-policy>
Each login module has its own set of configuration options. These are set as name/value pairs using the module-option elements. We'll cover module options in more depth when we look at the individual login modules available in JBoss AS.

10.5.1. Loading Security Domains

Authentication security domains are configured statically in the conf/login-config.xml file. The XMLLoginConfig MBean is responsible for loading security configurations from this configurations from a local configuration file. The MBean is defined as shown below. 
<mbean code="org.jboss.security.auth.login.XMLLoginConfig"
       name="jboss.security:service=XMLLoginConfig">
    <attribute name="ConfigResource">login-config.xml</attribute>
</mbean>
The MBean supports the following attributes:
  • ConfigURL: specifies the URL of the XML login configuration file that should be loaded by this MBean on startup. This must be a valid URL string representation.
  • ConfigResource: specifies the resource name of the XML login configuration file that should be loaded by this MBean on startup. The name is treated as a classpath resource for which a URL is located using the thread context class loader.
  • ValidateDTD: a flag indicating if the XML configuration should be validated against its DTD. This defaults to true.
The MBean also supports the following operations that allow one to dynamically extend the login configurations at runtime. Note that any operation that attempts to alter login configuration requires a javax.security.auth.AuthPermission("refreshLoginConfiguration") when running with a security manager. The org.jboss.book.security.service.SecurityConfig service demonstrates how this can be used to add/remove a deployment specific security configuration dynamically.
  • void addAppConfig(String appName, AppConfigurationEntry[] entries): this adds the given login module configuration stack to the current configuration under the given appName. This replaces any existing entry under that name.
  • void removeAppConfig(String appName): this removes the login module configuration registered under the given appName.
  • String[] loadConfig(URL configURL) throws Exception: this loads one or more login configurations from a URL representing either an XML or legacy Sun login configuration file. Note that all login configurations must be added or none will be added. It returns the names of the login configurations that were added.
  • void removeConfigs(String[] appNames): this removes the login configurations specified appNames array.
  • String displayAppConfig(String appName): this operation displays a simple string format of the named configuration if it exists.
The SecurityConfig MBean is responsible for selecting the javax.security.auth.login.Configuration to be used. The default configuration simply references the XMLLoginConfig MBean. 
  <mbean code="org.jboss.security.plugins.SecurityConfig" 
       name="jboss.security:service=SecurityConfig">
    <attribute name="LoginConfig">jboss.security:service=XMLLoginConfig</attribute>
                 </mbean>
There is one configurable attribute:
  • LoginConfig: Specifies the JMX ObjectName string of the MBean that provides the default JAAS login configuration. When the SecurityConfig is started, this MBean is queried for its javax.security.auth.login.Configuration by calling its getConfiguration(Configuration currentConfig) operation. If the LoginConfig attribute is not specified then the default Sun Configuration implementation described in the Configuration class JavaDocs is used.
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 allows one to push a login configuration onto the stack and latter pop it. This is a feature used by the security unit tests to install custom login configurations into a default JBoss installation. Pushing a new configuration is done using: 
public void pushLoginConfig(String objectName) throws
                JMException, MalformedObjectNameException;
The objectName parameters specifies an MBean similar to the LoginConfig attribute. The current login configuration may be removed using: 
public void popLoginConfig() throws JMException;