With declarative security, you specify all security settings for your application, including authentication requirements, access control, and security roles, using annotations and/or deployment descriptors. In other words, the security for your application is in a form that is external to the application, and relies on the mechanisms provided by the Java EE container for its management.

With programmatic security, your classes, entities, servlets, and page views manage security themselves. In this case, security logic is integrated directly into your application, and is used to handle authentication and authorization, and ensure that data is sent over a secure network protocol when necessary.

For the AffableBean application, we’ll use declarative security by declaring all security information in the web.xml deployment descriptor.

For more information on declarative and programmatic security types, see the Java EE 6 Tutorial: Overview of Web Application Security.

An authentication mechanism is used to determine how a user gains access to restricted content. The Java EE platform supports various authentication mechanisms, such as HTTP basic authentication, form-based authentication, and client authentication. The authentication mechanism behind our login form will be form-based authentication. You’ll learn what form-based authentication is when you begin setting up the login form for the AffableBean administration console below.

See the Java EE 6 Tutorial: Specifying Authentication Mechanisms for further information.

Form-based authentication has the advantage of enabling the developer to design the appearance of the login form so that it better suits the application which it belongs to. Our implementation for the form-based authentication mechanism can be divided into two steps. Begin by creating page views for the required login form and error message. Then add entries to the web.xml deployment descriptor to inform the servlet container that the application requires form-based authentication for access to the resources that comprise the administration console.

In form-based authentication, the process of authentication and authorization is shown in the following four steps:

For more information on form-based authentication, see the Java EE 6 Tutorial: Form-Based Authentication.

The j_security_check keyword represents the destination in the servlet container that handles authentication and authorization. When implementing the HTML login form, you apply it as the value for the form’s action attribute. You also apply the “j_username” and “j_password” keywords, as in the following template:

Perform the following steps.

This step ensures that when these two pages are returned to a client, they will be prepended and appended with the defined header.jspf and footer.jspf fragments, respectively.

You can equally configure the <jsp-property-group> entry from the `web.xml`s visual editor. Click the Pages tab along the top of the editor, and enter the URL patterns into the respective JSP Property Group.

Note that the HTML form is based on the template provided above. Here, you use the “j_security_check” keyword as the value for the form’s action attribute, and the “j_username” and “j_password” keywords as the values for the name attribute of the username and password text fields. The style of the form is implemented by encapsulating the form widgets within a <div> element, then defining a set of rules for the loginBox ID in affablebean.css.

The above content includes a simple message indicating that login has failed, and provides a link that allows the user to return to the login form.

In order to instruct the servlet container that form-based authentication is to be used, you add entries to the web.xml deployment descriptor. This is essentially a three-step process, which can be followed by specifying settings under the three headings in the web.xml file’s Security tab. These are: (1) Login Configuration, (2) Security Roles, and (3) Security Constraints.

This entry informs the servlet container that form-based authentication is used, the realm named file should be checked for user credentials, and specifies the whereabouts of the login and error pages.

Here we’ve specified the name of a security role used with the application. We’ll need to associate this role with the protected resources that define the administration console (under the Security Constraints heading below), and later we’ll create this role on the GlassFish server.

In these previous six steps, you’ve created a security constraint that specifies which resources need to be protected, and identifies the role(s) that are granted access to them. Since the administration console implementation is essentially everything contained within the application’s admin folder, you use a wildcard (*). Although you’ve specified that all HTTP methods should be protected, you could have equally selected just GET and POST, since these are the only two that are handled by the AdminServlet. As previously mentioned, the affableBeanAdmin role that we declared still needs to be created on the GlassFish server.

When you attempt to access the administration console, the login page is now presented.

A user is a unique identity recognized by the server. You define users on the server so that it can be able to determine who should have access to protected resources. You can optionally cluster users together into a group, which can be understood as a set of authenticated users. In order to specify which users and/or groups have access to protected resources, you create roles. As stated in the Java EE 6 Tutorial,

The role that a user or group is assigned to is what specifically allows the server to determine whether protected resources can be accessed. Users and groups can be assigned to multiple roles. As will be demonstrated below, you accomplish this by defining the role in the application, then mapping it to users and groups on the server.

The relationship between users, groups, and roles, and the process in which you establish them in the application and on the server, is presented in the following diagram.

For more information on groups, users, and roles, see Working with Realms, Users, Groups, and Roles in the Java EE 6 Tutorial.

When you define users and groups on the server, you do so by entering details into a security policy domain, otherwise known as a realm. A realm protects user credentials (e.g., user names and passwords) through an authentication scheme. For example, user credentials can be stored in a local text file, or maintained in a certificate database.

The GlassFish server provides three preconfigured realms by default. These are the file, admin-realm, and certificate realms. Briefly, the file realm stores user credentials in a local text file named keyfile. The admin-realm also stores credentials in a local text file, and is reserved for server administrator users. The certificate realm, the server stores user credentials in a certificate database.

When defining users, groups and roles for the AffableBean administration console, we’ll use the server’s preconfigured file realm.

In order to set up users, groups and roles to satisfy the form-based authentication mechanism we’ve created, perform the following three steps corresponding to the diagram above.

In this step, we’ll use the GlassFish Administration Console to create a user named nbuser within the preexisting file security realm. We’ll also assign the new nbuser to a group that we’ll create called affableBeanAdmin.

Here, we are creating a user for the file security realm, which we’ve randomly named nbuser. We have also assigned the new user to a randomly named affableBeanAdmin group. Remember the secret password you set, as you will require it to later log into the AffableBean administration console.

Optionally close the browser window for the GlassFish Administration Console, or leave it open for the time being. You will need to return to the Administration Console in the Map Roles to Users and/or Groups step below.

