SSL Configuration in Tomcat

Today, we are going to learn about how to setup SSL on your Tomcat so that you can access your application on HTTPS instead of HTTP and provide a secure interface to your clients. But before going into that, lets understand the basic difference between HTTP & HTTPS.

Introduction to HTTPS

HTTPS (HyperText Transfer Protocol Secure) combines HTTP protocol with SSL (Secure Sockets Layer) or TLS (Transport Layer Security) and offers a secure channel to browse the web so that you can trust the connection to send sensitive information like payment transactions details or your bank account details. The difference between the two clearly shows in the address bar where you can see “https://” instead of “http://”. Also HTTPS uses port 443 as the default port, whereas HTTP uses port 80 as the default port for communication.

Using HTTPS, the two-way communication that occurs between your web browser and the host server is now secure and encrypted. This means that the data being sent is encrypted by one side, transmitted, then decrypted by the other side before processing.

When a web browser initially attempts to contact a web server over a secure connection, it is presented with a “certificate” (set of credentials), as a proof of the site is who what it claims to be. These certificates are signed (digitally verified) by certain authorities like VeriSign and typically purchased by the web server. Remember that you need to buy a certificate for each port on which you want a secure connection. For this blog entry, we will sign our own certificate and make other changes to Tomcat configuration so that it starts accepting connection on port 443 using HTTPS protocol.

But before we begin setting up SSL on Tomcat, its very important to iterate that this is valid only if you are using Tomcat as a stand-alone web server, the other possibility being Microsoft IIS or Apache Server serving as the main interface to the outside world and Tomcat is serving as the JSP/Servlet Container at the backend, communicating with one of these servers. In that case, you have to make SSL configuration changes in IIS or Apache, while Tomcat will continue to work normally sending cleartext responses (no encryption at Tomcat level).

Creating a Certificate

Fortunately, Java provides us with a utility (keytool) which can be used to create a self-signed certificate. This is not validated by any authority, hence not suitable for production use. But it can certainly be used for development purposes. So, lets  create a certificate from scratch for our application:

Type in the following command and enter details(credentials) about your organization that users of your site/application would see in the certificate given to them when they use it. The default password for Tomcat is “changeit” (all in lower-case). It would be asked when you type the following command to generate your self signed certificate:

>> keytool –genkey –alias –tomcat –keyalg RSA

Note, you must enter the password (as told above) and then all the credentials as shown below:

After doing this correctly, a .keystore file will be generated in your home folder (in the home folder of the user who did this). This is the certificate your tomcat would use and present to any user who visit the secure site.

Configuring Tomcat

Now, we make changes in Tomcat configuration to reflect this change. Tomcat uses 2 different implementations for SSL: Apache Portable Runtime (APR) implementation and JSSE Connector implementation, provided by default with JRE (Java Runtime). Most of the users (like me) do not have APR installed by default, so following steps are valid for JSSE implementation

We now open server.xml present in $CATALINA_HOME/conf. An example <Connector> element for SSL is included by default in most server.xml that comes with Tomcat. It looks something like this:

All you have to do is to uncomment this connector and add to it the location of your certificate (.keystore) that we generated and the password we used to generate it. So finally the entry for the connector looks like:

Also, make sure that the Non-SSL Connector (the default one) which accepts connection on 8080, should have a redirectPort attribute set to 8443 or to the port that you specified for SSL Connection in the connector above. The entry looks like:

That’s all you need to do to make sure that Tomcat starts accepting secure connections on 8443 and redirects users who attempt to access a secure page with http to https. For more details regarding each attribute of the connector, you can refer Java HTTP Connector configuration reference.

Go ahead, try it out and feel the magic that Tomcat provides you. :-) Please post any bugs, queries and corrections as comments.

Tomcat – Container Managed Security

If you are a web developer, then I will not think twice before saying that you must have used Tomcat knowingly or unknowingly for deploying your web applications.

For me, Tomcat is a pretty basic web server, which mainly serves as a JSP/Servlet Container. Today, we explore some basic security features that are provided by the container itself. There are different ways in which this authentication can be provided. In this blog entry, we will try to understand and implement Basic & Form-based Authentication using MemoryRealm.

What’s a Realm?

