Configure UsersRolesLoginModule for JBoss EAP 6

Introduction

In this blog I will show you how to configure a simple JAAS login module, that holds username, passwords and roles in properties file. The login module for this job is org.jboss.security.auth.spi.UsersRolesLoginModule.

Finding the correct source code and documentation for the JBoss EAP 6 login modules, can be a bit tricky and the reason for that, is that the concrete implementation for them are hosted in the sister project Picketbox. For example the exact version that is shipped with JBoss EAP 6.1.0 is 4.0.17.Final-redhat-1. And the jar is located under $JBOSS_HOME/modules/system/layers/base/org/picketbox/main/.

The UsersRolesLoginModule has more to offer than I will show you here, and that is to store the password scrambled and not in clear text. But since the UsersRolesLoginModule is merely for test purpose, I will leave that out here.

Configuration

I will use JBoss EAP 6 in standalone mode, which means that the JBoss configuration file is $JBOSS_HOME/standalone/configuration/standalone.xml. Open it and add the below JAAS security-domain.

        <subsystem xmlns="urn:jboss:domain:security:1.2">
            ...
            <security-domains>
                <security-domain name="basic-policy" cache-type="default">
                    <authentication>
                        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
                            <module-option name="usersProperties" value="${jboss.server.config.dir}/basic-user.properties"/>
                            <module-option name="rolesProperties" value="${jboss.server.config.dir}/basic-roles.properties"/>
                        </login-module>
                    </authentication>
                </security-domain>
            </security-domains>
        </subsystem>

Create Users and Assing Roles

Creating users and theirs associated roles are easy since them are located in clear plain text files located under $JBOSS_HOME/standalone/configuration/. Here I will only create one user and one role, but you can create as many as you please.

$ echo "admin=password" > $JBOSS_HOME/standalone/configuration/basic-user.properties

$ echo "admin=ROLE_FOO" > $JBOSS_HOME/standalone/configuration/basic-roles.properties

Configuration

The easiest way to test the security, is to either take an existing war project or create a new zip file add a welcome file (index.html), web.xml and jboss-web.xml. Either way the relevant configuration for the web.xml is below.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">

    ...

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Foo Pages</web-resource-name>
            <url-pattern>/*</url-pattern>
            <!-- Do not specify http-method, since then only specified http-method 
                will be authenticated, not e.g. JUNK (attack) -->
        </web-resource-collection>

        <auth-constraint>
            <description>These are the roles who have access.</description>
            <role-name>ROLE_FOO</role-name>
        </auth-constraint>

        <user-data-constraint>
            <description>This is how the user data must be transmitted.</description>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>basic-policy</realm-name>
    </login-config>

    <security-role>
        <role-name>ROLE_FOO</role-name>
    </security-role>

    <welcome-file-list>
        <welcome-file>/index.html</welcome-file>
    </welcome-file-list>

    <session-config>
        <!-- Session timeout after X MINUTES after no user interaction. -->
        <session-timeout>15</session-timeout>
        <cookie-config>
            <!-- XSS attack: make sure that cookie cannot be accessed via client 
                side scripts -->
            <http-only>true</http-only>
            <!-- CSRF attack, session hijack attack: require cookie can only be used 
                for SSL communication. -->
            <secure>true</secure>
        </cookie-config>
        <!-- Do not use URL, since then it can be stored in numerous places: browser 
            history, proxy server log, referrer logs, web logs, etc. -->
        <tracking-mode>COOKIE</tracking-mode>
    </session-config>

    <!-- Custom error pages are handled in custom ErrorReportValve in jbossweb module -->

</web-app>

And the relevant portion in jboss-web.xml.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
    <context-root>/example-app</context-root>
    <security-domain>java:/jaas/basic-policy</security-domain>
</jboss-web>