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 users.properties and the default username-to-roles mapping filename is roles.properties.

Note

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

OptionTypeDefaultDescription

usersProperties

Path to a file or resource.

users.properties

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

rolesProperties

Path to a file or resource.

roles.properties

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

password-stacking

useFirstPass or false

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.

hashAlgorithm

String representing a password hashing algorithm.

none

The name of the java.security.MessageDigest 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 users.properties file must be comparably hashed.

hashEncoding

base64 or hex

base64

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

hashCharset

string

The default encoding set in the container’s runtime environment

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

unauthenticatedIdentity

principal name

none

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:

  • sampleapp-users.properties
  • sampleapp-roles.properties

CLI Commands for Adding the UserRoles Login Module

/subsystem=security/security-domain=sampleapp:add

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

Resulting XML

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