Introduction to ADF Security in JDeveloper 10.1.3.2

Authentication in ADF Security is enforced through a Servlet that is configured as adfAuthentication in the web.xml deployment descriptor. The servlet is protected by a J2EE security role in which all authorized application users are a member. Using the OC4J role " anyone " ADF Security allows developers to grant access to unauthenticated users, which is useful to maintain public pages and to enforcing lazy authentication.

Figure 5: JAAS provider selection

ADF Security supports both JAZN file-based security and the LDAP security provider for authentication and authorization. For application development the Lightweight XML Provider is the default. Note that selecting the LDAP Provider option in the wizard does not connect to the Oracle Internet Directory instance but configures the JAZN application deployment descriptor ( orion-application.xml) with the realm name and host location of the LDAP instance. The default lightweight XML provider reads its security definitions from system-jazn-data.xml, which at design time is located in JDeveloper_Home\jdev\system\oracle.j2ee.10.1.3.40.66\embedded-oc4j for development and testing.

Figure 6: Configuring the XML based Provider

If authorization is enforced for web applications, the repository location must be chosen as OC4J Default Repository, which points to the system-jazn-data.xml file in the OC4J configuration. The default realm in OC4J is jazn.com. A realm is comparable to a namespace that associates users and groups to a specific security policy. Setting the JAAS Mode to doAsPrivileged enforces permission checks to be performed against the Java permissions generated by the ADF Security design time for ADF iterator, attribute and control bindings. JAAS allows finer-grained authorization than standard J2EE container-managed security constraints defined on URL patterns.

Figure 7: J2EE authentication dialog

ADF Security uses J2EE container-managed authentication with one of the following authentication types: Basic Authentication, Digest Authentication, Forms-Based, Client Certificate.

If selecting Form-Based Authentication, an HTML file or a JSP file is required to define the login page and the error page. The login page contains an HTML form with the action attribute set to j_security_check and two input text fields: j_username and j_password. J2EE containers understand that the j_security_check action is used to perform J2EE authentication.

The Generate Default option generates two HTML files: login.html and error.html in the web application public_html directory. The login.html contains a HTML form element with the required j_security_check action and the j_username and j_password fields. To create files with a file name other than login.html, deselect the Generate Default option and click Browse to locate the desired file name. The files are created when finishing the ADF Security wizard.

If an ADF Faces application is configured to use the JAZN XML provider, then authentication is performed against user accounts defined in the system-jazn-data.xml file. If the LDAP provider is configured, then the authentication realm and user accounts are looked up in OID.

Figure 8: Creating and managing J2EE security roles in web.xml

J2EE security roles are defined in the web.xml deployment descriptor and mapped to users and groups in the system-jazn-data.xml file. If the role name in web.xml matches a group name in system-jazn-data.xml, no further mapping is required. If the names do not match, then the web.xml role name needs to be mapped to the name in the system-jazn-data.xml using the orion-application.xml file. The orion application file is automatically created and deployed with the J2EE application. Though it is possible to edit the web.xml deployment descriptor outside of the ADF Security wizard, it is recommended to use the wizard to configure user access to the ADF Security authentication servlet.

Finishing the ADF Security wizard writes the configuration information to the web.xml deployment descriptor and the orion-application.xml file.

Figure 9: ADF Security configuration in web.xml and orion-application.xml

Within the web.xml deployment descriptor, the ADF authentication servlet is created with a success_url initial parameter. The success_url contains the name of the application start page defined by setting the Redirect Upon Successful Authentication option as shown in Figure 3.

Configuring the embedded OC4J

The embedded OC4J J2EE container has its bootstrapping configuration files located in the JDeveloper_Home\jdev\system\oracle.j2ee.10.1.3.<version>\embedded-oc4j\config directory. The configuration file used for ADF Security development and testing in Oracle JDeveloper is system-jazn-data.xml. The system-jazn-data.xml is an XML-based security repository for Oracle JAAS and contains user accounts and passwords, user groups, and ADF Security JAAS permissions.

