8.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;