Container-managed security is something good because the developer can focus on what(!) resources have to be secured and not how this can be done. We call this declarative security. Unfortunately container-managed security requires a bunch of configurations. These configurations differ between various application servers and sometimes between different versions of the same server as well. This relativises the usefulness of container-managed security somewhat. The subsequent specified procedures have been tested with JBoss AS 7.1.1 and Wildfly 8.2.0. Recently RedHat seems to push its commercial EAP platform. That is RedHat doesn't provide compiled binaries e.g. for the JBoss AS 7.3 which corresponds to the 'hardened' EAP 6.2.0 commercial JBoss AS variant. You would have to download the sources and build the binary by yourself. Crosscheck the procedures with your documentation if you use one of the EAP 6.x.x or rather JBoss AS 7.2+ variants.

All specified procedures refer to a "standalone server" using the standalone-full.xml profile.

Since we want to authenticate against credentials stored in a (SQL-)database we need to create some tables containing the accounts and the roles. The Example application assumes the data definitions shown below. I'm using MySQL here but the DDL-statements are simple enough and should be roughly the same for other SQL-databases.

We need some test accounts as well. The following DML-statements will populate the tables with two accounts. The 'supertester' account holds both the 'appadmin' role and the 'appuser' role whereas the 'tester' account holds only the 'appuser' role. The Base64 encoded salt values have been chosen by chance. The password columns contains the password hash value concatenated with the salt as explained in section SaltedPasswordLoginModule.

The plaintext passwords of 'supertester' and 'tester' are 'Abracadabra' or rather 'Simsalabim'.

[Top]

The application server needs access to the database containing the credentials. Thus we need to install a JDBC driver compatible to the used database. Download the driver from your database vendor. This guide assummes a JDBC 4 compliant driver. There are several options to install a JDBC driver: via Admin GUI, as module or by deploying. We are using the latter method. First start the server:

$ cd <WILDFLY_INSTALL_DIR>/bin
$ ./standalone.sh --server-config=standalone-full.xml

Now switch to another shell within the same directory and type:

$ ./jboss-cli.sh --connect --commands="deploy <PATH_TO_DRIVER>/mysql-connector-java-5.1.30-bin.jar"

Next we request a list of the deployed drivers:

$ ./jboss-cli.sh --connect --commands=/subsystem=datasources:installed-drivers-list
{
    "outcome" => "success",
    "result" => [
        {
            "driver-name" => "mysql-connector-java-5.1.30-bin.jar_com.mysql.fabric.jdbc.FabricMySQLDriver_5_1",
            ...
        },
        {
            "driver-name" => "h2",
            ...
        },
        {
            "driver-name" => "mysql-connector-java-5.1.30-bin.jar_com.mysql.jdbc.Driver_5_1",
            "deployment-name" => "mysql-connector-java-5.1.30-bin.jar_com.mysql.jdbc.Driver_5_1",
            "driver-module-name" => undefined,
            "module-slot" => undefined,
            "driver-datasource-class-name" => undefined,
            "driver-xa-datasource-class-name" => undefined,
            "driver-class-name" => "com.mysql.jdbc.Driver",
            "driver-major-version" => 5,
            "driver-minor-version" => 1,
            "jdbc-compliant" => false
        }
    ]
}

The last line stating that the driver isn't JDBC-compliant seems somewhat odd, but look at Bug #62038 Connector/J Driver reports itself as not jdbc compliant. So this comes from MySQL not being SQL-92 compliant.

Now we can configure a datasource by referencing the name of the previously installed driver. Additionally, we have to specify the (JNDI-)name of the datasource, a connection URL, user credentials for the application server and the connection pool size:

$ ./jboss-cli.sh --connect --commands="data-source add --name=salt_example --connection-url=jdbc:mysql://localhost:3306/salt_example --jndi-name=java:/jdbc/SaltExampleDS --driver-name=mysql-connector-java-5.1.30-bin.jar_com.mysql.jdbc.Driver_5_1 --user-name=<USER_NAME> --password=<PASSWORD> --max-pool-size=15 --min-pool-size=5"

