In this part of the security trail, we start with Basic Authentication and fileRealm. For some basic background information, please refer to the former part.

To secure the TinyCalutor, we need to add a security constraint to web.xml. Open this file with your editor. Using NetBeans, choose on your project tree Web Pages, WEB-INF, web.xml. Although in case of this file, the source view is the predefined view, choose Security first to get an overview.

On top you may notice the different login configurations. As stated before, I’ll describe Basic and Form during this tutorial. From the users point of view, Digest is almost the same as Basic. Under the hood, a digest (hash value) is derived from the password. Thus, no clear text is send to the server. But this is not really a security feature. Clint Certificate is based on SSL and a server certificate in conjunction with a client certificate.

Choose Basic and enter “file” as realm name. This info is not checked by NetBeans, thus ensure to key in an existing realm name. Refer to your application server to figure out, which values are valid. Since I’m using GlassFish for this tutorial, “file” is a valid realm name. I file realm (aka domain, zone, ..) is available for most app servers.

Next, go to Security Roles and add the role name “student”. You may define as many roles as you like. This might be useful for applications where you need to distinguish between different access levels like admin, user, manager, service and so on. For my simple calculator, there is no need for different roles (frankly, there is no need for any restriction, but I want to demonstrate is).

Last step to configure web.xml is a security constraint. Click onto Add Security Constraint to add one. The display name is optional and for your convenience. It is very useful, once you have to deal with lots of different constraints.

Now, add a Web Resource Collection. Give it a name and provide an URL Pattern.“*.xhtml” applies to all pages of the calculator. We want to restrict the calculator to members of a given role. Thus, check Enable Authentication Constraint and edit Role Name. Enter “student”, the role we defined above. This establish a requirement for authorization, whilst Enable User Data Constraint forces a requirement for transport layer.

No NetBeans available? Or do you prefer to edit an xml file directly? Let’s take a look into it. Using NetBeans, choose the Source tab. Your web.xml should look similar to that one:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" 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_3_0.xsd">
       <context-param>
               <param-name>javax.faces.PROJECT_STAGE</param-name>
               <param-value>Development</param-value>
       </context-param>
       <servlet>
               <servlet-name>Faces Servlet</servlet-name>
               <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
               <load-on-startup>1</load-on-startup>
       </servlet>
       <servlet-mapping>
               <servlet-name>Faces Servlet</servlet-name>
               <url-pattern>*.xhtml</url-pattern>
       </servlet-mapping>
       <session-config>
               <session-timeout>
                       30
               </session-timeout>
       </session-config>
       <welcome-file-list>
               <welcome-file>index.xhtml</welcome-file>
       </welcome-file-list>
       <security-constraint>
               <display-name>All web pages</display-name>
               <web-resource-collection>
                       <web-resource-name>All web pages</web-resource-name>
                       <description/>
                       <url-pattern>*.xhtml</url-pattern>
               </web-resource-collection>
               <auth-constraint>
                       <description/>
                       <role-name>student</role-name>
               </auth-constraint>
       </security-constraint>
       <login-config>
               <auth-method>BASIC</auth-method>
               <realm-name>file</realm-name>
       </login-config>
       <security-role>
               <description/>
               <role-name>student</role-name>
       </security-role>
</web-app>

Locate the tags security-constraint, login-config, security-role and their children. This is the result of the configuration I explained above. Thus, the intent of these tags should be clear. And these tags are the heart from the part of container based security which is defined in this file. If you once know these tags, it might be faster to edit the xml file directly. If you want to apply more than one constraint, simply add a sibling. Within one constraint, it is allowed to add further web resource collections. And you may restrict it to one or more dedicated http methods.

  <web-resource-collection>
       <web-resource-name>All web pages</web-resource-name>
       <description/>
       <url-pattern>*.xhtml</url-pattern>
       <http-method>PUT</http-method>
       <http-method>POST</http-method>
</web-resource-collection>

<login-config> is the place where you need to apply changes, if you choose a different authentication, such as. Form, or a different realm. Changing the method usually does not affect the security constraint(s) or role(s). Thus, I do not explain this again, when we move to a different realm or authentication method.

Now, what happens if you start the application? Your browser will display a small login dialog to query username and password.

Enter some credentials, press enter (or click onto ok) – and this dialog will be re-displayed until (depending on your browser) you enter a valid username password combination. Yet, we have no user defined. Thus, the only choice is to cancel. You’ll get a 401 – Unauthorized page displayed by the browser. The application is secured now.

Want to let in some user? Ok, let’s define her.

Open the GlassFish admin console. Ensure GlassFish is running (will be started with your app). Using NetBeans, open the Services view (Ctrl+5), Choose Servers and open the context menu of your GlassFish. Choose View Domain Admin Console. Alternatively go to http://localhost:4848/ in your browser.

In the navigation pane choose Configurations, server-config, Security, Realms, file.

GlassFish displays the Edit Realm page. Click onto Manage Users and then New.

Now, enter some credentials as shown in the following screenshot. Confirm by clicking Ok.

As the Realm name suggest, your user information will be stored in a file. This is located in your domain/config folder and named keyfile.

You may open it with a text editor. The content should be similar to this:

guest;{SSHA256}c6/mlRhM7djv01PY+eA1tF6plcQ/3IROXeCwO06ZTLtkF+dqmg2Erw==;student

Each line is build up by three coloums: Username, password and group(s). To protect the password, it is stored as an encrypted hash value.

If you start the application, you still can’t log in. Do you remember web.xml dealing with roles whilst GlassFish stores groups? These are two slightly different entities. What’s missing is a mapping from group (or principal) to a role. This is a task specific to GlassFish.

For this mapping, you need a glassfish-web.xml (or sun-web.xml) file. You must create one, if it does not exists yet. Using NetBeans, simply choose New, Other, GlassFish, GlassFish Descriptor to create this file. Or create it manual in the WEB-INF folder.

In the Security tab, enter information in as shown below:

Or, in XML tab you may add these lines:

   <security-role-mapping>
       <role-name>student</role-name>
       <group-name>student</group-name>
       <group-name>user</group-name>
   </security-role-mapping>

This configuration maps both groups student and user to the role student. You may also map a user (principal) directly to a role:

   <security-role-mapping>
       <role-name>student</role-name>
       <group-name>student</group-name>
       <group-name>user</group-name>
       <principal-name>muellermi</principal-name>
   </security-role-mapping>

If there is no need for this flexible mapping, it is possible to switch it off. In GlassFish, Security check Default Principal To Role Mapping. Now, a group is directly mapped to a role (group name = role name). No need for a dedicated mapping. Beware, this affects only application deployed after changing this setting!

Now, if you start the application, login to the TinyCalculator is possible as desired.

To web development content.