CreateASimpleSecurityDomainForJBossSX

Setting up a security domain is simple with JBoss SX.  The following instructions are a step by step methodology for creating a simple domain that uses two properties files to hold user ids, passwords, and roles for those users.

 

1. Open the ${jboss.dist}/server/${server.name}/conf/login-config.xml file.

 

This file sets up the configuration for the security domains available to applications running in the server.  The file already has a few domains in there for some example/default resources, so you might want to look to those for inspiration.  JBoss SX uses JAAS for the underlying security infrastructure, and JAAS uses a class called a "login module" to interact with a security store for authenticating credentials.  This file basically hooks up a security domain (just a name really) to a JAAS login module.  JBoss AS comes packed with a few different login modules which you can find more information about on the JBoss SX wiki page at JBossSX.

 

The easiest login module to start with is the UsersRolesLoginModule.  This login module allows you to specify user names, passwords and roles in a simple property file.  Obviously, this module isn't one of the more secure modules, so you probably would want to use something like LDAP to store/lookup credentials in production.

 

2.  Copy the "jmx-console" domain policy as a starting point.

 

The "jmx-console" security domain policy contains the basics for configuring a UsersRolesLoginModule based security domain.  Here is a copy of that section:

     <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>

Copy this section to the bottom of the file, and change the "name" attribute on the application-policy attribute to "my-web".  Also, change the "userProperties" module-option text value to be "props/my-web-users.properties", and the "roleProperties" module-option text value to be "props/my-web-roles.properties".  Save the login-config.xml file.

 

The "name" attribute on the "application-policy" element specifies the name of the security domain.  This name is important because it is what will be used to tie the security domain to the web application later.  The "login-module" element specifies the login module that this domain will use.  You can actually have multiple "login-module" elements to have multi-level authentication, but we'll stick to one for this simple case.  The "flag" attribute on the login-module element specifies how to handle failed authentications from this module, and how it interacts with other modules.  The "required" value is what you would want for a single login module, but you can refer to the DTD for the login-config.xml file for more info about the other options.  Finally, the "module-option" elements specify some values to pass into the login module's "initialize" method.  These values are passed in as a name-value map to that method.  In the case of the UsersRolesLoginModule, we need to tell the module what properties files to use for looking up user information (usersProperties), and what file to use for looking up role information (rolesProperties).  These paths are relative to the ${jboss.dist}/server/${server.name}/conf directory.

 

3. In the ${jboss.dist}/server/conf/props directory, copy the jmx-console-users.properties into a new file called my-web-users.properties, and copy the jmx-console-roles.properties into a new file called my-web-roles.properties.

 

Opening the my-web-users.properties file, you will see a single entry like this:

"admin=admin".  When a user logs into this security domain, the login module will examine the properties data in this file for known users.  The structure of the entries in this file is "username=password".  Let's add a new entry to the file for your own user by pasting "chris=secure" on a new line below the "admin=admin" line in the file.  Save this file.

 

Next, open the my-web-roles.properties file, and you should see an line like the following: "admin=JBossAdmin,HttpInvoker".  The entries in this file define what roles a user has associated with their account when they login.  The form of these entries is "username=Role1,Role2,..." where the username is the user you wish to assign roles to, and the Roles entries are a comma separated list of roles to assign to that user.  Add a new entry to this file by pasting "chris=WebAppUser" on a new line below the "admin=...." line.  Save this file.