To configure the system-jazn-data.xml file for ADF Security from the Oracle JDeveloper IDE, choose the Tools | Embedded OC4J Server Preferences menu option.

Figure 10: Embedded OC4J configuration dialog

To configure ADF Security, the user and group accounts need to be created under the Global node. The jazn.com default realm also contains the OC4J administration accounts and for this reason is pre-defined in the system-jazn-data.xml file. For this how to example, three users sking , ahunold and dfaviet are created and assigned to the application roles users , managers and ceo.

The authentication servlet is protected using the same role names in the web.xml file, granting access to all user roles. If the role names configured in jazn-data.xml differ from the names used in web.xml, then the orion-application.xml file needs to be edited to map web.xml role names to system-jazn-data.xml roles as documented in the OC4J security guide. In this example, the names are the same and thus no extra configuration is needed.

Defining Authorization

Authorization in ADF Security is defined through Java Permissions. The application developer defines authorization declaratively for iterator bindings, action bindings, and method bindings defined in the ADF page definition ( pageDef.xml) file and, alternatively, for the entire page definition itself.

Figure 11: Authorization dialog for iterator bindings

A context menu option Edit Authorization on all bindings that can have authorization defined. The Authorization editor dialog shows all possible actions for the developer to identify which user roles are allowed to perform which actions. In JDeveloper 10.1.3.2 an application either has security configured or it doesn't. This means that if ADF Security is enabled for a web application, all ADF bindings must have grants configured. All security grants are written as permissions to the system-jazn-data.xml file. With ADF Security, the application developer doesn't need to understand how to implement JAAS to develop secure web applications. For deployment, the application specific permissions are defined in the app-jazn-data.xml file that is deployed with the EAR file. The deployment of web applications protected by ADF Security is explained later in this document.

Note: It is important to define authorization for the PageDef.xml files in the web application. Users need to have view privileges to access a JavaServer Faces page. Defining grants on the PageDef.xml file permits developers to set up page-level authorization, a security feature otherwise not available in JavaServer Faces.

Programmatic access control with ADF Security

Developers may need to access user permissions programmatically in their applications for example to hide or to show UI components that execute protected actions or perform navigation. Programmatic access control can be used to implement the 5th security policy in the sample application mentioned above: "All navigation controls are hidden from the user if the user is not authorized to perform the action".

Access through ADF Bindings

ADF Security sets the updateable flag on ADF attribute bindings and action bindings. If, for example, a user is not authorized to update the data displayed in a table, then the table binding's updateable property is automatically set to false. This information can be used with Expression Language to set the disabled property on a command button, as shown in the image below.

Figure 12: Disabling a command button through the updateable flag on the attribute binding

Access through Expression Language using the PermissionInfo object

The PermissionInfo object on the ADF Security Context allows access to ADF Security through Expression Language and Java. The PermissionInfo object is not shown in the Oracle JDeveloper Expression Language editor even though it exists on all binding types. The example of the disabled command button above can also be implemented with the PermissionInfo object as shown below:

#{!bindings.DepartmentsView1.permissionInfo.update}

The general use of PermissionInfo in Expression Language is

#{bindings.<iterator_binding>.permissionInfo.<read|create|delete|update>}
#{bindings.<method_binding>.permissionInfo.invoke}
#{bindings.<attribute_binding>.permissionInfo.<update|view>}

In addition, the PermissionInfo object allows developers to access information from a binding container other than the current one. This is useful to handle page authorization. In the sample application, the create button should only be enabled for managers and CEOs. In the policies defined for the sample application, a rule states that if the authenticated user is not allowed to view the EditCreateDepartmentsPageDef the Create button should be disabled. The Expression Language string that needs to be added to the command button Disabled property is:

#{!bindings.permissionInfo['EditCreateDepartmentsPageDef'].view}

Figure 13: Disabling command buttons based on different user privileges

Access control through calls to hasPermission()

It is also possible to directly check a specific permission grant using the hasPermission() method on the ADF Security Context. In this case the developer is aware of the permission names and actions defined in the system-jazn-data.xml. The example below executes a create operation only if the authenticated user is granted create on the RowSetPermission for the AppModuleDataControl.DepartmentsView1 iterator.

public String createDepartmentsAction() {
 final FacesContext fc = FacesContext.getCurrentInstance();
 final Application fapp = fc.getApplication();
 //get binding
 OperationBinding obind = (OperationBinding) fapp.createValueBinding("#{bindings.CreateDepartment}").getValue(fc);

 if ( ADFContext.getCurrent().getSecurityContext().hasPermission(new RowSetPermission("AppModuleDataControl.DepartmentsView1","create"))){
  obind.execute();
   if (obind.getErrors() == null || obind.getErrors().size()==0){
   return "editDepartments";
   }
  }
 return null;
 }

Note that using the hasPermission() method for access authorization bears the risk that later changes in the ADF Security permission classes will require modification of the application code. To avoid this dependency on physical implementation classes, the PermissionInfo object exists and should be used. The hasPermission() method makes sense to be used with custom permission classes.

ADF Faces security aware components

ADF Faces components, like af:inputText, are security-aware in that they render read-only if a user is not authorized to update the underlying ADF attribute binding. In the sample policy, rule 4 states that "Managers are not allowed to update the Department ID". The attribute authorization for the DeptId is set on the ADF binding layer through the pagedef.xml file so that managers have no update privilege. The image below shows the form rendering of the EditCreateDepartments.jspx page when i) connecting as a manager and ii) when connecting as the CEO.

Figure 14: Security aware ADF Faces components shows i) read-only text field for unauthorized user and ii) editable text field for authorized user

ADF Security Deployment

ADF Security is deployed by configuring the JAZN security provider of the target system with the Java security permissions created during web application development. In a deployment to the file-based provider, the Java Permissions need to be added manually to the system-jazn-data.xml file of the target OC4J instance. In a deployment that uses the Oracle Internet Directory (OID) as the security provider, the security permissions need to be uploaded to OID. The upload is handled through ldiff files, which is a specific file format for updating LDA entries using the ldapadd or ldapmodify command. A utility that migrates jazn-data.xml file entries to ldiff is provided with OC4J and documented in Chapter 7: File-Based Security Provider of the Oracle Containers for J2EE Security Guide.

Figure 15: ADF Security entry in OID

app-jazn-data.xml

The app-jazn-data.xml file is located in the .adf\META-INF folder under the Oracle JDeveloper workspace root folder and is deployed with the application. The JDeveloper_Home\jdev\system\ oracle.j2ee.10.1.3.<version>\embedded-oc4j\config\system-jazn-data.xml file that is used to store the Java Permissions during development is not empty but contains permissions and user accounts needed to run OC4J.

To make ADF Security deployment easier, the app-jazn-data.xml file contains only those Java Permissions of the system-jazn-data.xml file in Oracle JDeveloper that are added by ADF Security. Deploying the app-jazn-data.xml file with the application makes the security definitions available to the system administrator who sets up ADF Security for the production runtime.

To set up ADF Security for the file-based provider, the system administrator copies the user group and permission entries to the system-jazn-data.xml file of the target OC4J instance.

To set up the LDAP provider with ADF Security, the administrator uses the JAZN migration utility to create an ldiff file out of the app-jazn-data.xml file. The ldiff file then is used to configure OID through the ldappadd or ldapmodify command as documented in the OC4J Security Guide.

Summary

ADF Security is a protection framework in Oracle ADF to authorize user access to iterator bindings, action bindings, and attribute bindings. ADF Security implements application security independent of the business service layer and works with EJB, POJO, ADF Business Components, and web services alike.

For further documentation see

Chapter 8: WebCenter Framework Tutorial
Chapter 7: File-Based Security Provider
Chapter 8: Oracle WebCenter Framework Developer's Guide