Creating struts2 login page using Tomcat 6 and JNDI realm

Creating login module when using Struts2 and tomcat can be quite cool and interesting assignement, but can also be a quite annoying job if you are not familiar with all that you need to do…

When creating this module, there are several approaches. For example:

- Creating login module using container managed security
- Creating programmatic login module where you define a “database” of usernames, passwords, and roles. This way you define your login logic by yourself as well.
- Using some 3rd party library

This post describes how to configure Tomcat 6 to support container managed security, using JNDI realm.
I’ll use JNDI realm that enables application server to look for user’s information within Active Directory.

Realms are really cool!
They are, in fact, an instruction  for application server on where to look for user names, passwords and roles when a user that tries to login into your application needs to be authenticated or sometimes it’s a “database” of usernames, password and roles itself.
Great thing when using container managed security is that everything is already implemented, and all you have to do is to provide a realm and map several elements in web.xml, regarding  security.

Let’s start from the beginning.
At this moment, my web.xml file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <filter>
        <filter-name>struts2</filter-name>
        <filter-class>org.apache.struts2.dispatcher.FilterDispatcher</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>struts2</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <session-config>
        <session-timeout>
            15
        </session-timeout>
    </session-config>

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

And as for now, I put all my JSPs in the /jsp/ folder.
This is my application structure:

/ - root of  application
/jsp/  - contains JSPs
/css/main.css - contains CSS
/js/jsfile.js  - contains all of my java script code
/images/  - contains a lot of images

My task is to create a login system for this application, and to provide that only logged users , with roles “boss” or “manager” are allowed to se my JSP pages ( located in “/jsp/” folder )

To do that, the first thing we’ll do is to define (add ) roles in our web.xml.
This can be done in some other files as well, but I’ll do it here…
Note: These roles must be equal to those in active directory.

So, let’s add these two roles:

<security-role>
                <role-name>boss</role-name>
        </security-role>
        <security-role>
                <role-name>manager</role-name>
</security-role> 

Next thing we’ll do is to create a security constraint on accessing web pages:

