52 Implement Function Security

This chapter describes how to enforce security to authorize access to securable application artifacts created using Oracle Application Development Framework (Oracle ADF) in Oracle Fusion applications.

This chapter contains the following sections:

52.1 Introduction to Function Security

An important principle of Oracle Fusion function security ensures that end users do not have unintended access to web pages and application resources in an application that is created using Oracle Application Development Framework (Oracle ADF).

To enable access to application resources, you can use JDeveloper to create security policies to specify "who can perform what operations on what specific application artifacts."

To create the security policy, you must consider the additional duties the end users of the application will perform and then grant the desired roles specific rights to:

  • Access application resources, such as a custom ADF task flow that supports the duty

  • Initiate only those operations on the data required by the duty

Note:

Securing the data of the application requires creating data security policies. For details about creating data security policies, see Implementing Oracle Fusion Data Security.

Function security controls access to securable ADF artifacts including ADF task flows and top-level web pages backed by ADF page definition files. Function security may also control the visibility of UI components within the web pages. Users who do not have the required privilege cannot view the task flow or view buttons that initiate create, update, and delete operations. For example, in a sales organization, duties such as Manage_Accounts and Manage_Invoices exist for roles, such as Sales_Manager or Sales_Associate. A function security policy might give end users who belong to the Sales_Manager role the ability to view and edit customer invoices. Whereas, end users who do not belong to the Sales_Manager role, may enter the task flow to view customer invoices but not edit them.

52.1.1 Function Security Development Environment

Before you can implement function security for custom application resources, a security administrator must export the function security definitions from an LDAP-based policy store (typically from a staging environment) into a file-based policy store that you can work with in JDeveloper. The exported file will contain the function security artifacts that will enable you to run your application and access the resources that may otherwise have been secured by predefined function security policies.

The file you receive is formatted as XML and named jazn-data.xml. The XML definitions of the exported file comprise two major sections: an identity store to define valid end users of the application and a policy store to define the security policies that are specific to the application. Initially, only the policy store will be populated with security artifacts from the LDAP stores. The exported jazn-data.xml file will not contain the end user identities of the enterprise, thus the identity store section will initially appear empty.

Note:

As an Oracle Fusion security guideline, do not modify the predefined function security definitions contained in the jazn-data.xml file. Predefined security definitions include the security definitions of the Oracle security reference implementation and must not be modified. The security reference implementation provides role-based access control in Oracle Fusion Applications, and is composed of predefined security policies that protect functions, data, and segregation of duties. You should always add custom application roles to grant access rights. For details about restrictions when working with the file-based policy store, see What You May Need to Know About Actions That Developers Must Not Perform.

When you define security policies for custom Oracle ADF application artifacts, you should only use Oracle JDeveloper tools to work on the exported file-based policy store, and you should not edit the security definitions directly. JDeveloper supports iterative development of security so you can easily create, test, and edit security policies that you define.

After you customize security, you use JDeveloper to add end user identities to the identity store of the exported file before running and testing the application in JDeveloper's Integrated WebLogic Server. You provision a few test end user identities by defining user groups and then assign those groups to application roles to simulate how the actual end users of the enterprise will access the secured application artifacts. When you deploy the application in your development environment, JDeveloper migrates the identity store you created to the embedded LDAP of Integrated WebLogic Server. The application policy store is migrated to a system-jazn-data.xml file that aggregates the security policies definitions of all applications in your workspace.

After testing in JDeveloper, you must consult with the security administrator to merge the LDAP-based application policy store in the staging environment with the security policies that you added to the exported jazn-data.xml file. The staging environment is an LDAP-based Oracle WebLogic Server configured to use Oracle Internet Directory (OID) for the enterprise's application policy store and identity store (note that the stores of the staging server are LDAP-based and not file-based). Initially, the staging environment allows further testing using that server's identity store before deploying to the production environment. Thus, end user identities created in JDeveloper are not migrated to standalone Oracle WebLogic Server and are used only in Integrated WebLogic Server to test the extended application.

52.1.2 Function Security Implementation Scenarios

As an Oracle Fusion security guideline, when you secure the functions of your application, you should not modify the predefined security definitions specified by the Oracle Fusion security reference implementation. When you modify the file-based policy store, always create new security definitions.

Note:

The term protected in this chapter refers to the default Oracle Fusion application condition that denies end users access to database resources and application artifacts. In contrast, the term secured refers to resources that have been made accessible to end users through security policies created for this purpose. Therefore, a security policy specifically enables access to the resource based on the access rights it confers to the end user.

The following table summarizes the function security scenarios that Oracle Fusion security supports. The "Application Developer Tasks" column of the table provides a brief description of the security artifacts involved in each scenario.

Table 52-1 Oracle Fusion Function Security Use Cases

Security Goal Security Policy Requirement Application Developer Tasks

Control whether the end user associated with a particular role may access a new task flow and view all the web pages of the flow.

Create a new entitlement grant.

The new task flow will be inaccessible by default (also called protected) and will require a new function security policy to grant end users access.

Because the end user duty being secured is rarely addressed by grants to a single resource, the Oracle Fusion security best practice is to create entitlement grants.

Entitlement grants provide the means to aggregate multiple securable resources into a named security group so that privileges for the entire group can be granted to application roles through a single statement.

Enable ADF Security on the user interface project to protect all task flows (and the web pages they contain). Then, in the file-based policy store, create a resource definition for the task flow and assign the definition as a member of an entitlement (defined in the policy store as a permission set) that you name. Then, create the security policy by granting the entitlement to a custom application role that you either created or consulted with a security administrator to create for you.

For more information, see How to Create Entitlement Grants for Custom Application Roles.

Control whether the end user associated with a particular role may access a new top-level web page.

In Oracle Fusion applications, a top-level web page is one that is not contained by a task flow.

Create a new entitlement grant.

The new top-level web page will be inaccessible by default (also called protected) and will require a new function security policy to grant end users access.

The ability to secure individual web pages in Oracle Fusion applications is reserved for top-level web pages backed by an ADF page definition file only.

Enable ADF Security on the user interface project to protect all top-level web pages backed by ADF page definition files. Then, in the file-based policy store, create a resource definition for the web page and assign the definition as a member of an entitlement (defined in the policy store as a permission set) that you name. Then, create the security policy by granting the entitlement to a custom application role that you either created or consulted with a security administrator to create for you.

For more information, see How to Create Entitlement Grants for Custom Application Roles.

Control whether a new task flow or a new top-level web page is publicly accessible.

Publicly accessible means the application resource may accessed by guest users (those who do not need to log into the application) or it can mean accessible to all authenticated users who are not provisioned with the privileges conferred by a custom application role.

Create a new resource grant.

The new ADF artifact will be inaccessible by default (also called protected) and will require a new function security policy to grant end users access.

Because the publicly accessible artifact is a single resource, the Oracle Fusion security best practice is to create resource grants (rather than entitlement grants) for publicly accessible artifacts.

Enable ADF Security on the user interface project to protect all ADF-backed application artifacts. Then, in the file-based policy store, grant an action (defined in the policy store as a permission) directly to the artifact. Then, create the security policy by granting the permission to a built-in OPSS application role.

For more information, see How to Define Resource Grants for OPSS Built-In Roles.

Determine whether the end user associated with a particular role has the right to view UI components, such as buttons that initiate create, update, or delete operations in the displayed web page.

Create a grant.

Access to user interface components, such as buttons can be controlled by rendering the button in the user interface based on a permission check.

Conditionally render the component by entering ADF Security Expression Language (EL) utility methods on the rendered attribute of the button to test whether the end user has the necessary permission grant.

For more information about rendering components using EL utility methods, see the "Enabling ADF Security in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about how data security and function security work together to control access to the data and functions of the application, see the "Customizing Security for Oracle ADF Application Artifacts" chapter in the Extensibility Guide for Developers.

52.1.3 Function Security-Related Application Files

When you create a Fusion web application, JDeveloper creates specific files that are needed to secure the application. Additionally, when you run the Configure ADF Security wizard, JDeveloper updates these files to reflect the selections you make in the wizard.

For details about the created files, see the "What Happens When You Enable ADF Security" section in the Developing Fusion Web Applications with Oracle Application Development Framework.

52.2 Function Security Implementation Process Overview

An ADF bounded task flow that you add to your application is one of the main ADF artifacts that you that you can secure. You can also directly secure top-level web pages that are backed by ADF page definitions to specify data bindings. Although you can secure a variety of application resources, implementing function security follows a similar pattern.

Before You Begin

You will need to complete these tasks:

  1. Decide the names of custom application roles that your application will specify as the grantee of security privileges.

  2. Optionally, ask the security administrator to create custom application roles with the names you supply.

    If a security administrator creates the application roles you identify, then those custom application roles will already appear in the policy store section of the exported jazn-data.xml file.

    If you do not ask the security administrator to create custom application roles, then you must create them in JDeveloper before you define security policies.

  3. Consult a security administrator to export all predefined function security policies of the application that you are customizing into a jazn-data.xml file.

    For details about extracting data from an OID store to a file, see the "Security Store Management" section of the Administrator's Guide.

To implement function security:

  1. Copy the exported jazn-data.xml file into your application workspace.

    This is the file that JDeveloper will update when you create function security policies. In order for JDeveloper to use the file, copy the file to your application workspace in the <JDevAppHome>/src/META-INF folder.

  2. Determine which ADF artifacts should be secured and grant entitlement privileges to custom application roles to specify the access rights of end users.

    Although ADF Security permits you to define function security policies for ADF artifacts using only resource privilege grants, an Oracle Fusion security best practice is to define access policies using entitlement grants except for publicly accessible application artifacts.

    For details about securing application functions, see How to Create Entitlement Grants for Custom Application Roles.

  3. Determine which ADF artifacts should be public and grant resource privileges to an appropriate OPSS built-in application role.

    For details about making application functions public, see How to Define Resource Grants for OPSS Built-In Roles.

  4. Opt into the previously defined function security policies by running the Configure ADF Security wizard to enforce OPSS authorization checking.

    For details about enabling security on the user interface project, see How to Enforce Authorization for Securable ADF Artifacts.

  5. Determine which user interface components you want to associate with user entitlements, and enter ADF Security-based EL utility methods on the component to make it logically consistent with its target.

    ADF does not enforce security on user interface components, such as buttons or links that navigate to securable artifacts (pages and task flows).

  6. Define test user identities and run the application in JDeveloper to simulate the privileges of the enterprise users who will eventually interact with the application.

    For details about adding test user in JDeveloper, see How to Enable Authentication and Test the Application in JDeveloper.

To migrate security policies to the domain policy store:

  1. After testing is complete, remove the test users from the jazn-data.xml file and provide the updated jazn-data.xml file to the security administrator to merge the file-based policy store with the application policy store in the staging environment.

    JDeveloper must not be used as an identity store provisioning tool, and you must be careful not to deploy the application with user identities that you create for testing purposes. Deploying user identities with the application introduces the risk that malicious users may gain unintended access.

  2. The security administrator provisions enterprise users by mapping enterprise roles defined in the staging environment identity store to the custom application roles.

    For information about how the security administrator provisions enterprise users using Oracle Authorization Policy Manager, see the product-specific security guides.

  3. Before running the application in the staging environment, the security administrator must reconcile the application roles GUIDs of any data security policies that were created based on new custom application roles.

    When the file-based policy store is merged, the GUIDs of application roles are not preserved.

  4. Continue testing the application in the staging environment before deploying the application to production and merging the policies into the production environment application policy store.

    For details about how to modify the application to use the identity store and policy store of the staging environment, see What You May Need to Know About Testing.

52.3 Add Function Security to the Application

You implement function security by identifying the type of resource that corresponds to the ADF artifact whose function you intend to secure. You then select a resource instance of that type and select the action that corresponds to the artifact function you intend to grant to end users. Function security aggregates these resource / action pairs as an entitlement that serves as the grantable entity. Each entitlement can include as many resource / action pairs as needed to describe a particular duty to be performed by the end user. To support this goal, entitlements can include resources of different types. To create a function security policy, you then grant the entitlement to a custom application role, also called a duty role in Oracle Fusion applications.

In cases where a resource should be publicly accessible, you will not need to aggregate multiple resources to define a particular duty. Instead, you can create a resource-based function security policy with a single resource /action pair defined as the grantable entity.

Note:

Although ADF Security permits you to define function security policies for ADF artifacts using only resource privilege grants, an Oracle Fusion security best practice is to define access policies using entitlement grants except for publicly accessible application artifacts.

To simplify the task of securing the functions of your application, ADF provides the ADF Security framework. ADF Security defines a containment hierarchy that lets you define a single security policy for the ADF bounded task flow and its contains web pages. In other words, the security policy defined at the level of the bounded task flow, secures the flow's entry point and then all pages within that flow are secured by the same policy. For example, a series of web pages may guide new end users through a registration process and the bounded task flow controls page navigation for the process.

Specifically, ADF artifacts that are automatically protected by ADF Security and require function security policies to grant users access are:

  • ADF bounded task flow protects the entry point to the task flow, which in turn controls the end user's access to the pages contained by the flow

    The ADF unbounded task flow is not a securable application artifact and thus does not participate in OPSS authorization checks. When you need to secure the constituent pages of an unbounded task flow, you define policies for the page definition files associated with the pages instead.

  • ADF page definition files associated with top-level web pages and regions

    For example, a page may display a summary of products with data coordinated by the ADF bindings of the page's associated ADF page definition file.

Best Practice:

Do not create entitlement grants for the individual web pages of an ADF bounded task flow. When the end user accesses the bounded task flow, security for all pages will be managed by the entitlements you create for the task flow. This supports a well-defined security model for task flows that enforces a single entry point for all end users. For additional best practice information about ADF and function security, see What You May Need to Know About ADF Security Guidelines.

To add function security to the application:

  1. Determine which ADF task flows and top-level web pages should be secured and grant entitlement privileges to custom application roles to define the duties of end users.
  2. Determine which ADF task flows and top-level web pages should be public and grant resource privileges to an appropriate OPSS built-in application role.
  3. Determine which user interface components should be secured and create a resource permission and grant the view action in the entitlement grant to a custom application role.

    ADF does not automatically enforce security on user interface components, such as buttons or links that navigate to securable artifacts (pages and task flows). To secure these application artifacts, you must create a resource permission that the application can test by entering ADF Security-based EL utility methods on the component to make it logically consistent with its target.

  4. Opt into the previously defined function security policies by running the Configure ADF Security wizard to enforce OPSS authorization checking.
  5. Define test user identities and run the application in JDeveloper to simulate the privileges of the enterprise users who will eventually interact with the application.

52.3.1 How to Create Entitlement Grants for Custom Application Roles

Because the particular end user duty you want to secure is rarely addressed by grants to a single resource, you define the access policy for securable ADF artifacts by creating entitlement grants. Resource grants are only necessary to define publicly accessible application artifacts, as described in How to Define Resource Grants for OPSS Built-In Roles.

You create entitlement grants in the Entitlements Grants page of the jazn-data.xml file overview editor. The grants you create will appear as metadata in the policy store section of the jazn-data.xml file. This metadata defines an entitlement (identified in the XML definition as <permission-set>) comprised of resource instance /action pairs that you select. This entitlement is a grantable entity that you then grant to a custom application role.

Note:

Note that, in Oracle Fusion Applications, application roles are called duty roles. You must not modify predefined duty roles, and you must always add custom application roles (duty roles) to grant access permissions.

The list of resource types appears in the security policy overview editor. The resource type you select filters the resource instances defined within the projects of your application's workspace. The resource type selection also determines the list of available actions displayed by the overview editor. For example, when you select the Task Flow resource type, the overview editor will display all of the task flows in the user interface projects that you select and also displays the view action that you can associate with the available ADF bounded task flow resources.

The following table lists the resource types displayed in JDeveloper and identifies the associated resource and actions.

Table 52-2 Resource Types of Securable ADF Artifacts

Resource Type Supports These Resources and Actions

ADF Task Flow

Defines personalize, customize, grant, edit, and view actions on ADF bounded task flows in a Fusion Web application.

ADF Region

Defines personalize, customize, grant, edit, and view actions on regions and web pages backed by an ADF page definition file in a Fusion Web application.

ADF Entity Permission

Not used by Oracle Fusion Applications. Data security is provided by Oracle Fusion Data Security, as described in Implementing Oracle Fusion Data Security.

ADF Method Resource

Defines execute, invoke, and view actions on ADF methods in a Fusion web application.

Resource Permission

Defines custom actions on any functional artifact in a Fusion web application. Resource permissions are useful to create grants for UI components, as described in How to Protect UI Components.

Webservice Resource

Defines invoke actions on Fusion Web services. For more details about securing Web services, see Authorizing the Web Service with Entitlement Grants.

To define an entitlement grant for a securable ADF artifact, use the Entitlement Grants page of the overview editor for the jazn-data.xml file. This editor is also called the security policy overview editor.

Before you begin:

It may be helpful to understand the details of the ADF Security containment model. For more information, see What You May Need to Know About ADF Security Guidelines.

You will need to complete these tasks:

  • Consult the security administrator for the enterprise to obtain the jazn-data.xml file that contains the predefined function security policies for your application. You must add the file to your application workspace, as explained in Function Security Implementation Process Overview.

  • Create application roles as described in the "Enabling ADF Security in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework, in the Oracle Fusion Middleware Online Documentation Library.

To define an entitlement grant for an ADF artifact:

  1. In the main menu, choose Application and then Secure > Entitlement Grants.
  2. In the Entitlement Grants page of security policy overview editor, click the Add Entitlements icon in the Entitlements list.

    The overview editor displays all the resources that your application defines.

  3. In the Resources section, click the Add Member Resource icon to add a member resource to the entitlement.
  4. In the Select Resources dialog, select the resource from the Resource Type dropdown and then select the desired project in the Source Projects list.

    The dialog displays all the projects in your application workspace.

  5. In the Available Resources list, select the resource from and click the Add icon.

    The dialog displays all the resources define by your selected project.

  6. In the Actions lists, select the desired action for the selected resource.

    The following figure shows the overview editor with the View action selected for the task flow and added to MyEntitlement.

    Figure 52-1 Adding a Bounded Task Flow as a Resource in an Entitlement Grant

    Described in the surrounding text.
  7. Add other desired resources to the list.
  8. In the Grants section of the security policy overview editor, click the Add Role Grants icon to grant the entitlement to an application role.
  9. In the Select Application Roles dialog, select one or more custom application roles.

    The dialog displays all the application roles from the jazn-data.xml file. You must not add a grant to a predefined application role (also called duty roles in the terminology of Oracle Fusion Applications). Only select custom application roles that either you created in JDeveloper or that were created by a security administrator for this purpose.

  10. Click OK.
  11. You can repeat these steps to add other resources and make grants on those resources to the same entitlement for the same custom application role.

52.3.2 What Happens After You Create an Entitlement Grant

When you use the security policy editor in JDeveloper to create an entitlement grant, JDeveloper modifies the source for the application policy store in the jazn-data.xml file. The policy store section of the file contains a <resource-type> definition (that identifies the actions supported for resources of the selected type), a <resource> definition (to identify the resource instance that you selected from your application and mapped to a resource type), a <permission-set> definition (to define the resources and actions to be granted as an entitlement), and a <grant> definition with one or more entitlements (defined in the XML as a permission set) granted to the desired application roles (the grantee).

As the following example shows, entitlement-based security policies in the Oracle Fusion application are defined in the <jazn-policies> element and consist of one or more entitlements granted to a single application role.

Example 52-1 Entitlement-Based Policy Definition in the jazn-data.xml File

<?xml version="1.0" ?>
<jazn-data>
  <policy-store>
    <applications>
      <application>
        <name>MyApp</name>
                
        <app-roles>
        <app-role>
          <name>AppRole</name>
          <display-name>AppRole display name</display-name>
          <description>AppRole description</description>
          <guid>F5494E409CFB11DEBFEBC11296284F58</guid>
          <class>oracle.security.jps.service.policystore.ApplicationRole</class>
        </app-role>
      </app-roles>
                
      <role-categories>
        <role-category>
          <name>MyAppRoleCategory</name>
          <display-name>MyAppRoleCategory display name</display-name>
          <description>MyAppRoleCategory description</description>
        </role-category>
      </role-categories>
                
      <!-- resource-specific OPSS permission class definition -->
      <resource-types>
        <resource-type>
          <name>APredefinedResourceType</name>
          <display-name>APredefinedResourceType display name</display-name>
          <description>APredefinedResourceType description</description>
          <provider-name>APredefinedResourceType provider</provider-name>
          <matcher-class>oracle.security.jps.ResourcePermission</matcher-class>
          <actions-delimiter>,</actions-delimiter>
          <actions>write,read</actions>
        </resource-type>
      </resource-types>
                
      <resources>
        <resource>
          <name>MyResource</name>
          <display-name>MyResource display name</display-name>
          <description>MyResource description</description>
          <type-name-ref>APredefinedResourceType</type-name-ref>
        </resource>
      </resources>
                
      <!-- entitlement definition -->
      <permission-sets>
        <permission-set>
          <name>MyEntitlement</name>
          <display-name>MyEntitlement display name</display-name>
          <description>MyEntitlement description</description>
          <member-resources>
            <member-resource>
              <type-name-ref>APredefinedResourceType</type-name-ref>
              <resource-name>MyResource</resource-name>
              <actions>write</actions>
            </member-resource>
          </member-resources>
        </permission-set>
      </permission-sets>
                
      <!-- Oracle function security policies -->
      <jazn-policy>
        <!-- function security policy is a grantee and permission set -->
        <grant>
          <!-- application role is the recipient of the privileges -->
          <grantee>
            <principals>
              <principal>
                <class>
                   oracle.security.jps.service.policystore.ApplicationRole
                </class>
                <name>AppRole</name>
                <guid>F5494E409CFB11DEBFEBC11296284F58</guid>
              </principal>
            </principals>
          </grantee>

          <!-- entitlement granted to an application role -->
          <permission-set-refs>
            <permission-set-ref>
              <name>MyEntitlement</name>
            </permission-set-ref>
          </permission-set-refs>
        </grant>
      </jazn-policy>
    </application>      
  </applications>
 </policy-store>
</jazn-data>

52.3.3 How to Define Resource Grants for OPSS Built-In Roles

A common requirement of the application is that some web pages be available to all end users, regardless of their specific access privileges. For example, the home page should be seen by all visitors to the site, while a corporate site should be available only to those who have identified themselves through authentication.

In both cases, the page may be considered public, because the ability to view the page is not defined by the end users' specific privileges. Rather, the difference is whether the end user is anonymous or a known identity.

In the OPSS security model, you differentiate between the absence of security and public access to content by granting access privileges to the anonymous-role principal. The anonymous-role allows access to a resource by unauthenticated users, for example, guest users. To provide access to authenticated users only, the policy must be defined for the authenticated-role principal.

The built-in OPSS role authenticated-role stands for any authenticated user and is useful to implement authorization checks for end users who do not need to be explicitly assigned to specific custom application roles to get access to a resource. The authenticated-role can be directly granted any resource grants.

Before you begin:

It may be helpful to have an understanding of OPSS support for public, unprotected resources. For more information, see the "Understanding Users and Roles" chapter of the Oracle Fusion Middleware Applications Security Guide, in the Oracle Fusion Middleware Online Documentation Library.

It may also be helpful to understand the details of the ADF Security containment model. For more information, see What You May Need to Know About ADF Security Guidelines.

You will need to complete this task:

  • Consult the security administrator for the enterprise to obtain the jazn-data.xml file that contains the predefined function security policies for your application. You must add the file to your application workspace, as explained in Function Security Implementation Process Overview.

To grant public access to securable ADF artifact:

  1. In the main menu, choose Application and then Secure > Resource Grants.
  2. In the Resource Grants page of security policy overview editor, select the resource from the Resource Type dropdown and then select the desired project in the Source Projects list.

    The overview editor displays all the projects in your application workspace.

  3. In the Resources column, select the ADF artifact for which you want to grant access rights.

    Tip: Click the lock icon to show only those resources that do not yet have grants.

  4. In the Granted to column, click the Add Grantee icon and choose Add Application Role.
  5. In the Select Application Roles dialog, select one of these built-in application roles:

    • anonymous-role means the resource will be accessible to anyone who visits the site. A grant to this role is necessary if you want to make web pages backed by securable ADF artifacts accessible before an end user logs in. For example, you would grant to anonymous-role for an ADF bounded task flow that manages customer registration.

    • authenticated-role means the resource will be accessible only to authenticated users (ones who visit the site and log in). For example, you would grant to authenticated-role for an ADF bounded task flow that manages employee registration.

  6. In the Select Application Roles dialog, click OK.
  7. In the Resource Grants page of the overview editor, in the Actions column, select the desired action.

    The following figure shows the overview editor with the View action selected for the task flow and granted to authenticated-role.

    Figure 52-2 Granting to authenticated-role in the Overview Editor

    Described in the surrounding text.

52.3.4 What Happens When You Make an ADF Resource Public

When you use the security policy editor in JDeveloper to create a resource grant, JDeveloper modifies the source for the application policy store in the jazn-data.xml file.

The following example shows a resource-based security policy in the jazn-data.xml file that makes a customer registration task flow public to all authenticated users. The grant to the OPSS built-in role authenticated-role contains a single view permission for a bounded task flow, customer-registration-task-flow. With this grant, any authenticated user will be able to enter the employee registration task flow.

Example 52-2 Resource-Based Policy Definition in the jazn-data.xml File

<policy-store>
   ...
   <jazn-policy>
      <grant>
        <grantee>
            <principals>
                <principal>
                   <class>oracle.security.jps.internal.core.
                                    principals.JpsAuthenticatedRoleImpl</class>
                   <name>authenticated-role</name>
                </principal>
            </principals>
         </grantee>
         <permissions>
            <permission>
                  <class>oracle.adf.controller.security.TaskFlowPermission</class>
                  <name>/WEB-INF/customer-registration-task-flow.xml#
                                    customer-registration-task-flow</name>
                  <actions>view</actions>
            </permission>
            ...
         </permissions>
      ...
      </grant>
      ...
   </jazn-policy>
</policy-store>

52.3.5 How to Protect UI Components

Security expressions in the ADF Security EL namespace let you check the user permission, authentication and role membership status before displaying UI components in your page. When you need fine-grained protection over UI components to secure functional parts of the application that are not part of task flow security or web page security, you use the EL value userGrantedResource and a resource grant that you define for a custom resource type. For instance, through a resource grant that you create for a menu item, the application may either enable or disable a Cancel Shipment menu item to limit who may perform customer order updates.

Resource grants for custom resources types rely on the ResourcePermission class, which is provided by Oracle Platform Security Services (OPSS) and packaged with the application.

You use the overview editor for security policies to create a security policy for the custom resource type. And, in your web page, you use the security expression to evaluate the user's access rights to the UI component projected by the resource grant.

To grant resource policies for a custom resource type:

  1. Create the custom resource type for the UI component you want to protect.
  2. Create the resource grant for the custom resource.
  3. Associate the rendering of a UI component with a role's granted resource permission.

    For complete details about protecting UI components, see the "How to Protect UI Components Using OPSS Resource Permissions and EL" section in the Developing Fusion Web Applications with Oracle Application Development Framework.

52.3.6 How to Enforce Authorization for Securable ADF Artifacts

You run the Configure ADF Security wizard to enable authorization and make the function security policies you define effective. When you run the Configure ADF Security wizard, it has the following affect:

  • It configures your application to enable OPSS security when running in the JDeveloper test environment.

  • It allows the Integrated WebLogic Server to use the file-based security policies to authorize access to application resources by the end user (where OPSS determines at runtime whether the end user (represented by the JAAS subject) has the privileges necessary to access the resources they intend.

When you run the wizard, you are effectively enforcing authorization checking for all securable ADF artifacts. The wizard also enables the ADF authentication servlet to require the end user to log in the first time a page in the application is accessed.

This configuration requires a valid user to access the pages of your application. This assumes that you will define custom application roles and assign explicit grants to those roles to manage access to securable ADF artifacts, as described in How to Create Entitlement Grants for Custom Application Roles. Alternatively, when you want to make a page pubic and accessible by unauthenticated user, you must explicitly grant to a built-in OPSS role, as described in How to Define Resource Grants for OPSS Built-In Roles.

Before you begin:

It may be helpful to have an understanding of the configuration changes made by the Configure ADF Security wizard. For more information, see the "Enabling ADF Security in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework, in the Oracle Fusion Middleware Online Documentation Library.

It may also be helpful to have an understanding of the test-all role when you want to test the application without restricted access. For more information, see the "Enabling ADF Security in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework, in the Oracle Fusion Middleware Online Documentation Library.

To enforce authorization:

  1. In the main menu, choose Application and then Secure > Configure ADF Security.
  2. Complete the Configure ADF Security wizard pages.

    For complete details about running the wizard, see the "Enabling ADF Security" section in the Developing Fusion Web Applications with Oracle Application Development Framework.

52.3.7 How to Enable Authentication and Test the Application in JDeveloper

Authentication is enabled when you run the Configure ADF Security wizard, as described in How to Enforce Authorization for Securable ADF Artifacts. This means you when you run your application, you will be prompted to log in upon accessing any page backed by securable ADF artifacts.

To test your application, you will need to create test user identities and provision them with the custom application roles that you defined. The end user's membership in an application role defines their access privileges to the resources. If you prefer to be consistent with the Oracle Fusion standard for provisioning users and simulate how the actual end users of the enterprise access resources, you can optionally provision test users by defining enterprise roles consisting of groups of users (called job roles in Oracle Fusion applications) and then assign those groups to application roles (called duty roles in Oracle Fusion applications).

Note that if you enabled the option to grant to a test role when you run the Configure ADF Security wizard, your grants may be of the following two types:

  • For the task flows that you create before running the Configure ADF Security wizard, the wizard automatically assigns them to the test-all role. You will need to remove these grants and create valid grants to your custom application roles. For each entitlement granted to a specific role, the equivalent grant to the test-all role must be removed.

  • The new task flows you create after running the Configure ADF Security wizard are not granted to the test-all role automatically. You need to manually grant the entitlements for the new task flows to your custom application roles.

Related Links

The following document provides additional information about Oracle Fusion Middleware topics discussed in this section:

  • For details about creating test users, see the "Enabling ADF Security in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework, in the Oracle Fusion Middleware Online Documentation Library.

52.3.8 What You May Need to Know About Actions That Developers Must Not Perform

Security definitions that are predefined in the Oracle Fusion security reference implementation must not be changed by developers. When modifying the file-based policy store, always create custom application roles and define new entitlement grants.

Specifically, developers must not make the following changes to the predefined security definitions of the Oracle Fusion security reference implementation.

  • Add or remove entitlement grants on predefined application roles (those supplied by Oracle).

  • Add or remove resources on predefined entitlements (those supplied by Oracle).

  • Add or remove actions on resources on predefined entitlements (those supplied by Oracle).

For more information about the Oracle Fusion security reference implementation, see the product-specific security guides.

52.3.9 What You May Need to Know About Testing

When the application needs to undergo testing either in your local environment or on a staging server, the following changes will ensure that the application uses the LDAP-based identity and policy stores configured on the staging server.

To configure the deployed application to use the security repositories on the target server:

  1. Set the application name in the web.xml file to point to the application stripe on the target server.

    The domain policy store is logically partitioned in stripes, one for each application name specified in the file system-jazn-data.xml under the element <applications>. Each stripe identifies the subset of domain policies pertaining to a particular application. For more details about application stripes, see the "Managing the Policy Store" chapter in the Oracle Fusion Middleware Applications Security Guide.

  2. Set the jps.policystore.applicationid in the weblogic-application.xml file to point to the application stripe on the target server.
  3. If you want the policies to persist on the staging server after the application is undeployed, then set the jps.policystore.removal flag in the weblogic-application.xml file.
  4. Note that the jps-config.xml file in the application does not need to be modified. When the application is deployed, the staging server will have its own instance of the jps-config.xml file which is configured through a WLST command (the reassociateSecurityStore command). Therefore, the application jps-config.xml file can remain unchanged.

If you use JDeveloper to deploy to the application to standalone Oracle WebLogic Server, then you must ensure the Users and Groups checkbox is not selected in the application deployment properties (Menu Application > Secure > Configure Security Deployment…), as shown in the following figure.

Figure 52-3 Application Deployment Properties Related to Security

Described in the surrounding text.

As a security best practice, you should not migrate users and groups that you create in JDeveloper. If the Users and Groups checkbox is selected, test users and groups in jazn-data.xml will be merged into the target server with different GUIDs than those used to grant data security privileges.

Note:

JDeveloper must not be used as an identity store provisioning tool, and you must be careful not to deploy the application with user identities that you create for testing purposes. Deploying user identities with the application introduces the risk that malicious users may gain unintended access. Instead, rely on the system administrator to configure user identities through the tools provided by the domain-level identity management system.

Before testing the application in the staging environment, any custom application roles that you created will need to be created in the LDAP application policy store. These new application roles will receive new GUIDs and any data security policies defined for application roles of the same name must have their GUIDs reconciled.

Related Links

The following document provides additional information about Oracle Fusion Middleware topics discussed in this section:

  • For details about the LDAP identity and policy store configuration, see the "OPSS Services" part of the Oracle Fusion Middleware Applications Security Guide, in the Oracle Fusion Middleware Online Documentation Library.

  • For details about how security administrators reconcile GUIDs in the data security repository, see the "Reconciling GUIDs" section in the Administrator's Guide.

52.3.10 What You May Need to Know About ADF Security Guidelines

ADF implements a particular security model. Follow these rules to address problems you encounter when adding security to the application:

  • Bounded task flows are secured by default. Secured by default means OPSS will check authorization on all bounded task flows when ADF Security has been enabled.

  • Pages and page fragments backed by an ADF page definition file are also secured by default when not embedded in a bounded task flow. Keep in mind that OPSS will not check authorization for pages or page fragments that do not have a corresponding ADF page definition file.

  • Pages and page fragments embedded in bounded task flows will not be checked by OPSS for authorization. Instead, they are granted or denied as a unit depending on the entitlement granted to the bounded task flow. That means those pages and page fragments do not need to be explicitly granted in the policy store.

  • Bounded task flows embedded in bounded task flows will by checked by OPSS for authorization.

  • ADF does not enforce security on user interface components, such as buttons or links) that navigate to securable artifacts (pages and task flows). An explicit EL expression must be attached to the component to make it logically consistent with its target.

  • The test-all role is just a means of not breaking the application when ADF Security is enabled. Therefore, it should never be deployed, since it grants access to the application for non-authenticated users.

Related Links

The following document provides additional information about Oracle Fusion Middleware topics discussed in this section:

  • For information about ADF application artifacts, see the Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework guide, in the Oracle Fusion Middleware Online Documentation Library.

52.4 Learning More About Function Security in Oracle Fusion Applications

The following documents within the Oracle Fusion Applications Online Documentation Library provide details about the supporting tasks of the Oracle Fusion Applications security administrator.

  • For information about how the security administrator creates application roles using Oracle Authorization Policy Manager, see the product-specific security guides.

  • For information about how the security administrator exports the application policy store, see the "Extracting Data from an OID Store to a File" section in the Administrator's Guide.

  • For information about how the security administrator merges the policies using Oracle Authorization Policy Manager, see the "Upgrading Fusion Application Policies" section in the Administrator's Guide.

  • For information about how the security administrator reconciles GUIDs using a WLST command, see the "Reconciling GUIDs" section in the Administrator's Guide.

Related Links

The following documents provide additional information about Oracle Fusion Middleware topics discussed in this chapter:

  • For information about OPSS (Oracle Platform Security Services) and application roles, see the "Understanding Security Concepts" part in the Oracle Fusion Middleware Applications Security Guide, in the Oracle Fusion Middleware Online Documentation Library.

  • For information about ADF application artifacts, see the Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework guide, in the Oracle Fusion Middleware Online Documentation Library.

  • For details about creating test users, see the Enabling ADF Security in a Fusion Web Application section of the Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework guide , in the Oracle Fusion Middleware Online Documentation Library.

  • For details about using EL utility methods to render UI components based on user roles, see the "Enabling ADF Security in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework, in the Oracle Fusion Middleware Online Documentation Library.