We are using a (MySQL-)database named 'salt_example' here. The application server needs an account when connecting to the database. Within the Example Application the datasource can be requested by its JNDI name 'java:/jdbc/SaltExampleDS'. You may need to enable the datasource:

$ ./jboss-cli.sh --connect --commands="data-source enable --name=salt_example"

You may test the configured connection via the Admin Console. Before you can do this you need a management account. Consult your Getting Started with WildFly 8 or rather Getting Started with JBoss Application Server 7 if required. Now stop the server again:

$ ./jboss-cli.sh -c --command=shutdown

Or rather:

$ ./jboss-cli.sh -c --command=:shutdown

[Top]

The whole procedure with (salted) hashed passwords would be fully pointless if the plaintext passwords were sent over the wire. Hence we need an encrypted connection between the client and the server. The SSL protocol uses public key cryptography to negotiate a symmetric session key for further encryption between both parties. That is we need to create a key pair by using the keytool command provided by the JDK (see Security Tools for further information):

$ cd <WILDFLY_INSTALL_DIR>/standalone/configuration
$ export JAVA_HOME=<PATH_TO_JDK>
$ ${JAVA_HOME}/bin/keytool -genkeypair -alias server -keyalg RSA -keystore server.keystore -validity 365 -storepass changeit -dname "cn=myserver" -keypass changeit

This creates a keystore with password 'changeit' containing our keypair which can be referenced by the alias 'server'. Next we have to fiddle with the standalone-full.xml configuration file.The following XML segment must be inserted within the <security-realms> section if you use WildFly 8.2.0. The procedure is different for JBossAS 7.1.1 and will be explained later on.

Now we must define a https listener within the undertow-subsystem which uses the just now configured security realm.

For JBossAS 7.1.1 you would have to insert the following XML segment. First search for the definition of the normal http connector within the web-subsystem (namespace is urn:jboss:domain:web:1.1). There must be a redirect-port-attribut supplemented. This ensures that http requests will be redirected to the secured connection.

[Top]

What is missing is the connection between our SaltedPasswordLoginModule and the application. The first step in this direction is to define a security-domain for authentication within standalone-full.xml which references the fully qualified class name of our login module. The final link will be the definition of the web descriptors at application level as explained in the next section.

The configuration above includes the usage of two of the supported basic options, in this case the to be used datasource when retrieving the hashed password and salt and to enforce case sensitivity in string search by MySQL.

[Top]

Within the jboss-web.xml-descriptor in the WEB-INF folder we define the security domain that should be used when a request to a secured resource has been made:

Finally we are ready to secure our web resources by declaration. This will be done within the standard web.xml-descriptor. My Example application uses an unsecured page containing a link to a secured resource. Without a session following the link triggers the display of a predefined login page. Upon successfull login the secured resource can be accessed by users which hold the 'appadmin' or the 'appuser' role. Additionally there exists another page which can be a accessed only by users holding the 'appadmin' role. Below the complete web.xml of the Example application is shown. I'm using a Java Server Faces application here. The interesting things begin with line 20.

From line 20 to line 36 the first security constraint is defined. This constraint secures the resource /pages/main.jsf and covers the authentication and the encryption of the transported user data. That is any user who wants to access the resource must be authenticated and all the data will be encrypted during the process. The authentication succeeds if a certain user holds the 'appadmin' or 'appuser' role. The second security constraint (line 37 to 52) secures the resource /pages/admin/manager.jsf. Only users with 'appadmin' role will be granted access to the page. Within line 53 to line 60 the authentication method is defined. We are using FORM authentication here, that is we have to provide a custom login.html page which follows some conventions. After a failed authentication the user will be redirected to an error page. From line 61 to 68 the roles known to the declarative security approach are defined.

The web.xml-descriptor for JBossAS 7.1.1 is almost identical. Only the namespace, version and schemalocation declared in line 2 are different:

[Top]