Chapter 6. Configuring a Security Domain to use a Filesystem

Security domains can also be configured to use a filesystem as an identity store for authentication and authorization by using a login module.

6.1. UsersRoles Login Module

UsersRoles login module is a simple login module that supports multiple users and user roles loaded from Java properties files. The primary purpose of this login module is to easily test the security settings of multiple users and roles using properties files deployed with the application. The default username-to-password mapping filename is and the default username-to-roles mapping filename is


This login module supports password stacking, password hashing, and unauthenticated identity.

The properties files are loaded during initialization using the initialize method thread context class loader. This means that these files can be placed on the classpath of the Java EE deployment (for example, into the WEB-INF/classes folder in the WAR archive), or into any directory on the server classpath.

Table 6.1. Complete UsersRoles Login Module Options



Path to a file or resource.

The file or resource which contains the user-to-password mappings. The format of the file is username=password


Path to a file or resource.

The file or resource which contains the user-to-role mappings. The format of the file is username=role1,role2,role3


useFirstPass or false


A value of useFirstPass indicates that this login module should first look to the information stored in the LoginContext for the identity. This option can be used when stacking other login modules with this one.


String representing a password hashing algorithm.


The name of the algorithm to use to hash the password. There is no default so this option must be explicitly set to enable hashing. When hashAlgorithm is specified, the clear text password obtained from the CallbackHandler is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The password stored in the file must be comparably hashed.


base64 or hex


The string format for the hashed password, if hashAlgorithm is also set.



The default encoding set in the container’s runtime environment

The encoding used to convert the clear-text password to a byte array.


principal name


Defines the principal name assigned to requests which contain no authentication information. This can allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and can only access unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.

6.1.1. Configuring a Security Domain to use the UsersRoles Login Module

The below example assumes the following files have been created and are available on the application’s classpath:


CLI Commands for Adding the UserRoles Login Module


/subsystem=security/security-domain=sampleapp/authentication=classic/login-module=UsersRoles:add( \
  code=UsersRoles, \
  flag=required, \
  module-options=[ \
    ("usersProperties"=>""), \
    ("rolesProperties"=>"") \

Resulting XML

<security-domain name="sampleapp">
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value=""/>
      <module-option name="rolesProperties" value=""/>