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 8.13, “The XMLLoginConfig DTD”. This DTD can be found in docs/dtd/security_config.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.