<security-constraint>
                <web-resource-collection>
                        <web-resource-name>Protected area</web-resource-name>
                        <url-pattern>/*</url-pattern>                  
                </web-resource-collection>

                <auth-constraint>
                    <role-name>boss</role-name>
                    <role-name>manager</role-name>
                </auth-constraint>
</security-constraint>

This way, we deny acces to our resources to anyone except to those of  role “boss” or “manager”.

Next thing we need to do is to define the authentication method we will be using.
There are several authentication methods: BASIC, FORM-BASED , DIGEST , SECURE SOCKET LAYER ( SSL) and CLIENT CERTIFICATE AUTHENTICATION.

Which one to use  - depends on what exactly you need.

For us, the most  interesting method is FORM-BASED authentication.
With this method, you create your custom JSP login  form inside your application, with your own look and feel.
There are 3 very important  things to know when working with form-based authentication:

- input field containing user name must be named “j_username”
- input field containing password must be named “j_password”
- action for form containing these two inputs must be “j_security_check”

So, let’s create one!
Here is the example of such page,:

<html>
<head>
<title>Login Page for Examples</title>
<body bgcolor="white">
<form method="POST" action="j_security_check" >
  <table border="0" cellspacing="5">
    <tr>
      <th align="right">Username:</th>
      <td align="left"><input type="text" name="j_username"></td>
    </tr>
    <tr>
      <th align="right">Password:</th>
      <td align="left"><input type="password" name="j_password"></td>
    </tr>
    <tr>
      <td align="right"><input type="submit" value="Log in"></td>
      <td align="left"><input type="reset"></td>
    </tr>
  </table>
</form>
</body>
</html>

Let’s call it “login.jsp”, and place it in the root folder ( /login.jsp )

Now, let’s map it inside web.xml:

<login-config>
                <auth-method>FORM</auth-method>
                <form-login-config>
                        <form-login-page>/login.jsp</form-login-page>

                </form-login-config>
</login-config>

For now, this is good, but it’s not enough.
We also need to define a form-error-page inside a <form-login-config> tag…
Application server will open that page when user enters wrong user name or password.

Here is what I’m going to do:
I’ll define login.jsp page to be form-error-page too, but with result=false in URL.
This way we will know that we need to add some warning message to user that didn’t enter valid username and/or password.
Let’s edit that prevoius <login-config>:

<login-config>
                <auth-method>FORM</auth-method>
                <form-login-config>
                        <form-login-page>/login.jsp</form-login-page>
                        <form-error-page>/login.jsp?result=false</form-error-page>
                </form-login-config>
</login-config>

and let’s edit that login.jsp page, to show error messages when needed:

<html>
<head>
<title>Login Page for Examples</title>
<body bgcolor="white">
                     <%
                         String result = request.getParameter("result");
                         if(result == null)
                            result = "";
                         if (result.equalsIgnoreCase("false")) 

                         {
                    %>
                    <span style="color: red">
                    Wrong user name or password
                    <br>
                    </span>
                    <%       

                         }
                    %>
<form method="POST" action="j_security_check" >
  <table border="0" cellspacing="5">
    <tr>
      <th align="right">Username:</th>
      <td align="left"><input type="text" name="j_username"></td>
    </tr>
    <tr>
      <th align="right">Password:</th>
      <td align="left"><input type="password" name="j_password"></td>
    </tr>
    <tr>
      <td align="right"><input type="submit" value="Log in"></td>
      <td align="left"><input type="reset"></td>
    </tr>
  </table>
</form>
</body>
</html>

So…
We created login.jsp page, we mapped it in the web.xml  and earlier before we made an acces constraint to all of our folders so only logged users can access it.
But now question is: “what if our login page uses some image from /images/ folder in it, or some java script from within /js/ , or css from within /css/ as it  probably would?”

If we leave everything like this, your login form will not be able to read your css and images, and it will look very bad…

What we now need to do is to make some resource  public, so that our login.jsp page could use it…
To do so, we could make some existing folders public ( for example /css/ and /images/ ) ,  or we could copy particular resources ( some images and css that login.jsp needs ) to some new folder and make public only what has to be public ( what we copied ), nothing more…
We’ll do that…
Let’s call this folder “login_resources”
Let’s place it in the root:

/login_resources/

Copy all the resources that you login.jsp uses to this folder.
We will now create one more security constraint that will allow everyone ( login.jsp ) to access it:

<security-constraint>
        <web-resource-collection>
        <web-resource-name>Unprotected area</web-resource-name>
        <url-pattern>/login_resources/*</url-pattern>
        </web-resource-collection>
 </security-constraint>

We intentionaly “forgot” to set <auth-constraint> inside <security-constraint> so that everyone could access this resource.

Now, our login form will be able to read all the resources it needs…

And, at the end, we need to add our JNDI  realm to our context.xml file
You could add this realm to some other files as well, but I like to add it to context.xml.

Here is one example of it:

<Realm 
 className="org.apache.catalina.realm.JNDIRealm"
 debug="99"
 connectionURL="ldap://localhost:389"
 userPattern="uid={0},ou=people,dc=mycompany,dc=com"
 roleBase="ou=groups,dc=mycompany,dc=com"
 roleName="cn"
 roleSearch="(uniqueMember={0})"
/>

Please, visit http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html for more information on creating  realms.
Place this realm inside <context>  </context> tag in context.xml file.

So, let’s sumarize:

Our web.xml now looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <filter>
        <filter-name>struts2</filter-name>
        <filter-class>org.apache.struts2.dispatcher.FilterDispatcher</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>struts2</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

     <session-config>
        <session-timeout>
            15
        </session-timeout>
    </session-config>

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

<security-role>
                <role-name>boss</role-name>
        </security-role>
        <security-role>
                <role-name>manager</role-name>
</security-role> 

<security-constraint>
                <web-resource-collection>
                        <web-resource-name>Protected area</web-resource-name>
                        <url-pattern>/*</url-pattern>                  
                </web-resource-collection>

                <auth-constraint>
                    <role-name>boss</role-name>
                    <role-name>manager</role-name>
                </auth-constraint>
</security-constraint>

<security-constraint>
        <web-resource-collection>
        <web-resource-name>Unprotected area</web-resource-name>
        <url-pattern>/login_resources/*</url-pattern>
        </web-resource-collection>
 </security-constraint>

<login-config>
                <auth-method>FORM</auth-method>
                <form-login-config>
                        <form-login-page>/login.jsp</form-login-page>
                        <form-error-page>/login.jsp?result=false</form-error-page>
                </form-login-config>
</login-config>

Once the user logs in, application server will create a session for him.
You can access it’s user name with

ServletActionContext.getRequest().getUserPrincipal().getName();

or check if he has a sufficient role with

ServletActionContext.getRequest().isUserInRole(“some_role”);


And if you would like to logout, you can use

getRequest().getSession().invalidate();





That’s it for now…
I hope I helped someone and saved him some time...

Using simple theme and custom CSS in Struts2

Simple theme in Struts2 is great when you want to use your own CSS , and control everything by yourself when it comes to GUI.
Probably many of you (us :-) ) tried using Struts2 with your own CSS without setting default theme to SIMPLE and came up with bunch of unfamiliar tags , like

<table class="wwFormTable">

In your HTML…

Well , if you want to use your own CSS and get your application to look like you wanted to, you need to either create your own new theme ( harder ), or just use Simple theme and use your own CSS ( easier ).

In order to switch to simple theme, just copy/paste this line to your struts.properties file:

struts.ui.theme=simple

Visit
http://devtalks.blogspot.com/2009/07/create-struts2-project-in-netbeans.html
if you are using NetBeans , or

http://devtalks.blogspot.com/2009/07/eclipse-galileo-and-struts2.html
if you are using eclipse

on how to create Struts2 project , and struts.properties file

And that’s it! This way your pages will not contain those annoying
<table class="wwFormTable"> tags…


ISSUES

One thing I noticed when using simple theme is that struts tag <s:fielderror> doesn’t seems to “work” as it should…
You cannot just say, for example,

<s:fielderror />
<s:textfield name=”firstName” />

and expect from struts2 to show errors if your validator doesn’t succeed in validating filed “firstName” .
As a matter of fact, struts2 will indeed dispatch to your INPUT result, but it will not show any errors!
Fortunately , There is a solution to this problem: just use

<s:fielderror> <s:param>filed_name</s:param> </s:fielderror>
instead of
<s:fielderror />

in your .jsp pages and your validation will again act as it should…


ALTERING FieldErrors , ActionMessages and ActionErrors

Speaking of fielderrors, I often see people asking how to change the way Struts is showing field errors action messages and action errors…

You do this by extending the theme you are using. When using simple theme, all you need to do is:

- Create subfolders “template” and “simple” inside folder “classes”

- Find actionerror.ftl , actionmessage.ftl and fielerror.ftl ( or just those which you would like to extend ) in struts2-core-2.x.x.jar , inside “template.simple” package. You can find this .JAR inside your “libraries” folder.

- Copy these files to your new template -> simple folder created in earlier step.

If you open one of these files, you’ll see how these messages are generated.
You can change all that just by editing that file.

Lets say you don’t want your application to show fielderrors as <ul> <li> </li> <ul> elements.
You just need to open the fielderror.ftl and change the part that does this:

So, instead of having

like it is in original file, we can just remove <ul> <li> </li> <ul> elements, and change it with, for example, simple <span> </span> element. That will do the trick. ;-)

Or let’s, for example,change the way your Action message is shown in an application.

Let’s say we need a green box with all the action messages shown in it…
Something like this:

To do this, you could just open the actionmessage.ftl file, and change the original

<#if (actionMessages?? && actionMessages?size > 0)>
<ul<#rt/>
<#if parameters.cssClass??>
class="${parameters.cssClass?html}"<#rt/>
<#else>
class="actionMessage"<#rt/>
</#if>
<#if parameters.cssStyle??>
style="${parameters.cssStyle?html}"<#rt/>
</#if>
>
<#list actionMessages as message>
<li><span>${message!}</span></li>
</#list>
</ul>
</#if>

with something like this:

<#if (actionMessages?? && actionMessages?size > 0)>
<div class="mymessage"><br><span<#rt/>
<#if parameters.cssClass??>
class="${parameters.cssClass?html}"<#rt/>
<#else>
class="actionMessage"<#rt/>
</#if>
<#if parameters.cssStyle??>
style="${parameters.cssStyle?html}"<#rt/>
</#if>
>
<#list actionMessages as message>
<span>- ${message!}</span>
</#list>
</span><br><br></div>
</#if>

And for now on, every Action message in your application will look like a green box containing messages.

Here is the css I used:

div.mymessage
{
right: 0;
bottom: 0;
left: 0;
width:300px;
margin: auto;
color: #33CC33;
border-color:#009900;
border-style:solid ;
border-width:1px;
border-collapse: collapse;
font-weight: bold;
text-align: center;
background-color:#DDFFDD;
}

This is just a simple example what you can do with extending a theme...