Chapter 6. Security Domain Schema

The security domain schema is constructed using XML.
The XML Schema Definition (XSD) that defines the structure of the security domain is declared in the security-beans_1_0.xsd file. The location of the file varies depending on which version of the JBoss Enterprise Application Platform you use.
5.1, 5.2
/schema/security-beans_1_0.xsd inside the jboss-as/lib/jbosssx.jar
5.0, 5.0.1
/schema/security-beans_1_0.xsd inside the jboss-as/common/lib/jbosssx.jar
The schema is the same regardless of which JBoss Enterprise Application Platform server you use. 
<application-policy xmlns="urn:jboss:security-beans:1.0" name="">
  <authentication>
    <login-module code="" flag="[required|requisite|sufficient|optional]" extends="">
      <module-option name=""></module-option>
    </login-module>
  </authentication>
  <authorization>
    <policy-module code="" flag="[required|requisite|sufficient|optional]"/>
  </authorization>
  <mapping>
    <mapping-module code="" type="" />
  </mapping>
</application-policy>

Figure 6.1. Schema of the Security Domain Definition

6.1. Security Domain Elements

<application-policy>
The elements of a security domain, regardless of how it is deployed within the system, are contained within the <application-policy> element. The element uses the XML namespace, as declared in the xmlns attribute.
The name attribute sets the name of the security domain referenced by an application. The security domain name is bound in JNDI under the java:/jaas context, and is accessed by applications via reference in their deployment descriptors.
An <application-policy> element can contain a number of child elements that set the behavior for the security domain and all applications that use it. These elements are described in greater detail in Section 6.1.1, “<authentication>”, Section 6.1.2, “<authorization>”, and Section 6.1.3, “<mapping>”.

6.1.1. <authentication>

This element contains <login-module> elements, that control which authentication modules are used when authenticating users who connect through the application.
When multiple <login-module> elements are present, they form a collective group of requirements that must be met before authentication is verified. This collective group is called a stack .
<login-module>
This element uses the code attribute to specify what login module implementation an application can use, and the flag attribute to tell the application how to parse each login module present in the stack. The flag attribute supports the following values:
required
The module must succeed for authentication to be successful. If any required <login-module> fails, the authentication will fail. The remaining login modules in the stack are called regardless of the outcome of the authentication.
requisite
The module is required to succeed. If it succeeds, authentication continues down the stack. If the module 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 the module fails, authentication continues down the stack.
optional
The login module is not required to succeed. Authentication still continues to proceed down the stack regardless of whether the login module succeeds or fails.
Each <login-module> contains a set of <module-option> elements that further define settings required by the login module implementation.
<module-option>
Each login module has its own set of configuration options. The name attribute specifies the property required by the login module, and the value is declared in the CDATA of the <module-option> element. Module options depend on what login module you choose. Section 12.1, “Using Modules” covers module options in greater detail.

6.1.2. <authorization>

This element contains <policy-module> elements that define the policy module used to authorize application users, and whether the module is required:
When multiple <policy-module> elements are present, they form a collective group of requirements that must be met before authorization is verified. This collective group is called a stack .
<policy-module>
This element uses the code attribute to specify what policy module implementation an application can use, and the flag attribute to tell the application how to parse each policy module present in the policy stack. The flag attribute supports the following values:
required
The module must succeed for authorization to be successful. If any required <policy-module> fails, the authorization attempt will fail. The remaining modules in the stack are called regardless of the outcome of the module.
requisite
The module is required to succeed. If it succeeds, authorization continues down the stack. If it fails, control immediately returns to the application.
sufficient
The module is not required to succeed. If it does succeed, control immediately returns to the application. If it fails, authorization continues down the stack.
optional
The module is not required to succeed. Authorization still continues to proceed down the stack regardless of whether the module succeeds or fails.

6.1.3. <mapping>

This element contains <mapping-module> elements that are used to define the parameters of the mapping-module elements.
When multiple <mapping-module> elements are present, they form a collective group of requirements that must be met before mapping can succeed. This collective group is called a stack .
<mapping-module>
This element uses the code attribute to specify what mapping module implementation an application can use, and the type attribute to tell the application how to parse each mapping module present in the policy stack. The type attribute supports the following values:
  • credential
  • principal
  • role
  • attribute