According to the Tomcat specification, a Realm is a "database" of usernames and passwords that identify valid users of a web application (or set of web applications), plus an enumeration of the list of roles associated with each valid user. Obviously, there are many ways to specify the valid username-password combinations and the associated roles. We will use something known as MemoryRealm, which uses a file: tomcat-users.xml to specify this database.

Steps to Enable Authentication

1. Change the configuration file (server.xml) of the Tomcat Server to specify the realm that you will use
2. Change the tomcat-users.xml file to list the valid username-passwords and the associated roles
3. Change the deployment descriptor (web.xml) for your web application to reflect security constraints needed by the application.

Step1: Change server.xml of Tomcat

The default server.xml has the UserDatabaseRealm enabled as shown below:

 

Note: This can change depending on the versions of the Tomcat, but for Tomcat 5.5 and Tomcat 6, it is the default one. We change it to use MemoryRealm by commenting the previous line and adding the following declaration as shown below:

Step2: Change tomcat-users.xml of Tomcat

The default tomcat-users.xml file, which is present at $CATALINA_HOME/conf/tomcat-users.xml  where $CATALINA_HOME is the directory in which your Tomcat server is installed, looks like:

To this, add your own role and associate with it, some valid combination of username and password as done below:

Step3: Change web.xml of your web application

So far, we have made changes in the Tomcat server itself, its time we must modify our application to reflect the security constraints that we want. To do so, we add the following to our web.xml file:

a) Security Constraints as per the need

Here, We specify that in order to access any URL in our application which comes after http://{context_App}/jsp/…  should be password-protected. Also, we associate a role with it, so users associated with that role can only access these URLs now.

b) Declaring the Security Role

c) Specifying the Type of Authentication

We tell Tomcat that we want to use BASIC authentication for our web application and the realm that we will use will use your tomcat-users.xml file. 

That’s it. All you need to do now, is to restart Tomcat and check whether this works or not. Obviously you need to create a basic web application to deploy onto the Tomcat , for which you have specified the security constraints. You can download my test web application here. (Provide a Link)…………………

This was pretty basic stuff, but it has several limitations. For one, this is not suitable for production environments and we must use FORM-based authentication instead of BASIC. Secondly, it is not a good practice to use clear-text passwords in tomcat-users.xml file. We can save the encrypted password (encrypted by any algorithm like SHA, MD2, MD5 etc) supported by the realm.

Changes to overcome limitations

1. Use Digested Passwords

Obviously, storing passwords in clear-text readable format in tomcat-users.xml cannot be considered safe or practical. In a production environment, it is essential to use some encryption to provide security. Tomcat provides us with several digest algorithms (SHA, MD2, MD5 etc) supported by MessageDigest class. To enable it, change the realm declaration in server.xml of Tomcat to the following:

Also, change the password you specified in tomcat-users.xml to the encrypted version of the original password, by using RealmBase class. You can find this class in catalina.jar in $CATALINA_HOME/lib directory. Use it as follows: RealmBase.digest(“password”, “MD5”, null) . Now, restart your Tomcat and test your authentication.

2. Use FORM-based Authentication

Since using BASIC authentication, you have very little control over the authentication/login method used by Tomcat and it is not considered practical for production environment. So we demonstrate another way: FORM-based authentication. The whole setup remains same, only you can provide your own custom login and error pages (with your company logo and whatever you want) instead of just popping up a window (as done by Tomcat in BASIC mode)

We will change the <login-config> element declared in your application’s web.xml as follows:

We will now add login.jsp and error.jsp to our application. login.jsp is used to authenticate the user: hence it would provide a form while error.jsp is the page to which user is redirected in case of an error: invalid username-password.

login.jsp will have at least a login field with name as “j_username” and password field with name as “j_password”. This must be same so that tomcat can identify the password and login fields in the form. Also the action of the form must be “j_security_check”. You can find the link to download the whole project at the end. My authentication page looks like this, which I believe is much better and safer than basic mode.

Still, we have one limitation:

Any changes made to the file: tomcat-users.xml will be reflected only when the Tomcat server is restarted. So, if you add a new username-password combination to it, you must restart Tomcat in order to have its effect. We can also overcome this limitation by specifying the username-password and roles in a database table and using a JDBCRealm instead of MemoryRealm. You can download entire project from here.

Flex Remoting with Java Part 2

In the last blog entry, I wrote about setting up a simple Flex Application and integrating it with Java so as to be able to make Remote Calls to Java Methods and display the result in Flex.

