RESTful Basic HTTP authentication with tomcat JDBCRealm

Hi All,

In this post I will describe how to secure a web application which expose a RESTful API.

I will use JDBCRealm – an implementation of the Tomcat  Realm interface that looks up users in a relational database accessed via a JDBC driver.

1. First we need to create three new database tables for storing users and groups:
   users – with two columns: name (primary key) and password (hashed).
   groups – with one column: name (primary key).
   users_groups – with two columns: name & groupname (many to many)
2. Second we need to enable JDBCRealm at server.xml  by adding:
   

   <Realm name=”” className=”org.apache.catalina.realm.JDBCRealm”

          driverName=”org.gjt.mm.mysql.Driver”

          connectionURL=”jdbc:mysql://localhost/db_name”

          connectionName=”root” connectionPassword=””

          userTable=”users” userNameCol=”name”                        userCredCol=”password” 

          userRoleTable=”users_groups” roleNameCol=”groupname”

          digest=”sha-256″/>

   (We are storing the password encrypted with sha-256 algorithm)

3. Now it is recommended to configure tomcat with SSL:
   Generate keystone file and password by running in shell :

   keytool -genkey -alias techtracer -keypass ttadmin -keystore techtracer.bin -storepass ttadmin. 
   And add to server.xml :

   <Connector SSLEnabled=”true” acceptCount=”100″ clientAuth=”false” disableUploadTimeout=”true” enableLookups=”false” maxThreads=”25″ port=”8443″ keystoreFile=”/your_location/.keystore” keystorePass=”your_password” protocol=”org.apache.coyote.http11.Http11NioProtocol” scheme=”https” secure=”true” sslProtocol=”TLS” />

   <Connector port=”8009″ protocol=”AJP/1.3″ redirectPort=”8443″/>

4. Finally we we need to update web.xml :
   

   <security-constraint>

           <web-resource-collection>

                   <web-resource-name>your_server</web-resource-name>

                   <url-pattern>/*</url-pattern>

                   <http-method>GET</http-method>

                   <http-method>POST</http-method>

                   <http-method>PUT</http-method>

                   <http-method>DELETE</http-method>

           </web-resource-collection>

           <auth-constraint>

                   <role-name>server-user</role-name>

           </auth-constraint>

           <user-data-constraint>

                   <transport-guarantee>CONFIDENTIAL</transport-guarantee>

           </user-data-constraint>

   </security-constraint>

   <login-config>

           <auth-method>BASIC</auth-method>

   </login-config>

We did it!

Creating a RESTful web services using Jersey

What are RESTful web services?

Representational State Transfer (REST) is an architectural style that specifies constraints, such as the uniform interface, that if applied to a web service induce desirable properties, such as performance, scalability, and modifiability, that enable services to work best on the Web. In the REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs), typically links on the Web. The resources are acted upon by using a set of simple, well-defined operations. The REST architectural style constrains an architecture to a client/server architecture and is designed to use a stateless communication protocol, typically HTTP. In the REST architecture style, clients and servers exchange representations of resources by using a standardized interface and protocol.

The following principles encourage RESTful applications to be simple, lightweight, and fast:

• Resource identification through URI: A RESTful web service exposes a set of resources that identify the targets of the interaction with its clients. Resources are identified by URIs, which provide a global addressing space for resource and service discovery.
• Uniform interface: Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT, GET, POST, and DELETE. PUT creates a new resource, which can be then deleted by using DELETE. GET retrieves the current state of a resource in some representation.POST transfers a new state onto a resource.
• Self-descriptive messages: Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, JPEG, JSON, and others. Metadata about the resource is available and used, for example, to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control.
• Stateful interactions through hyperlinks: Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, such as URI rewriting, cookies, and hidden form fields. State can be embedded in response messages to point to valid future states of the interaction.

Jersey

Jersey is the open source, production quality, JAX-RS (JSR 311) Reference Implementation for building RESTful Web services. But, it is also more than the Reference Implementation. Jersey provides an API so that developers may extend Jersey to suit their needs. you can read more here.

So how to use it?

1. Download Jersey and add the following jars into your project:
   asm-3.1.jar, jersey-core-1.8.jar, jersey-server-1.8.jar, jsr311-api-1.1.1.jar, ersey-json-1.8.jar, jersey-bundle-1.8.jar
2. Add to web.xml
   

   <servlet>

   <servlet-name>Jersey REST Service</servlet-name>

   <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>

   <init-param>

   <param-name>com.sun.jersey.config.property.packages</param-name>

   <param-value>com.company.package-name</param-value>

   </init-param>

   <load-on-startup>1</load-on-startup>

   </servlet>

   <servlet-mapping>

   <servlet-name>Jersey REST Service</servlet-name>

   <url-pattern>/rest/*</url-pattern>

   </servlet-mapping>

3. Create a Restful service class
   

   @Path(“/team”)

   public class RestfulService{

      @GET

      @Produces(MediaType.APPLICATION_JSON)

      public List<Model> getResult() {

         // return result

      }

   }         

4. Add JSON support to your model by adding annotation
   

   @XmlRootElement 

   public class Model {

      //class members

      //getters

      //setters

   }

And that is all folks…

Getting Started

I am creating a cross-platform mobile application designed to serve millions of sports fans. In the coming posts I will focus on designing and developing the application server.

The server should include the following capabilities:

• Registration and authentication.
• Exposing services to the end users such as database queries, updates etc.
• Sending push notification to end-users.
• Managing real-time content such as live scores.
• Exposing an administration API for data updates, user actions statistics etc.

High level design of the system:

As I see it, there are three main modules:

1. Model Services Module – consists of Restful Services expose an API to all end users in HTTP protocol, Model Services contain the business logic, Model DAOs handle object CRUD (create, update, delete) actions and a DB which stores the data.
2. Content Management Module – gets & processes real-time content from external Live-Feed service, stores it in a Memcache and notifies about relevant events.
3. Push Notification Module – sends push notification to all devices through Android C2DM (Cloud to Device Messaging) and Apple APNS (Apple Push Notification Service) servers.

Another important module which will be discussed later is the Authentication Module relevant to all parts of the system.