JAAS-secured JAX-RS end point

Deny WuysanSeptember 11th, 2013Last Updated: September 10th, 2013

0 82 5 minutes read

With the advent of RESTFUL (JAX-RS) as the “preferred” way to create web service end points, for a long time I have always wondered how people implement security mechanism around it.

At the end of the day, I presume the underlying implementation of JAX-RS is servlet, and therefore its security might also be around what is already provided by the container, i.e. JAAS.

This post will cover my findings on how to step-by-step implement FORM-based security using JDBC realm, JAX-RS and how to test it using cURL, on Glassfish 3.

Setting up JDBC-realm

Firstly, since we are using JDBC-realm, let’s assume that we have created a JDBC connection to the underlying database under the JNDI jdbc/test.

The next step is to create a new realm. You can do this by going to server-config > Security > Realms and add a new realm. Select the realm type com.sun.enterprise.security.auth.realm.jdbc.JDBCRealm, and then populate the mandatory fields.

Start by giving your new realm a name.
For JAAS Context, put jdbcRealm
Populate JNDI name, preferably starts with "jndi/"

Next, do pay attention to the rest of the fields. It seems that Glassfish expects to see two tables. The first table is to contain a list of users, with usernames as their unique identifier. The second table is to list the groups that each user belongs to. Username is to be the foreign-key link between the two tables. (The next section should give you better idea on how the tables should look, they are after all very simple).

Once these tables are created, we can then populate the mandatory fields accordingly.

Populate database for testing purpose

The next step is to populate the table for testing purpose. Let’s just assume that we will be testing using username hpotter and password test. For the password however, note that Glassfish digest by default is SHA-256, as illustrated by the following screen shot.

Hence, you need to encode the password test before insert. You can use encoder by technipixel, which will give you the String 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.

The next step is to write some INSERT statements:

INSERT INTO person (id, password, username) VALUES (1, '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', 'hpotter');
COMMIT;
INSERT INTO person_role (username, user_group) VALUES ('hpotter', 'User');
INSERT INTO person_role (username, user_group) VALUES ('hpotter', 'Admin');
COMMIT;

Let’s move on to the next step.

Securing web application using JAAS

Quite a number of tutorials out there on JAAS with FORM authentication method. However, I thought I put it here again, with the hope that some might find it simpler.

web.xml

Make the following modification to your web.xml

<welcome-file-list>
        <welcome-file>/index.jsp</welcome-file><!-- 1 -->
    </welcome-file-list>
    <security-constraint><!-- 2 -->
        <display-name>TestConstraint</display-name>
        <web-resource-collection>
            <web-resource-name>TestResource</web-resource-name>
            <description/>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <description/>
            <role-name>User</role-name>
            <role-name>Admin</role-name>
        </auth-constraint>
    </security-constraint>
    <login-config><!-- 3 -->
        <auth-method>FORM</auth-method>
        <realm-name>testRealm</realm-name>
        <form-login-config>
            <form-login-page>/login.html</form-login-page>
            <form-error-page>/error.html</form-error-page>
        </form-login-config>
    </login-config>
    <security-role><!-- 4 -->
        <description/>
        <role-name>User</role-name>
    </security-role>
    <security-role><!-- 5 -->
        <description/>
        <role-name>Admin</role-name>
    </security-role>

Let’s go through them one-by-one.