Today, we are going to make those efforts valuable by seeing how a user-defined object can be passed between Java & Flex. We will create a Employee List in Java and show it in a DataGrid in Flex. As Simple as that. To start with, you must have all the environment setup as explained here.

RPC with User Defined Objects

To be able to do so, we must create classes in both ActionScript and Java and bind them together as shown below:

Employee.java

Employee.as

The Java and the ActionScript file have the same attributes and they map to each other using Flex Metadata: RemoteClass(alias=””) which maps the java object returned from server to ActionScript object which can be displayed. This metadata tag used in ActionScript Class (Employee.as) specifies the fully qualified name of the corresponding Java Class. We now create a Utility class for getting Employee details:

EmployeeUtils.java

Here, we have hard-coded the Employees Data, but it is as easy to get these employees from a database by firing a query. We now make a RPC call from Flex to get this list so that we can display it in a DataGrid.

We create a RemoteObject in Flex and specify a destination “employee” which is present in a remoting-config.xml to specify the Java Class file to look for methods called (getAllEmployees) using this RemoteObject. Part of flex-config.xml which specifies this looks like:

 

We specify the result and fault handlers with the remote object, which are called when result or fault occurs. In the result handler function, we save the result in a ArrayCollection, which we bind with our DataGrid as shown below:

We set the dataProvider property of our DataGrid component to __employeeList, which is a bindable ArrayCollection which contains the result data. The advantage of making the ArrayCollection as bindable is that any changes made to this ArrayCllection (due to any event) is reflected in our DataGrid automatically.

When we run this example, we get a DataGrid as shown below:

Again this is not a best-way to code your flex application. The intent was to show how user-defined objects can be passed between Java & Flex. In practice and in large scale application, we would use tested frameworks like Cairngorm or PureMVC.

Wishing you very Happy Coding with Flex :-)

Flex Remoting with Java

Flex is one of those technologies that has taken the RIA (rich internet applications) world by storm and surprise. It has never been so easy to create interactive user interfaces before. Flex offers various ways to interact with languages like Java, PHP and Coldfusion:

• RPC Services which enables Flex applications to make asynchronous calls to remote services following a call and response model.
• Data Management Services provides data synchronization and real-time updates, on-demand data paging and many other data integration features to Flex Applications.
• Message Services that provides Flex with a publish-subscribe mechanism to create rich and collaborative real-time applications

All these capabilities are provided as a part of Adobe’s LiveCycle Data Services Pack. But unlike the Flex SDK, the entire LiveCycle Data Services Pack is not free and open Source. Rather, Adobe has open sourced a part of it, basically the RPC services and Message Services known as BlazeDS.

Using the RPC Services, one can

• Call and invoke remote Java Methods directly and bind the result to a Flex component. (using RemoteObject Component ). It follows a request and response model making asynchronous calls to the backend.
• Invoke an already deployed SOAP-based Web Service over HTTP using WebService Component.
• Send and receive data using HTTP GET and POST using HTTPService Component.

Today, we are going to make use of RemoteObject to invoke Java Methods and show the result in Flex. For this purpose, we are going to use

1. Flex 3 SDK
2. Flex Builder 3
3. BlazeDS for making asynchronous calls to Java

Open Flex Builder. Create a new Java Project. Name it ‘testFlexRPC’.

Project Structure

Structure of a typical flex application that we will use looks like:

‘web’ is our output folder. We will deploy it as a WAR file later on. The output folder contains the WEB-INF folder, in which we will add the deployment descriptor ‘web.xml’ file and other folders such as classes. (the path web/WEB-INF/classes should be your default output folder in Java Build Path, which will store the class files). Make two other folders, flex and lib which will contain the flex files for remoting purposes (remoting-config.xml and services-config.xml) and the libraries needed for Flex Remoting (typically the BlazeDS JARs for messaging).

Deployment Descriptor

Lets add the deployment descriptor (web.xml) to the project. It will typically contain an entry for the MessageBroker Servlet (which is used by the flex framework for RPC communication) and specify the location of services-config.xml, which is used to define the kind of RPC services to be used.

web.xml

Services-Config.xml

Line 14 of web.xml specifies the location of services-config.xml in your project. It is the top-level configuration file that contains security-constraint definitions, channel definitions, logging settings that each of the services can use. Create an empty XML file on that location and add the following to it:

Firstly, it defines the kind of RPC services that we will use in this project. It includes another file: remoting-config.xml which will contain the destinations for RPC Calls.

Next, it defines the channels that are actually used by the flex application to transfer data between client and server. It defines two channels: HTTP channel and AMF Channel (AMF stands for Actionscript Messaging Format). These channels are used in remoting-config.xml as we will see in a moment. These channels are a key element of the destinations that are specified and perform all work needed for the asynchronous communication that is required by the application.

The other part of this file: services-config.xml specifies the logging information and looks like:

Remoting-Config.xml

Lets create another XML file, which will list the destinations that we will make use of, for making asynchronous calls to remote Java methods from Flex.

It specifies the channels (HTTP and AMF that we configured in services-config.xml) that these destinations will use to communicate between client and server. This file also lists the adapter (server-side code) that interacts directly with the object or the service.

Next, it defines the destinations that can be used with <mx:RemoteObject>, <mx:WebService> and <mx:WebService> tags in MXML or its equivalent in Actionscript code.

Here, we define a destination (sayHelloToMe) and bind it with the Java Class SayHello.java present in java.myPackage package.

Now, add the following libraries in your project. You can find them in the BlazeDS zipped file that you downloaded at the start.

Now, right click on the project node and go to Flex Project Nature –> Add Flex Project Nature

A popup would appear asking for Flex Project Settings. Choose the default settings: application server type to J2EE and check the box Using remote object access service. Click Next to configure J2EE server for your application

Enter your application deployment settings like your application server’s port number and the context root that you want for this application. Also specify the output folder, where you want the resulting SWF file (and the html wrapper) to be stored. Click Finish to successfully add the Flex Project Nature to your Java application.

It will automatically create a default MXML application file with the same name as the project to the source folder (configurable in Flex Build Path). We move this mxml file to flex folder that we created under src/flex folder (not necessarily needed, but we have a thing for being organized :-) ). Though for this, we also have to change the Flex Build Path. So, right click on the project node, go to properties. Click on Flex Build Path tab and set the following settings:

Click Add Folder and add “src”. Also change the main source folder from “src” to “src/flex”. Click Ok to update the compiler settings. You still need to set the testFlexRPC.mxml as the default mxml application. so, right click Project node, go to Properties, Go to tab Flex Application. click on Flex folder and click add. Now add the testFlexRPC.mxml file and click set on default button to make it default application file.

If you check out, the project must be giving you a compile-time error since we have not created any html file (wrapper) to embed the SWF file which contains the compiled flex application. So right click on the error and click ‘Re-create HTML Templates’ to create the default html wrapper which can be used as is.

Now, your application is ready to be deployed (technically), but since we have not added any display element and made use of Flex Remoting (the long and tiring process that we have done so far), so there is no use of deploying it currently.

Now, comes the easy part. Click the src/java and add a new package: mypackage and create a new Java File: SayHello.java ( as specified in remoting-config.xml ) It looks like the following:

SayHello.java

Now, this is a very simple example (because I think you already have had enough !!) and this is not something for which you have to go to Java from Flex. But it is enough to show you how things can be done and results calculated in Java can be passed to Flex (whether its a primitive or any other object: String or any user-defined object as well)

Now, we will call this java Method in Flex. Add the following code in testFlexRPC.mxml file, already created.

testFlexRPC.mxml

Again, this is not a best-practice way to code, but since I’m running out of space and you are running out of patience, so I’m doing things quickly :-)

Finally, we are ready for deployment and I’m using Tomcat to deploy my web application. To accomplish this, we create the following XML file specifying the context.

flexRPCJava.xml

To learn more on how to deploy Web Applications on Tomcat, please read my previous blog entry about the same.

Now, all you need to do is to start Tomcat and check whether your application is working correctly or not by checking the HTML wrapper that Flex Builder created for you:

I hope you are with me till now and would be happy to know that this (perhaps the longest blog I ever wrote) has finished and you have successfully learned how to use Flex with Java.

I could have taught the same in a very concise manner using the BlazeDS Turnkey Server and pre-configured examples, but that would have defeated the purpose of structuring and creating a web-application from scratch. Hope you had fun. Cheers !!

Any suggestions, corrections or Comments are welcome and wanted :-)