Why is it that developers are so horrible at writing documentation? Here’s a task for you, search the JBoss documentation, even do a Google search, and try to find a clearly written, step-by-step tutorial on adding role-based security to a JBoss web app.

You can’t because, stunningly, it doesn’t exist…. until now. After days of searching different forums and tinkering around with settings myself, I discovered that the process is laughably simple, but the instructions exist nowhere (well, they exist, but good luck understanding them).

Here we go:

Step 1 – Define secure resource for your application

Edit the file C:\{jboss install dir}\server\default\deploy\{your web app}\WEB-INF\web.xml

After all of the servlet-mapping sections (near the bottom of the file) you need to add security-contraint sections for each resource (file or directory) that you want secure. Here’s an example of how you would secure a directory named developer.

<security-constraint>
	<web-resource-collection>
		<web-resource-name>developer</web-resource-name>
		<url-pattern>/developer/*</url-pattern>
	</web-resource-collection>
	<auth-constraint>
		<role-name>developer</role-name>
	</auth-constraint>
	<user-data-constraint>
		<transport-guarantee>NONE</transport-guarantee>
	</user-data-constraint>
</security-constraint>

Step 2 – Setting the authentication method

Below that in the same file, specify what type of authentication you want to use for your security contraints. Check the JBoss documentation for the different types.

<login-config>
	<auth-method>BASIC</auth-method>
	<realm-name>My Application Security Zone</realm-name>
</login-config>

Step 3 – Defining the roles that have access

Last step in this file is to define what roles will have access to this application’s security zones. You can take a quick peek at Step 7 to see how roles are set up.

<security-role>
	<description>The role required to access restricted developer content</description>
	<role-name>developer</role-name>
</security-role>

<security-role>
	<description>The role required to access restricted ColdFusion content </description>
	<role-name>coldfusionadmin</role-name>
</security-role>

Step 4 – Applying your new policy

Create/edit the file C:\{jboss install dir}\server\default\deploy\{your web app}\WEB-INF\jboss-web.xml

Edit the file so that it contains the <security-domain> property. Here’s an example of what the file should look like…

<jboss-web>
	<context-root></context-root>
	<security-domain>java:/jaas/{application policy name}</security-domain>
</jboss-web>

The application policy name can be anything you want. Just pick a common-sense name. For example, if you’re app name is Widgets, just put that text in there.

Step 5 – Telling JBoss about your policy

Edit the file C:\{jboss install dir}\server\default\conf\login-config and add an application policy with the same name as what you put in {application policy name} in the previous step. Again, here’s an example…

<application-policy name ="{application policy name}"
	<authentication>
		<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
			<module-option name="usersProperties">yourappnamehere-users.properties</module-option>
			<module-option name="rolesProperties">yourappnamehere-roles.properties</module-option>
		</login-module>
	</authentication>
</application-policy>

Step 6 – Creating users and roles files

Now create the WEB-INF\classes directory under your web application if it doesn’t already exist.
Create two files in the classes directory

• yourappnamehere-users.properties
• yourappnamehere-roles.properties

Step 7 – Setting up your users

In the users file, all you need to do is define a user and its password in the format user=password for as many as you need to create.

In the roles file, assign each user a role that you created in your web.xml file.
user=coldfusionadmin,developer
joe=developer
bob=coldfusionadmin

Let’s say that your development, production and QA environments all want to play around with the ColdFusion administrator settings independantly of the actual application code. Development checks code into CVS, QA verifies it and a build is cut to production. What would happen if the administrator settings were different in each environment? Doesn’t sound like a very stable, or safe, process. One way around this is to have your ColdFusion root directory located completely outside your deployment path, perhaps even on a network drive. Here’s how to start.

1. When installing ColdFusion, choose the J2EE installation with the WAR file option
2. Once installation is complete, unpack (with any zip application) the WAR file to a temporary folder
3. Now create a folder on the same mounted drive as where you’ll be running ColdFusion (Jboss) from where all persistent data will be held
4. In your temporary folder, you’ll see a WEB-INF directory. Move the cfusion and cfclasses directory from there to the folder you create in step 3
5. Now you can move the CFIDE and WEB-INF directories to the folder (or war file) of your web application

Now you’ll be modifying the WEB-INF\web.xml file in several places. Here’s an example – your deployment directory path for your application is…
C:\jboss-4.0.1\server\default\deploy\myapp.war

Now let’s say that when production gets a new build, that they must delete the entire JBoss directory and deploy a completely new one from the build. You want to house your persistent files outside of that directory, such as…
C:\PersistentData

In your myapp.war\WEB-INF\web.xml file, you must change the value for all instances of the following properties to point to your persistent data folder.

• cf.class.path
• cf.lib.path
• cfRootDir

For this specific example, one value would be…

<context-param id="macromedia_context_89">
   <param-name>cf.lib.path</param-name>
   <param-value>../../../../../../PersistentData/cfusion/lib</param-value>
</context-param>

Once all are changed, ColdFusion – on startup – will now look in that location for all of its required libraries.