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.
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> |
Edit the oracle10g_login.jsp file as required.
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
Edit the newly copied oracle10g_login.jsp file as shown.
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 |
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>
(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>
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.
Repackage the application.
Therefore, using the software tool of your choice, repackage the application as a JAR file.
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.
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
Take note of the application name and deployment URL (Map to URL).
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.
For Default Realm, accept the default, which is blank.
Therefore, by default no value is associated with Default Realm.
For XML Data, accept the default, which is “./jazn-data.xml.”
Complete the deployment procedure.
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
represents the directory within which the Oracle Application Server 10g10.12 instance was installed.
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
Take note of the application name and deployment URL.
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.
For Security Provider, select Custom.
Click Add Login Module.
In the field labeled JAAS Login Module Class, enter the following:
com.sun.identity.agents.oracle.v1012.AmOracleLoginModule
For Login Module Control Flag, select Required.
Click OK.
Complete the deployment procedures.
Using an editor of your choice, access the J2EE agent AMAgent.properties file
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.
Restart the Oracle Application Server 10g instance.
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.
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.