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