Sun Java System Access Manager Policy Agent 2.2 Guide for Apache Tomcat 5.5 Servlet/JSP Container

Enabling Web-Tier Declarative Security in J2EE Agents

Certain applications might require the use of web-tier declarative security that enforces role-based access control over web resources such as Servlets, JSPs, HTML files and any other resource that can be represented as a URI. This type of security is enforced by adding security-constraint elements to the deployed application’s web.xml deployment descriptor.

Typically security-constraint elements are tied with auth-constraint elements that identify the role membership that will be enforced when a request for a protected resource is made by the client browser. The following example illustrates this idea:

     <web-resource-name>Report Servlet</web-resource-name>


This fragment of deployment descriptor can be used to ensure that access to the report generation servlet is allowed only to those users who are members of the role called Manager.

In order for such a construct to work, you must make the necessary modifications in the J2EE agent configuration file to ensure it can identify and handle such requests.

ProcedureTo Enable J2EE Agents to Handle Security Constraint Settings

  1. Ensure that a login-config element is specified for the web application that is being protected and that the login-config element has the auth-method set to FORM.

    The supporting form-login-config element is also required.

  2. The form-login-page element of form-login-config should be added as one of the values for the following property in the J2EE agent configuration file:


    As an example, consider the following login-config element of a protected application:


    Notice how the form-login-page is specified for the supporting form-login-config element. This value must be set for the following property in the J2EE agent configuration file as shown:

    com.sun.identity.agents.config.login.form[0] = /Portal/jsp/login.jsp

    Notice that the value of the form-login-page as specified in the deployment descriptor is not the same as what is specified in the J2EE agent configuration file. The difference being that when you enter this value in the configuration file, you must prefix it with the context path for the application on which this form-login-page is going to be used. In this particular example, the context path of the application is “/Portal.”

    Similarly, if you have more than one application deployed that require web-tier declarative security, you must add their respective form-login-pages to the J2EE agent configuration file. For example, other entries could be:

    com.sun.identity.agents.config.login.error.uri[1] = /BankApp/SignOn

    com.sun.identity.agents.config.login.error.uri[2] = /ERP/LoginServlet

    Please ensure that each such element added to this list has a unique index entry. Having duplicate index entries can result in the loss of data and consequently result in the malfunction of the application.

    Once you have configured the web application’s deployment descriptor to use the form-login mechanism for web-tier declarative security and have added the full URI of the form-login-page for each such application in the J2EE agent configuration file, the web-tier declarative security is enabled for these applications.

    Note –
    • When a protected application is configured for web-tier declarative security handling by the agent, it must be redeployed with a form-login configuration as described in this section. This configuration requires that two application resources be specified in the application’s web.xml deployment descriptor: one for the form-login-page and the other for the form-error-page. Regardless of whether the resource corresponding to the form-login-page exists in the application or not (this depends on how the agent is configured to handle the form-login requests), the resource corresponding to the form-error-page must be present in the application. This resource is directly invoked by the deployment container to indicate authentication failures and, optionally, authorization failures. If the application does not contain a valid form-error-page matching the URI specified in this deployment descriptor, it could result in HTTP 404 errors when the container chooses to display this error page.

    • For applications that do not contain a form-login-page, you can specify any URI as long as that URI does not conflict with any application resource and the matching value has been added to the configuration property com.sun.identity.agents.config.login.form.

    • By default, the agent is configured to intercept all form-login requests and handle them without invoking the actual form-login-page resource as specified in the web.xml of the protected application. Thus, when using a default installation of the agent, the application is not required to have a resource corresponding to the form-login-page element specified in web.xml. This allows for the configuration of web-tier declarative security for applications that were not designed to use the form-login mechanism and instead relied on other login schemes available in J2EE specification. This behavior of the agent can be changed so that it allows the form-login requests to be handled by actual resources that exist within the application by changing the agent configuration properties as applicable. For details on how this can be done, please refer to the section Customizing Agent Response for Form Login.

    • If the agent filter is operating in the URL_POLICY mode, any necessary URL policies to allow access to the form-error-page resource must be created for all users.

    To further customize the behavior of the application when using web-tier declarative security, see Web-Tier Security Details.

Web-Tier Security Details

When the deployment container gets a request for a resource that is protected by the web-tier declarative security-constraint, it must evaluate the credentials of the user against the agent realm to ensure that only authorized requests go through. In order to process such a request, the deployment container requires the user to sign on using the specified form login page as mentioned in the form-login-config element of the web.xml descriptor. Based on the specification of the FORM authentication mechanism, it is required that the user submits a valid user name as j_username and a valid password as j_password to the special URI j_security_check using the HTTP POST method of form submission.

The agent, once configured to support web-tier declarative security for the given application can isolate the request for accessing form-login-page and instead can stream out some data to the client browser. This data contains the user’s login name and temporary encrypted password, which in turn uses Javascript to do automatic form submission as required. This gives the user a seamless single sign-on experience since the user does not have to re-login in order to access the protected resources for a deployed application that uses web-tier declarative security.

By default, the content that the agent sends to the client browser on intercepting a request for the form login page is read from the file called FormLoginContent.txt located in the locale directory of the agent installation. This file contains the following HTML code:

      <title>Security Check</title>
   <body onLoad="document.security_check_form.submit()">
      <form name="security_check_form" action="j_security_check" method="POST">
         <input type="hidden" value="am.filter.j_username" name="j_username">
         <input type="hidden" value="am.filter.j_password" name="j_password">


Before the agent streams out the contents of this file, it replaces all occurrences of the string am.filter.j_username by the appropriate user name. Similarly, all occurrences of the string am.filter.j_password are replaced by a temporary encrypted string that acts as a one-time password for the user.

Customizing Agent Response for Form Login

The J2EE agent configuration file allows you to completely control the content that is sent out to the user when the deployment container requires a form login from the user.

Note –

The ability to customize the agent response form login is not a feature whose purpose is to change the form login page nor is the purpose of this feature to bypass the default Access Manager login page.

Using the J2EE agent configuration file, you can customize the agent response in the following ways:

ProcedureTo Customize the Agent Response to Form Login

  1. Modify the content of the FormLoginContent.txt file to suit your UI requirements as necessary.

    Ensure that regardless of the modifications you make, the final file submits the j_username and j_password to the action j_security_check via HTTP POST method.

  2. (Conditional) You can specify the name of a different file using the property com.sun.identity.agents.config.login.content.file in the J2EE agent configuration file.

    If you specify the file name, you must ensure that it exists within the locale directory of the agent installation.

    If you wish that this file be used from another directory, you can simply specify the full path to this new file.

    Ensure that regardless of the modifications you make, the final file submits the j_username and j_password to the action j_security_check via HTTP POST method.

  3. (Conditional) If you have more than one application and would like to have an application-specific response to the form login requests, instruct the agent to allow the form login request to proceed to the actual form login page.

    This can be done by setting the value of the configuration property as follows:com.sun.identity.agents.config.login.use.internal as false.

    In this situation, you must ensure that the resource that receives this request extracts the am.filter.j_username and am.filter.j_password from the HttpServletRequest as attributes and uses that to ensure that eventually a submit of these values as j_username and j_password is done to the action j_security_check via HTTP POST method.

    The following JSP fragment demonstrates how this can be done:

    <form action="j_security_check" method="POST">
       String user = (String) request.getAttribute("am.filter.j_username");
       String password = (String) request.getAttribute("am.filter.j_password");
          <li>Your username for login is: <b><%=user%></b></li>
          <li>Your password for login is: <b><%=password%></b></li>
       <input type=hidden name="j_username" value="<%=user%>">
       <input type=hidden name="j_password" value="<%=password%>">
       <input type="submit" name="submit" value="CONTINUE">

    This mechanism would therefore allow you to have an application-specific form-login handling mechanism.