By "defining roles in the application," you specify which roles have access to EJB session beans, servlets, and/or specific methods that they contain. You can accomplish this declaratively by creating entries in the deployment descriptor, or using annotations. For the AffableBean administration console, we’ve actually already completed this step when we added the affableBeanAdmin role to the security constraint that we created when implementing form-based authentication. However, in more complicated scenarios you may have multiple roles, each with varying degrees of access. In such cases, implementation requires a more fine-grained access control.

The Java EE 6 API includes various security annotations that you can use in place of the XML entries you add to deployment descriptors. The availability of annotations primarily aims to offer ease of development and flexibility when coding. One common method is to use annotations within classes, but override them when necessary using deployment descriptors.

We have so far accomplished the following:

It is no coincidence that the group and role names are the same. While it is not necessary that these names be identical, this makes sense if we are only creating one-to-one matching between roles and groups. In more complicated scenarios, you can map users and groups to multiple roles providing access to different resources. In such cases, you would give unique names to groups and roles.

In order to map the affableBeanAdmin role to the affableBeanAdmin group, you have a choice of performing one of two actions. You can either create a <security-role-mapping> entry in GlassFish' sun-web.xml deployment descriptor. (In the Projects window, sun-web.xml is located within the project’s Configuration Files). This would look as follows:

This action explicitly maps the affableBeanAdmin role to the affableBeanAdmin group. Otherwise, you can enable GlassFish' Default Principal To Role Mapping service so that roles are automatically assigned to groups of the same name.

The following steps demonstrate how to enable the Default Principal To Role Mapping service in the GlassFish Administration Console.

The Java EE 6 Tutorial defines the term principal as, "An entity that can be authenticated by an authentication protocol in a security service that is deployed in an enterprise. A principal is identified by using a principal name and authenticated by using authentication data." See Working with Realms, Users, Groups, and Roles: Some Other Terminology for more information.

At this stage, you have taken the necessary steps to enable you to log into the AffableBean administration console using the nbuser / secret username / password combination that you set earlier.

Using form-based authentication, the server authenticates the client using the username and password credentials sent from the form. Because the nbuser belongs to the affableBeanAdmin group, and that group is associated with the affableBeanAdmin role, access is granted to the administration console.

The AdminServlet handles the /logout URL pattern by invalidating the user session:

Calling invalidate() terminates the user session. As a consequence, the authenticated user is dissociated from the active session and would need to login in again in order to access protected resources.

The browser displays a warning, indicating that the server is presenting you with a self-signed certificate. In Firefox for example, the warning looks as follows.

Click Confirm Security Exception. A secure connection is established on port 8181, and your local development server, GlassFish, is then able to display the following page.

Aside from the HTTPS protocol displayed in the browser’s address bar, Firefox indicates that a secure connection is established with the blue background behind localhost in the address bar. Also, a lock ( ) icon displays in the lower right corner of the browser. You can click the lock icon for secure pages to review certificate details.

The following optional steps demonstrate how you can identify this security support in the GlassFish Administration Console.

The main panel displays the three network listeners enabled by default on the GlassFish server. http-listener-2, which has been configured to listen over port 8181, is the network listener used for secure connections.

For more information on network listeners, see the Oracle GlassFish Server 3.0.1 Administration Guide: About HTTP Network Listeners.

At this stage, you have an understanding of how the GlassFish server supports secure connections out-of-the-box. Naturally, you could set up your own network listener, have it listen on a port other than 8181, enable SSL 3 instead of TLS (or both), or generate and sign your own digital certificates using Java’s `keytool` management utility. You can find instructions on how to accomplish all of these tasks from the following resources: * The Java EE 6 Tutorial, Establishing a Secure Connection Using SSL * Oracle GlassFish Server 3.0.1 Administration Guide, Chapter 11: Administering System Security * Oracle GlassFish Server 3.0.1 Administration Guide, Chapter 16: Administering Internet Connectivity

This example demonstrates how to specify a secure connection using both XML in the web deployment descriptor, as well as Servlet 3.0 annotations directly in a servlet. You begin by creating an <security-constraint> entry in web.xml for the customer checkout process. Then, to create a secure connection for access to the administration console, you specify a TransportGuarantee constraint for the @HttpConstraint annotation in the AdminServlet.

Note: Recall that the /checkout URL pattern is handled by the ControllerServlet`s `doGet method, and forwards the user to the checkout page.

When you choose CONFIDENTIAL as a security constraint, you are instructing the server to encrypt data using TLS/SSL so that it cannot be read while in transit. For more information, see the Java EE 6 Tutorial, Specifying a Secure Connection.

Configuration for the customer checkout process is now complete. To ensure that a secure connection is applied for access to the administration console, simply specify that any requests handled by the AdminServlet are transmitted over a secure channel.

Also, in Firefox, note the lock ( ) icon displayed in the lower right corner of the browser.

The website now automatically switches to a secure channel when presenting the checkout page. You see the HTTPS protocol displayed in the browser’s address bar, and the port is changed to 8181.

Note: You way wonder at this point how it is possible to switch from a secure connection back to a normal, unsecured one. This practice however is not recommended. The Java EE 6 Tutorial explains as follows:

You have now successfully secured the AffableBean application according to the defined customer requirements. You’ve set up a login form for the administration console to authorize or deny access based on user credentials, and you configured the application and server to create a secure connection for access to the administration console, as well as the customer checkout process.

You can compare your work with the completed `AffableBean` project. The completed project includes the security implementation demonstrated in this unit, and also provides a basic implementation for web page error customization, such as when a request for a nonexistent resource is made, and the server returns an HTTP 404 'Not Found' error message.

Send Feedback on This Tutorial