This is the file to be displayed on successful login. You can also use this file as redirection. For example, suppose you have a file called index.xhtml (a JSF page), you can use response.sendRedirect("index.jsf");
This is the actual constraint, i.e. how you secure the application. This section is basically there to secure all access to the application, denoted by /* url pattern, and only allow access of user with the role of User and Admin.
This part denotes that what we are using is FORM authentication method (which I’ll explain in more detail in the next section). Important part is to ensure the correct name of the security realm used, which in this case, testRealm, the same realm name we have given when setting it up via Glassfish admin page. The other part is to set the page containing j_security_check that the application will automatically redirect to in the event of request access has not been authenticated yet.
The known role
Same as previous section.

glassfish-web.xml

We also need to configure glassfish-web.xml so that the container knows about the mapping between groups from the database and the role recognised by the application.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN" "http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
<glassfish-web-app error-url="">
    <security-role-mapping>
        <role-name>Admin</role-name>
        <group-name>Admin</group-name>
    </security-role-mapping>
    <security-role-mapping>
        <role-name>User</role-name>
        <group-name>User</group-name>
    </security-role-mapping>
    <class-loader delegate="true"/>
    <jsp-config>
        <property name="keepgenerated" value="true">
            <description>Keep a copy of the generated servlet class' java code.</description>
        </property>
    </jsp-config>
</glassfish-web-app>

N.B. If you use Netbeans, this file might be generated for you.

Login page: login.html

If we refer again to web.xml above, notice that the login page is pointing to login.html. For FORM authentication method, as per specification, we need to have a form with j_security_check, with j_username and j_password (Oracle 2013).

<!DOCTYPE html>
<html>
    <body>

        <form action="j_security_check" method="post">
            <p>
                <strong>Username</strong>
                <input type="text" name="j_username" size="25" />
            </p>
            <p>
                <strong>Password</strong>
                <input type="password" size="15" name="j_password" />
            </p>
            <p>
                <input type="submit" value="Submit" />
                <input type="reset" value="Reset" />
            </p>
        </form>
    </body>
</html>

With all of these completed, we can start up Glassfish, deploy our application and test it using any browser. Upon accessing the application, users should be directed to login.html to login. Remember to use hpotter as username and test as password. On successful login, the user should be redirected to index.jsp (which in turn redirects user to index.jsf, or anything the index.jsp is redirecting to, according to your requirement).

Create a RESTFUL end point

The next step of course is to create a RESTFUL end point, which is very simple. One of the posts I have written here might also be useful.

To start, assuming we have the following application path.

package com.dwuysan;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

/**
 * @author denywuy
 */
@ApplicationPath(value = "resources")
public class ApplicationConfig extends Application {
}

Let us assume that we have the following simple RESTFUL service.

package com.dwuysan;

import com.dwuysan.entity.Outlet;
import com.dwuysan.service.OutletService;
import javax.annotation.ManagedBean;
import javax.annotation.security.RolesAllowed;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Path(value = "generic")
@RolesAllowed(value = "User")
@ManagedBean
public class GenericResource {

    @Inject
    private OutletService outletService;

    @GET
    @Path("{id}")
    public Outlet get(@PathParam(value = "id") final long id) {
        return this.outletService.getOutlet(id);
    }
}

Note that we have secured this service with javax.annotation.security.RolesAllowed annotation.

Testing secured RESTFUL service using curl

Given the RESTFUL service we created above, we should be able to test it using CURL with the following command:

curl -X GET -H "Accept:application/json" -H "Content-Type:application/json" http://localhost:8080/testApp/resources/generic/101

The above command translate to the following: hit the URL above using GET, with the headers Accept:application/json and Content-Type:application/json (cURL 2013)

Since we have secured our application, invocation as above will not work. The user will be redirected to login.html. Hence, our aim now is to first login. With cURL, we can submit parameters to login, i.e. username and password, and then obtain the cookie. To do that, we can use this command:

curl -b cookies.txt -c cookies.txt -d "j_username=hpotter&j_password=test" http://localhost:8080/testApp/j_security_check

This command is submitting username and password, to the j_security_check (remember our login.html that we have created previously), and storing the cookies obtain under the file cookies.txt.

If you open your cookies.txt, you may see the following:

# Netscape HTTP Cookie File
# http://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

#HttpOnly_localhost     FALSE   /testApp     FALSE   0       JSESSIONID      245a317ab91fbb28244403346770

N.B. You might receive Document Moved response. This means login has been successful. Otherwise, you would get the raw html of the error.html again.

Once we have been authenticated successfully, we can use the cookies we have obtained from the login to invoke the RESTFUL service.

curl -X GET -H "Accept:application/json" -H "Content-Type:application/json" -b cookies.txt -c cookies.txt http://localhost:8080/testApp/resources/generic/101