Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 6 (11.1.6)

Part Number E15524-11
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

50 Implementing 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:

50.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:

Note:

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

Function security controls access to securable application artifacts including ADF task flows and top-level web pages backed by ADF page definition files. Users who do not have the required privilege cannot view the task flow. 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 not enter the task flow.

50.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.

Important:

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. You should always add custom application roles to grant access rights. For details about restrictions when working with the file-based policy store, see Section 50.3.7, "What You May Need to Know About Actions That Developers Must Not Perform."

As an security implementation guideline, 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 create for Oracle ADF application artifacts.

After you customize security, you use JDeveloper to add end user identities to the identity store of the exported file for the purpose of 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.

50.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.

To gather background information about function security, refer to these documents:

Table 50-1 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 50-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 Section 50.3.1, "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 Section 50.3.1, "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 Section 50.3.3, "How to Define Resource Grants for OPSS Built-In Roles."

Determine whether the end user associated with a particular role has the right to select create, edit, or delete buttons in the displayed web page.

Do not create a security policy.

Access to user interface components, such as buttons, is not controlled by a security policy, but can be controlled by rendering the button in the user interface based on the end user's role.

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 membership in a particular role.

For more information about rendering components using EL utility methods, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).


50.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.

Table 50-2 lists the file related to Oracle Fusion security that are created for you when you secure your application in JDeveloper. For more information about the security-related files, see the Oracle Fusion Middleware Application Security Guide.

Table 50-2 Oracle Fusion Application Security-Related Files

File Name Location Security Purpose

jazn-data.xml

<JDevAppHome>/src/META-INF

  • Design-time policy store, containing all the function security policies defined for securable Oracle ADF artifacts in the workspace. This file must be generated by a security administrator.

adf-config.xml

<JDevAppHome>/.adf/META-INF

  • Stores the flags that control whether authentication and authorization are supposed to be enforced by runtime Oracle ADF.

  • Specifies the security providers' and OPSS factory's classes names.

weblogic-application.xml

<JDevAppHome>/src/META-INF

  • Defines the listeners used by Oracle WebLogic Server to interact with the application.

  • Controls the application stripe to which policies are migrated.

jps-config.xml

<JDevAppHome>/src/META-INF

  • Stores definitions of OPSS service providers and services instances.

  • Stores definitions of OPSS contexts for the current workspace. An OPSS context contains pointers to the service instances used by that application.

web.xml

<JDevAppHome>/UserInterface/
public-html/WEB-INF

  • Stores definitions and mappings for servlets and filters used by ADF Security.

  • Includes security constraints for any custom servlets.

  • Defines the OPPS JpsFilter servlet filter to set up the OPSS policy provider. The filter defines settings that indicate that your servlet has special privileges. It is important that the JpsFilter definition be the first filter definition in the web.xml file.

  • Adds the ADF adfAuthentication servlet definition to require the user to log in the first time the application is accessed.

  • Maps the adfAuthentication servlet to a security constraint that triggers user authentication dynamically.

  • Defines the ADFBindingFilter servlet filter which instantiates the ADFContext object, which includes context information about the session, including the security context.

  • Defines login configuration for the application.

  • Define the Java EE logical valid-users role, which is used to trigger the security constraint that enables dynamic authentication.

  • Contains the runtime application stripe, which must match the configuration in the weblogic-application.xml file.

weblogic.xml

<JDevAppHome>/UserInterface/
public-html/WEB-INF

  • Maps the Java EE valid-users role (created by the Configure ADF Security wizard) to the implicit users group defined by Oracle WebLogic Server.

cwallet.sso

<JDevAppHome>/src/META-INF

  • Stores external system's password in encrypted format.


50.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.

