test

Sun Java System Access Manager Policy Agent 2.2 Guide for Oracle Application Server 10g

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:


<security-constraint>
   <web-resource-collection>
     <web-resource-name>Report Servlet</web-resource-name>
     <url-pattern>/ReportGenServlet</url-pattern>
   </web-resource-collection>
   <auth-constraint>
     <role-name>MANAGER</role-name>
   </auth-constraint>
</security-constraint>

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

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

    The following element serves as an example of a login-config element for a protected application on Oracle Application Server 10g:


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

  3. Edit the oracle10g_login.jsp file as required.

    1. Copy the oracle10g_login.jsp file to the jsp directory of the application's WAR file.

      The following is the full path to the oracle10g_login.jsp file:

      PolicyAgent-base/sampleapp/docroot/jsp/oracle10g_login.jsp

    2. Edit the newly copied oracle10g_login.jsp file as shown.

      Caution – Caution –

      When editing the oracle10g_login.jsp file, ensure that you do not modify the following tag:

      <META HTTP-EQUIV="refresh" content="0;url=/Deployment-URL/jsp/oracle10g_login.jsp"/>

      where Deployment-URL represents the deployment URL of the application.

      If this tag is modified, the Java Server Page (JSP) can appear in the end user's browser instead of being directed to the target application.

      The following table demonstrates the string to be edited, agentsample/jsp/oracle10g_login.jsp, and how the string appears after editing. Edit every occurrence of this string:

      Original String 

      Edited String 

      agentsample/jsp/oracle10g_login.jsp

      Deployment-URL/jsp/oracle10g_login.jsp

  4. Add the following information to the application's META-INF/orion-application.xml descriptor file:

    <jazn provider="XML" "location="./jazn-data.xml">
<property name="role.mapping.dynamic" value="true"/>
<property name="custom.loginmodule.provider" value="true" />
</jazn>

  5. (Conditional) If a jazn-data.xml file does not exist in the application's META-INF directory, create one as demonstrated in the following example:

    <?xml version="1.0" encoding="UTF-8" standalone='yes'?>
<!DOCTYPE jazn-data PUBLIC "JAZN-XML Data" "http://xmlns.oracle.com/ias/dtds/jazn-data.dtd">
<jazn-data>
<!-- JAZN Realm Data -->
<jazn-realm>
<realm>
<name>jazn.com</name>
<users>
</users>
<roles>
</roles>
</realm>
</jazn-realm>

<!-- JAZN Policy Data -->
<jazn-policy>
</jazn-policy>
<!-- Permission Class Data -->
<jazn-permission-classes>
</jazn-permission-classes>
<!-- Principal Class Data -->
<jazn-principal-classes>
</jazn-principal-classes>
<!-- Login Module Data -->
<jazn-loginconfig>
</jazn-loginconfig>
</jazn-data>

  6. Define the proper role-to-principal mapping in the application's orion-application.xml descriptor file as follows:

    <security-role-mapping name="MANAGER_ROLE">
     <group name="id=manager,ou=role,dc=subdomain,dc=domain,dc=com" />
</security-role-mapping>

    Notice that id=manager,ou=role,dc=subdomain,dc=domain,dc=com is an example of a universal ID generated by the agentadmin --getUuid command.

    For information about the agentadmin --getUuid command, see agentadmin --getUuid.

  7. Repackage the application.

    Therefore, using the software tool of your choice, repackage the application as a JAR file.

  8. Redeploy the application using Oracle Application Server 10g Enterprise Manager.

    The redeployment steps differ between Oracle 10g10.1.2 and 10g10.1.3 as indicated by the following alternatives. Perform the set of steps that apply according to the specific Oracle Application Server 10g version, 10g10.1.2 or 10g10.1.3, you are configuring.

    Note –

    The substeps that follow serve as a guideline. As you redeploy the application, you are prompted for information. The substeps that follow present the options that you are required to select or provide to ensure a successful redeployment. For prompts that are not referenced in the substeps that follow, the default option is assumed to be appropriate.

    • Oracle Application Server 10g10.1.2

      1. Take note of the application name and deployment URL (Map to URL).

      2. Select Use JAZN XML User Manager when the following message appears:

        Deploy Application: User Manager

        Therefore, at some point during the deployment process, the preceding message appears.

        At that time, select Use JAZN XML User Manager.

      3. For Default Realm, accept the default, which is blank.

        Therefore, by default no value is associated with Default Realm.

      4. For XML Data, accept the default, which is “./jazn-data.xml.”

      5. Complete the deployment procedure.

      6. Add the necessary XML elements to the jazn-data.xml file.

        Once the deployment procedure is complete, you must add elements to the jazn-data.xml file as described in this substep.

        The following is the location of the jazn-data.xml file:

        DeployContainer-base/j2ee/DeployContainer-instance/config/jazn-data.xml
        DeployContainer-base

        represents the directory within which the Oracle Application Server 10g10.12 instance was installed.

        DeployContainer-instance

        represents the name of the Oracle Application Server 10g instance on which the protected application will be deployed.

        The following configuration elements are appropriate to add:


        <application>
<name>application-name</name>
<login-modules>
<login-module>
<class>com.sun.identity.agents.oracle.v1012.AmOracleLoginModule</class>
<control-flag>required</control-flag>
<options>
<option>
<name>debug</name>
<value>true</value>
</option>
</options>
</login-module>
</login-modules>
</application>

        where application-name represents the name of the application, such as “agentsample.” This is the application name of which you were instructed to take note at the beginning of this task.

    • Oracle Application Server 10g10.1.3

      1. Take note of the application name and deployment URL.

      2. Click Go To Task for the Select Security Provider task when the following message appears:

        Deploy: Deployment Settings:

        Therefore, at some point during the deployment process, the preceding message appears. At that time, click Go To Task for the Select Security Provider task.

      3. For Security Provider, select Custom.

      4. Click Add Login Module.

      5. In the field labeled JAAS Login Module Class, enter the following:

        com.sun.identity.agents.oracle.v1012.AmOracleLoginModule

      6. For Login Module Control Flag, select Required.

      7. Click OK.

      8. Complete the deployment procedures.

  9. Using an editor of your choice, access the J2EE agent AMAgent.properties file

  10. Set the following property as shown:

    com.sun.identity.agents.config.login.form[0] =
Deployment-URL/jsp/oracle10g_login.jsp

    where Deployment-URL represents the deployment URL of the application.

  11. Restart the Oracle Application Server 10g instance.

Next Steps

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] = Deployment-URL/jsp/oracle10g_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 Deployment-URL.

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.form[1] = /BankApp/SignOn

com.sun.identity.agents.config.login.form[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 AMAgent.properties configuration file, the web-tier declarative security is enabled for these applications.

Note –

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:


<html>
   <head>
      <title>Security Check</title>
   </head>
   <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">
      </form>
   </body>
</html>

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 AMAgent.properties 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 AMAgent.properties 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 AMAgent.properties 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");
%>
   <ul>
      <li>Your username for login is: <b><%=user%></b></li>
      <li>Your password for login is: <b><%=password%></b></li>
   </ul>
   <input type=hidden name="j_username" value="<%=user%>">
   <input type=hidden name="j_password" value="<%=password%>">
   <input type="submit" name="submit" value="CONTINUE">
</form>

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