Protecting Java EE Applications With OpenSSO Policy Agents, Part 1: Basic Steps

Print-friendly Version

The OpenSSO server (OpenSSO for short), usually logically centralized, offers an identity repository and numerous services, such as those for authentication, management of user sessions, administration of policies, auditing, and logging. Along with OpenSSO Policy Agents for the Java EE platform, you can protect Web applications from unauthorized access through OpenSSO's security services. Several other options for protection also exist, such as by means of the client SDK or identity services that take advantage of the Simple Object Access Protocol (SOAP) and Representational State Transfer (REST) interfaces. However, those options require extra code for enabling the security services and are thus more complex and time-consuming to implement.

By installing a Policy Agent at the application-server instance on which your applications are deployed and then configuring the Policy Agent, you can enforce authentication, single sign-on (SSO), and authorization. During installation, classes that can secure the deployed applications are added to your application-server instance. Subsequently, you can also enable Web-service security, personalize applications for users, and map to the Java EE security mechanisms.

This article, Part 1 of a series, shows you how to protect Web applications with Policy Agents and OpenSSO through the example of a simple application. You'll learn how to accomplish these two tasks:

1. Create user accounts for OpenSSO.
   
   
2. Mandate that users log in and be authenticated before being granted access to the application.

Part 2 describes how to protect only certain pages of your application and how to allow authenticated users to access other applications in your enterprise without having to log in again—in other words, how to implement SSO.

This article assumes that you are familiar with the basics of OpenSSO and Policy Agents and that you have installed them on your system. For the installation process, see this tutorial.

If you install OpenSSO and a Policy Agent on different containers, the Policy Agent can intercept requests to the application and conduct security checks. When a user attempts to access a protected resource or page in the application, the OpenSSO login page is displayed. After authentication, the user is granted access.

Figure 1 illustrates the architecture.

Figure 1: How a Policy Agent and OpenSSO Protect Access of Web Applications

Here's the process:

1. The browser sends a request for the protected resource to the deployment container (such as a Web server or an application server) protected by the Policy Agent.
   
   
2. The Policy Agent intercepts the request and checks whether a session token is embedded in a cookie. If the answer is yes, the Policy Agent validates the token for SSO. Otherwise, the Policy Agent directs the user to the OpenSSO login page to log in with the credentials, such as a user name and password, which the Policy Agents then verifies against the data in the identity repository.
   
   
3. If authentication succeeds, the Policy Agent establishes a session token and proceeds to step 4. In addition, the Policy Agent might create a cookie for the user's browser.
   
   If authentication fails, the Policy Agent denies the user access.
   
   
4. The Policy Agent sends an authorization request to the OpenSSO policy service for user access to the protected resource.
   
   
5. OpenSSO responds with the policy decision.
   
   
6. The Policy Agent interprets the decision and allows or denies access to the requested resource.

Despite the many interactions, in practice, the Policy Agent might cache information and does not require an interaction with the OpenSSO each time.

As an example, see this simple application, which contains two JavaServer Pages (JSP) pages.

• Welcome page (index.jsp) — Links to the protect_me.jsp page.
  
  
• Protected page (protect_me.jsp) — Shows the name of the application's context root.

Here are the assumptions and an explanation of the related URLs and nomenclature:

• You have deployed OpenSSO on GlassFish application server.
  
  Subsequently, the OpenSSO Administration Console is at http://my.test.domain.com:8080/opensso. The Policy Agent and the protected application run in another GlassFish domain, called domain2, at http://my.test.domain.com:6948/mini-agentsample.
  
  
• You have created a Policy Agent profile while installing the Policy Agent.
  
  On the sample application server domain in which you install the Policy Agent and in which your applications will be deployed, you must create a Policy Agent profile. This profile, which you can edit in the OpenSSO Administration Console, contains the configurations for your Policy Agent, such as its security mode, the server URL of the Policy Agent-protected applications, and the security settings. In our example, the profile is named myagentprofile; feel free to name it whatever you desire.

Follow the steps in this section to protect your application.

Step 1: Update the web.xml File of Your Application
By referring to the Policy Agent filter in the web.xml file of your application, you enable the Policy Agent code to intercept Web requests and perform security checks before allowing the application to process those requests.

Note: Since the web.xml file included in the sample application already contains the following filter segment, you need not perform this step.

But here is the code segment to add to other applications' web.xml file:

<filter>
<filter-name>Agent</filter-name>
<filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class>
</filter>
<filter-mapping>
<filter-name>Agent</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>INCLUDE</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>ERROR</dispatcher>
</filter-mapping>

Step 2: Build and Deploy the Application
The sample application has already been built, with the mini-agentsample.war file ready for download. You need only deploy it on domain2, the GlassFish domain on which you installed the Policy Agent.

Deploy the application either on the GlassFish Administration Console or by placing a copy of the mini-agentsample.war file in the autodeploy directory of your domain, for example, C:\workspace\sample\db-stuff\my-gf-server\glassfish\domains\domain2\autodeploy.

Step 3: Create a User Account
Next, create a user account. Afterwards, the related identity attributes, including the defaults (first name, last name, membership information, and such) and those specified by the user, reside in the OpenSSO identity repository. When the user logs in to access a protected resource, OpenSSO compares the credentials with the values stored in the identity repository.

First, create a user account with Bob as the user ID:

1. Log in to the OpenSSO Administration Console at http://my.test.domain.com:8080/opensso as amadmin.
   
   
2. Click the Access Control tab and then Top Level Realm. Click the Subjects tab. See Figure 2.
   
   
   

   Figure 2: Subjects Screen Under Top-Level Realm
    
   
3. Click the New button under User to go to the New User screen. Fill in the fields, with secret as the password, as shown in Figure 3. Click OK.
   
   
   

   Figure 3: New User Screen
    
   OpenSSO then lists Bob Smith as an account under Users. See Figure 4.
   
   
   

   Figure 4: Bob Smith as a User Account
    
   

Tip: To verify that a user's attributes are stored in the OpenSSO identity repository, click the Subjects tab and then click Bob to view the user profile. Alternatively, log out of the Administration Console, delete the cookies in the browser, and log in with Bob as the user ID and secret as the password.

Step 4: Configure the Agent Filter Mode
You can configure the Policy Agent filter and specify different modes for different types of security. Altogether, there are five modes: ALL, J2EE_POLICY, URL_POLICY, SSO_ONLY, and NONE. See their descriptions. For example, you can assign a mode to an application and another mode as a default for any protected applications that do not have an explicit mode.

The sample application does not rely on any of the Java EE security mechanisms for protection. Instead, we protect it with OpenSSO. Note that the application name and its context root are, by default, mini-agentsample.

Do the following:

1. In the OpenSSO Administration Console, navigate to the configuration screen for the Policy Agent named myagentprofile. By default, OpenSSO displays the Global screen for the agent, as shown in Figure 5.
   
   
   

   Figure 5: Edit myagentprofile Screen
    
   
2. Click the link General above the Profile section.
   
   The General subsection is displayed, showing the configuration screen for the agent filter mode. See Figure 6.
   
   
   

   Figure 6: Configuration Screen for Agent Filter Mode
    
   By default, the value of the agent filter mode is ALL, which means that the applications are protected by all the filter modes. For the sample application, we specify the SSO_ONLY mode instead.
   
   Note: This mode applies to all applications that are deployed on the same domain as the sample application. Optionally, we can define a filter mode to apply to only one application by specifying the application context name along with the filter mode, for example, [/myapp]=SSO_ONLY. For simplicity, we retain the SSO_ONLY mode.
   
   When SSO_ONLY mode is in effect and after a user has been successfully authenticated, the Policy Agent places a cookie in the browser to represent the OpenSSO token for that user. The user can then access the application's other resources and other deployed, Policy Agent-protected applications without having to log in again.
   
   
3. Click ALL under Current Values and then click the Remove button.
   
   
4. Type SSO_ONLY in the Corresponding Map Value field and leave the Map Key field blank, as shown in Figure 7. Click Add.
   
   
   

   Figure 7: Application of SSO_ONLY as the Agent Filter Mode
    
   OpenSSO then shows SSO_ONLY as the agent filter mode. See Figure 8.
   
   
   

   Figure 8: SSO_ONLY as the Agent Filter Mode
    
   
5. Important: Click the Save button at the top of the Edit myagentprofile screen.
   
   
6. Because the mode change is not hot-swappable, restart the Policy Agent container for the mode change to take effect.
   
   
   1. On the command line, go to the application server domain (domain2 in this example).
      
      
   2. Stop and then restart the server, For example, type:
      
      glassfish\bin>asadmin stop-domain domaintest2
glassfish\bin>asadmin start-domain domaintest2

Step 5: Create a Policy and Rules for the Application
Since you have specified SSO_ONLY, your application, by default, allows only authenticated users to access resources—the behavior that applies to our example. In other cases, you can create a more refined policy, such as one that restricts access to a certain group of users or resources. For simplicity, this example retains the default behavior of SSO_ONLY.

Step 6: Test the Implementation
Finally, verify that authentication and SSO work properly:

1. Log out of the OpenSSO Administration Console and delete all the cookies in your browser to avoid a clash of the two cookies (one for OpenSSO and one for the Policy Agent).
   
   
2. Go to the application at http://my.test.domain.com:6948/mini-agentsample/index.jsp.
   
   The OpenSSO login page is displayed. Note that the URL is now an OpenSSO URL: http://my.test.domain.com:8080/opensso/UI/Login?goto=http%3A%2F%2Fmy.test.domain.com%3A6948%2Fmini-agentsample%2Findex.jsp. The goto parameter appended to the URL specifies the sample application's address to return to after successful login.
   
   
3. Type Bob as the user name and secret as the password. Click Log in. See Figure 9.
   
   
   

   Figure 9: OpenSSO Login Page
    
   The welcome page of the application is displayed. See Figure 10.
   
   
   

   Figure 10: Welcome Page of Sample Application
    
   
4. Click "Access the second protected page."
   
   The protected page is displayed, showing the name of the application's context root, /mini-agentsample. See Figure 11.
   
   
   

   Figure 11: Protected Page in Sample Application
    
   

You can easily protect Web applications with Policy Agents. In this article, you've learned how to do so by mandating user authentication before access to any pages is allowed and by enabling SSO.

Stay tuned for Part 2, which will show you how to configure OpenSSO so that certain resources of your application, for example, the welcome page, are publicly accessible. You'll also learn how to enable authenticated users to access your enterprise's other applications without having to log in again.

• OpenSSO
  • Main page
  • Resource Center
  • Support: Sun OpenSSO Express
  
  
• Policy Agent download (with a deployable sample Java EE Web application)
  
  
• GlassFish application server
  
  
• Sun developer services
  • Support
  • Training and certification