To implement function security:

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

    For information about application roles, see the "Understanding Security Concepts" part of the Oracle Fusion Middleware Application Security Guide.

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

    If a security manager 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. For details about how the security administrator creates application roles using Oracle Authorization Policy Manager, see the "Managing Policies and Policy Objects" chapter in the Oracle Fusion Middleware Oracle Authorization Policy Manager Administrator's Guide (Oracle Fusion Applications Edition).

    If you do not ask the security manager 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 how the security manager exports the application policy store, see the "Securing Oracle Fusion Applications" chapter in the Oracle Fusion Applications Administrator's Guide.

  4. 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.

  5. 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 Section 50.3.1, "How to Create Entitlement Grants for Custom Application Roles."

  6. 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 Section 50.3.3, "How to Define Resource Grants for OPSS Built-In Roles."

  7. 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 Section 50.3.5, "How to Enforce Authorization for Securable ADF Artifacts."

  8. Determine which user interface components you want to associate with user entitlements, and enter 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). For details about using EL utility methods, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

  9. 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 Section 50.3.6, "How to Enable Authentication and Test the Application in JDeveloper."

  10. 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.

    For information about how the security administrator merges the policies using Oracle Authorization Policy Manager, see the "Upgrading Oracle Fusion Applications Policies" chapter in the Oracle Fusion Middleware Oracle Authorization Policy Manager Administrator's Guide (Oracle Fusion Applications Edition).

  11. 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 "Managing Policies and Policy Objects" chapter in the Oracle Fusion Middleware Oracle Authorization Policy Manager Administrator's Guide (Oracle Fusion Applications Edition).

  12. 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. For information about how the security administrator reconciles GUIDs using a WLST command, see the "Securing Oracle Fusion Applications" chapter in the Oracle Fusion Applications Administrator's Guide.

  13. 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 Section 50.3.8, "What You May Need to Know About Testing."

50.3 Adding 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.

Best Practice:

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, the ADF artifacts that you may secure are:

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 Section 50.3.9, "What You May Need to Know About Security Best Practices."

To add function security to the application:

  1. Determine which ADF artifacts should be secured and grant entitlement privileges to custom application roles to define the duties of end users.

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

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

  4. Determine which user interface components you want to associate with user entitlements, and enter 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). For details about using EL utility methods, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

  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.

50.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 should be used only to define publicly accessible application artifacts, as described in Section 50.3.3, "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.

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 Permission 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.

Table 50-3 lists the resource types displayed in JDeveloper and identifies the associated resource and actions.

Table 50-3 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 Chapter 51, "Securing Web Services Use Cases."

ADF Method Resource

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

Webservice Resource

Defines invoke actions on Fusion Web services. For more details about securing Web services, see Section 51.5, "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 have an understanding of ADF Security. For more information, see the "Understanding Users and Roles" chapter in the Oracle Fusion Middleware Application Security Guide.

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

You will need to complete these tasks:

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.

    Figure 50-1 shows the overview editor with the View action selected for the task flow and added to MyEntitlement.

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

    Entitlement grant in the policy editor
  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.

50.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 Example 50-1 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 50-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>

50.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 in the Oracle Fusion Middleware Application Security Guide.

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

You will need to complete this task:

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.

    Figure 50-2 shows the overview editor with the View action selected for the task flow and granted to authenticated-role.

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

    Resource grant to built-in role in policy editor

50.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.

Example 50-2 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 50-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>

50.3.5 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.

Once 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 in order 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 Section 50.3.1, "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 Section 50.3.3, "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 in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

To enforce authorization:

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

  2. Update the wizard pages as follows:

    ADF Security: Select ADF Authentication and Authorization (default), as shown in Figure 50-3. Click Next.

    Figure 50-3 Configure ADF Security — ADF Security Model Page

    Configure ADF Security - Enable ADF Security page

    Authentication Type: Select HTTP Basic Authentication (default). Click Next.

    Automatic Policy Grant: Select No Automatic Grants (default), as shown in Figure 50-4. Click Next.

    Figure 50-4 Configure ADF Security — Automatic Policy Grants Page

    Configure ADF Security - Auto Policy Grants page

    Note:

    When you select No Automatic Grants, you must define explicit grants that are specific to your application. The test-all application role provides a convenient way to run and test application resources without the restricted access that ADF authorization enforces. For more information about the test-all role, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

    Authenticated Welcome: Do not make a selection. (The Redirect Upon Successful Authentication option should not be selected). Click Next.

    Summary: Review your selections. Click Finish.

50.3.6 How to Enable Authentication and Test the Application in JDeveloper

Authentication is enabled when you run the Configure ADF Security wizard, as described in Section 50.3.5, "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).

For details about creating test users, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

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.

50.3.7 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 Oracle Fusion Applications Security Guide.

50.3.8 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.

  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 Figure 50-5.

Figure 50-5 Application Deployment Properties Related to Security

Application Properties dialog - Deployment page

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. For details about reconciling GUIDs in the data security repository, see the "Securing Oracle Fusion Applications" chapter in the Oracle Fusion Applications Administrator's Guide.

50.3.9 What You May Need to Know About Security Best Practices

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 once 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 single 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 once ADF Security is enabled. Therefore, it should never be deployed, since it grants access to the application for non-authenticated users.