• inShare1

This tutorial has been tested with Glassfish 3.1.2. It will tell you how to integrate container managed authentication and authorization features offerd by Glasfish 3 into your Java EE application using different technologies. We will create a very simple application with the following features and requirements:

• any anonymous user can create/register a new account
• an already registered user can login with her/his credentials (username and password)
• some resources require a login, others are available to the public
• automatic redirection to a login page if user is not authenticated
• https is mandatory after login as well as for the login/register page
• users and roles are managed in a database (jdbcRealm)

To implement our “little” requirements we will use Glassfish 3, PostgreSQL, EJBs, JAAS, JPA, REST, JSON, AJAX, jQuery and even much more. So it would help if you are kind of familiar with all that stuff. If you are familiar with all that, you might need only a few hours to walk through this tutorial. Please consider that I have chosen not to use Maven. I believe that this allows a larger audience to follow this tutorial. This tutorial does not handle how to install Glassfish 3. I also expect you have already installed a PostgreSQL database. Other databases are also fine, but I will only handle PostgreSQL in detail when it comes to creating a JDBC resource on Glassfish and then using JPA to access it. Please refer to the security section of the official Oracle Java EE 6 Tutorial for an overview of how to secure Java EE 6 Web Applications. If you don’t know it already you might want to check The Open Web Application Security Project (OWASP). As a starting point you could begin with their page about Access Control In Your J2EE Application.

This tutorial requires some external libraries. Why and where they are needed is also discussed in this tutorial. Since I decided not to use maven (see above) please make sure to download the external dependecies (see below) manually and place them into the lib folder of your web application (you could still use maven if you want). All these dependencies are also packaged in the Downloads I offer below – so you might prefer that one instead of finding and downloading each jar one by one. To be honest, I used maven to get all these dependencies and then I just copied them one by one into the lib folder. Since Glassfish 3.1.2 ships with Jersey 1.11 you should make sure to get jersey-json version 1.11 and not 1.12.

• commons-codec-1.6.jar (Apache Commons Codec)
• jersey-json (Maven coordinates: groupId=com.sun.jersey, artifactId=jersey-json, version=1.11)
  • activation-1.1.jar
  • jackson-core-asl-1.9.2.jar
  • jackson-jaxrs-1.9.2.jar
  • jackson-mapper-asl-1.9.2.jar
  • jackson-xc-1.9.2.jar
  • jaxb-api-2.2.2.jar
  • jaxb-impl-2.2.3-1.jar
  • jersey-core-1.11.jar
  • jersey-json-1.11.jar
  • jettison-1.1.jar
  • stax-api-1.0-2.jar
  • stax-api-1.0.1.jar

As we have defined requirements for allowing new users to register new accounts we need to define where and how we want to store the account data for each user. An already registered user can login with her or his credentials. That means we need to be able to create new user accounts (user registration) as well as reading/finding existing user account data (login) for authentication and authorization. Authorization means we want to consider that authenticated users need to have a specific role assigned in order to be authorized to access restricted content. The relationship between users and roles needs also to be considered for our data storage.

Besides username and user password usually you also want to have some more information from your users, i.e. first name, last name, address etc. This kind of data depends on your own requirements – for illustration purposes I will only store the users first name, last name and registration date. When developing web applications at some point you have to ask yourself what data you want and how to store them. This can lead to a user management component which offers APIs for your requirements. Once you know what data you want to store you need to think about the storage itself. In this tutorial we will benefit from the Glassfish 3 and Java EE 6 features for storing all of our data in a database (i.e. credentials, last name, first name) and then using them for securing our web application (athentication and authorization). Later we will explain how to configure Glassfish for weaving everything together, but for now we will create our data model for our user management component.

When having a data model in your mind you could either write down the SQL statements to create the tables you want. Then you could write your own layer for accessing and manipulating the data. This is what we will not do here. Instead, we will implement JPA 2.0 Entity Classes and make our tables being generated automatically by JPA. This also allows us to easily access available user data stored in our database, manipulate them or to create new entities (i.e. for creating a new user account). The data model for our user management component looks as follows:

As you can see we will have two tables: USERS and USERS_GROUPS. The primary key of our USERS table is the email address. The password of each user is also stored in that table as well as the firsname, lastname and the registration date. Later we will see how to assure that the password field does not contain a clear text password. The second table is the USERS_GROUPS table. It contains the mapping between users and groups. Therefore it has exactly two fields: the email field is a foreign key and the groupname contains the group name (String/varchar) assigend to a user. Both fields together are unique, i.e. a user can be assigned to a group only once while the user can be assigned to multiple different groups. From that little piece of information we can derive how our JPA classes should look like. Please consider that you usually want to start with the JPA classes before thinking about how your DB tables will look like. I have choosen to describe it here the other way around only for pedagogical reasons.

To make it easy I believe that it’s a good idea to model our groups as a simple enum. Let’s assume we have administrators and registered users that use our web application. We also could have other groups, i.e. I have just added a default group for demonstration reasons. The Group enum could look as follows:

Now we can think about our User Entity class. Every user has an email address which serves as the unique identifier of the user. I have defined that the length of the field is 128 – actually this might be way more than you will ever need (you could also use 64 or what ever instead). The attributes firstName, lastName and registeredOn are also pretty much straight forward – I want them always to be filled and that’s why they cannot be null.

The password field is more interesting. As I mentioned above the user password should never be stored as clear text on the database. If you won’t follow that rule then people who might have gained access to our USERS table could see the original passwords and abuse them (there are different horrible scenarios for that but we will not discuss them here). So a good idea to solve this issue is to only store hashed values on the DB. Please consider that MD5 is not save anymore, so never use MD5 in a critical environment. I have chosen to use SHA-512 which is considered to be pretty safe. I have also chosen to use SHA-512 in combination with a hexadecimal encoding/representation. But what length do we now need for our password field (length of column in DB)? As its name indicates SHA-512 is 512 bits long. Since we are using an hexadecimal encoding, each digit codes for 4 bits. So you need 512 : 4 = 128 digits to represent 512 bits. That means on the DB you would need a varchar(128) to store SHA-512 HEX values. Actually, you could also use a char(128) because the length stays always the same – it is not varying at all, no matter how long the input String initially was before letting SHA-512 + HEX to run over it. Please consider that in real life projects you might even go one step further and hash the password with a “salt”. You might want to check this to see why you should add a salt. I will not use a salt in this tutorial because I want this tutorial to be kind of easy to follow. For creating a SHA-512 HEX value for a given String we can simply use the Apache Commons Codec library. So please make sure to add the Apache Commons Codec library to your application!

Attention: I store the password as a String. Everywhere I use a password (also in my REST APIs which will be discussed later) I use a String. From security point of view this is not a good idea! From security point of view it is much better to use a char array for such sensitive data! For more information about that please ask Google – this topic is out of scope for this tutorial. I have not used a char array in this tutorial only for pedagogical reasons (I don’t want to make it too complex…). As you will see later the Servlet 3.0 API offers HttpServletRequest.login(String username, String password) which is also using a String instead of a char array for passing the password. I am sure the Java EE Spec guys have a good reason reason for that.

The next interesting attribute is groups. It contains a list of all the groups which the user has been assigned to. One of our constructors offers to initialize some of the attributes by expecting an UserDTO. DTO stands for Data Transfer Object and is a simple pattern for passing data. As you will see later we will user the UserDTO for our registration REST Service (although some of you might say that DTOs are kind of old school…). Since we have this constructor we also have to offer a default constructor (parameterless). Usually you should validate your attributes at some point. For demonstration I only validate the passwords – and that only in the the constructor which expects a UserDTO (later you will understand what password1 and password2 is). Actually, you could also user Bean Validation (JSR 303) but in this tutorial we are not going to use Bean Validation at all. Please also consider that we do not use any JAXB annotations (i.e. @XmlRootElement). The JPA annotations you see avoid using a mapping table. And here is the source for both the User Entity and UserDTO:

So far we have defined a very simple model for our user management compoment. It’s time to implement an interface that uses our Entities, i.e. for saving a new user to the database. For this purpose we will use a simple Stateless Session Bean. Per default our UserBean EJB is only accessible locally (No-Interface View). We don’t want it to be accessible from any remote clients:

We are using JPA, therefore we also want to define a persistence.xml file:

We have named our one and only Persistence Unit authPU. If we had multiple Persistence Units then we would have to specify which of our Persistence Units shall be used for our EntityManager in our UserBean, i.e. like this (see UserBean.java above):

Now we want to tell Glassfish where our DB is, which credentials to use when connecting to the DB and so on. As I have mentioned earlier we want to connect to a PorstgreSQL database. There are different options for adding new JDBC Resources to Glassfish:

• creating it via Admin Console (web frontend for Glassfish administration)
• using asadmin create-jdbc-connection-pool and create-jdbc-resource (see here and here)
• using glassfish-resources.xml file + asadmin add-resources (see http://docs.oracle.com/cd/E18930_01/html/821-2433/add-resources-1.html#scrolltoc)

I never use option 1 because it doesn’t support automated scripts. I prefer option 2 or 3, but I will only tell you how to configure all of your resources (in our case only a jdbc-connection-pool) into a glassfish-resources.xml file and afterwards how to add all of your resources defined in that file via asadmin add-resources to Glassfish (option 3). So first of all we will create the glassfish-resources.xml file:

As you can see our glassfish-resources.xml defines a JDBC resource. With that configuration Glassfish can manage DB connections. In our case we have configured a PorstgreSQL database. Please see the official documentation for more details regarding the parameters I have used. The next step is to tell Glassfish about our jdbc-resource defined in the glassfish-resources.xml file by executing a asadmin add-resources command:

A common format for data exchange between web frontend and backend system is JSON. Most tutorials you find will tell you how to use JAXB (Java API for XML Binding) and its Java annotations for generating JSON. Once you have done what those tutorials told you suddenly you see some very strange JSON fromat which is not what you expected. At this point you might look for other tutorials or blogs that tell you what else you have to do in order to get a natural JSON representation of your POJOs by using JAXB. If you are lucky, then you will find the POJOMappingFeature that is shipped with Jersey. But then you find out that you still have null values in your generated JSON Strings. So you keep asking Google for aome annotations or some other Features like the POJOMappingFeature that allow you to get rid of the null values. Then you find some annotations and code snippets that seem not to work for you because you don’t have the correct libraries or library versions on your Glassfish classpath. With your last breath you have come to a point where you are getting ready to develop your own @Provider classes to generate JSON from POJOs and vice versa. Since you have found this tutorial you don’t have to implement your own @Provider classes and you don’t have to use JAXB.

JAXB is a great thing. But in case you only need JSON and no XML at all, like in our case, then JAXB might not be the best choice. JAXB allows to convert your POJOs to JSON and vice versa. But it always generates XML in an intermediate step and that’s what we actually don’t need. Furthermore you have to annotate your classes with @XmlRootElement, but what happens if you don’t have the sources of classes that you want to convert to JSON? So there can be good reasons for not using JAXB, it depends from case to case… As an alternative you could use Google’s gson (which is by the way really great). But since we are in a Glassfish world (at least here in this tutorial) we will use Jackson (Jersey is based on Jackson). Please keep in mind that I have tested this tutorial with a Glassfish 3.1.2 installation. The 3.1.2 version ships with Jersey 1.11 (you can easily check your Jersey version in the server output when you start your Glassfish, i.e. something like this: Initiating Jersey application, version ‘Jersey: 1.11 12/09/2011 10:27 AM’). By the end of 2011 Jersey was modularized. What we actually want is to have all the jersey-json maven dependencies in our project. But since I have promised not to use Maven you have to add them all one by one to your classpath. Please download all the jars listed on the Jersey Dependencies page under 11.4.1. JAXB (we only need the jersey-json dependencies). Hint: I have added all the relevant dependencies to the /WEB-INF/lib/ folder of the downloadable sources below. If you want some more information about the different Jackson packages please check here. By the way: we are using Jackson 1.9.2 and we want to configure Jackson globally in our own @Provider class. Instead we could also use @Json* annotations, i.e. @JsonSerialize(include = Inclusion.NON_EMPTY). Inclusion.NON_EMPTY tells Jackson not to include null values or empty collections. That’s it – the rest happens without any further configuration Please check here in case you have multiple Providers for the same type.

The browser (or any client) sends HTTP requests to our Glassfish server in order to consume our REST Services. If the server is able to process the request it returns the response data itself and a HTTP Status code that tells the caller if everything was ok or not. There are a lot of HTTP Staus codes defined in the HTTP Spec, I am sure you know at least 404 (Not Found), 200 (OK), 500 (Internal Server Error). On our frontend we use jQuery (frontend is discussed later). When executing Ajax requests with jQuery the error callback function that you define for your Ajax call is called automatically by jQuery depending on the HTTP Status code of the response. Besides that you could also define a statusCode object for your Ajax call and define callback functions for each HTTP Status code you are interested in (later you will see some example code below). When implementing your backend services you always want to implement a safe error handling, you want to consider everything that could happen. Once you know what could happen you start thinking about what HTTP Status code should be returned for each specific case, i.e. you might want to return a 404 in case the ID for your getBookById Service doesn’t exist in the database, or you might want to return a 403 in case the user doesn’t have enough privileges to call your getBookById service. This little example should only tell you that you could and should make use of the HTTP Status codes. But then there are also cases where you cannot clearly identify which HTTP Status you should return. Furthermore using all of the possible HTTP Status codes could also require additional lines of code within your frontend in order to “react” correctly. You should decide whether you want to treat the HTTP Status code as part of your REST APIs or not, and that decision can be different from project to project, or even from service to service (latter might not be the best solution). I usually make use of only a few HTTP Status codes, i.e. 404, 403, 500, 200 etc. Besides that I use a JsonEnvelope which separates the response data itself and the “application” status of the request. In all my JSON responses I use this JsonEnvelope – a very simple POJO which is not even extending javax.ws.rs.core.Response (ok, maybe I was a little lazy to extend javax.ws.rs.core.Response…). The application status (you might want to use another term for that, maybe “app request status”) is something different than the HTTP Status. To demonstrate this all let’s talk about our login service which is discussed in detail later: For now we only want to consider two cases (although there can be more). The first case is “Login succeeded” – in that case the HTTP Status is 200 (OK) and the JsonResponse status (aka application status) could be “SUCCESS”. The second case is “Login failed” – in that case the HTTP Status still stays at 200, whereas the JsonResponse status is “FAILED”. You don’t have to do it the way I decided, there are other options as well. Feel free to choose your own “Best Practics”. Please also consider that I have added a version attribute to the JsonResponse class because we might have different client technologies (not only our web frontend) and we might want to change the attributes of our JsonResponse. Here is the source code for our JsonResponse class: