Sun Java System Access Manager Policy Agent 2.2 Guide for JBoss Application Server 4.0

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 AMAgent.properties configuration file:

    com.sun.identity.agents.config.login.form

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


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

    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 AMAgent.properties 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 AMAgent.properties 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 AMAgent.properties 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

    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 AMAgent.properties 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 about how this can be done, refer to 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.