Page Security

参见开发文档

Overview

This document describes how to build applications that grant selected access to individual pages.

Security Example

To put the various aspects of page security in context, this document uses the following example application to illustrate the steps that you need to take in your applications. It is the same example that we used in Chapter 3: Menus and Page Security with one additional special page (the Benefits Registration Page).

Page	Description	Benefits Manager Access?	Employee Access?
Benefits Registration Page	User login page to access the benefits application. This page also allows a user to register himself.	Yes	Yes
Administer Benefits	View, update, approve and discontinue benefits.	Yes	No
Create Benefit	Create a new benefit.	Yes	No
My Benefits	View current benefit selections and make new selections as appropriate. This page can be accessed from the "Workflow Notifications Page". This page has a "Create" button to launch the "Create Benefit" page.	Yes	Yes
Update Beneficiaries	Update designated beneficiaries.	Yes	Yes

Contents

• Step 1: Create the Navigation Menu
• Step 2: Create Permissions
  • Permissions to secure Component Access
    • Case: Page supports auto responsibility setting 
    • Case: Shared/reusable page that needs a specific responsibility context
• Step 3: Create Grantees or Roles
• Step 4: Create Permission Sets
• Step 5: Create Grants
• Step 6: Extract Seed Data

Prerequisite Reading

Please read the following before proceeding:

• Chapter 3: Menus and Page Security
• Chapter 4: Tabs / Navigation
• Chapter 4: Component-Level Function Security (Dynamic User Interface)

Step 1: Create Navigation Menu

As described in Chapter 3: Menus and Page Security and Chapter 4: Tabs / Navigation, you should begin with a navigation menu including all the pages that anyone could access from your application's menu. In our example, we would create a function for each of the five pages described above, and add them to tabs, and then the Home Page top-level menu.

Tip: The advantage of having just one navigation menu is that there is just one file to ship, patch and upgrade when the navigation within your application changes and/or you add more pages.

Note that the Grant Flag for all of the functions should be unchecked (or set to N). One of the primary goals of the Oracle E-Business Suite security model is to separate navigation from security. And as you notice, the above navigation menu just defines the navigation or hierarchy for your application. To ensure the right authorization for your pages, you would then proceed with steps outlined in this document.

Note: Previously, a navigation menu's function Grant Flags were checked (or set to Y).These functions could then be accessed only by those responsibilities that had access to the navigation menu.

Step 2: Create Permissions

Just like the Navigation functions, permissions are FND form functions, but in this context, they are used exclusively for application security.  Permissions created for an application fall under the following categories:

• All navigation functions used in your navigation menu -- you can reuse the functions that you created for your navigation menu as permissions.

• Permissions to secure component access -- all your UI components including the page itself can be secured using permissions.

Securing Page Access

You should use the following rules to set permissions to secure your pages:

• Rule 1: If a page can be accessed from a menu, then use the navigation function of that page to set permissions. This permission is required to identify if your page is accessible from the menu.

  In our example, we can use the Navigation Functions that we created for the five pages above as permissions. There is no need to create additional permissions.

  Note that you do not need to specify a navigation function or permission for every page in your application. You should specify a navigation function only if is a part of your navigation menu.

• Rule 2: If a restricted page can be accessed from another page using a link or a button, then associate a permission with the Rendered property of the link or button to hide the link or button from the appropriate users.  Create a permission with a name that describes the rule you want to implement.

  In our example, the Create button on the My Benefits page should be displayed only to managers. So, create a permission MANAGER_RENDERED_ONLY for this purpose. We will learn about how to associate this permission with the appropriate grants in the subsequent steps. Note that showing a restricted access message on the Create Benefits page when a non-manager selects the Create button is an inappropriate design. You should instead secure the entry points to the restricted page. 

• Rule 3: If you want to switch or set responsibility seamlessly

  To secure your page access, you should set the function SPEL expression on the Rendered property of your pageLayout region (see Chapter 4: Component-Level Function Security for information about how to do this). Previously, you would do this using the Function Name property on your pageLayout region.

  You should do this if your page falls under one of the cases below:

  Note: GUEST is a special seeded user in the Oracle E-Business Suite Users form.

  In our example, the Benefits Registration Page is an example of a Guest user page. To create a Guest user page:

  Step 1: Set the Security Mode property of your page to Self secured.

  Step 2: Implement the validateParameters() method in your controllers to protect the integrity of the URL.

  Tip: Note that the above two steps are required because your page should exist outside a user's session, and is therefore "bookmarkable".

  Step 3: Set a permission on the rendered attribute of your page layout region using a function security SPEL expression.

  ${oa.FunctionSecurity.BENEFITS_GUEST}Rendered

  The OA Framework requires no authentication and authorization to run a page that is secured using a GUEST user-granted permission.

  Note: Although a GLOBAL-granted permission would seem logical to use, it actually is not appropriate in this case. All users except the GUEST user have access to pages that have a GLOBAL grant. In addition, GLOBAL users must first log in and be authenticated in order to access those globally-granted pages.

  Case 2: Page Supports Automatic Responsibility Setting

The OA Framework requires a responsibility context to be set while running your page, unless it is globally granted. A responsibility context is established when you launch your page after picking a responsibility from the E-Business Home page.

In order to set a responsibility, you should associate a permission (function name) with the Rendered property of your pageLayout region using a SPEL expression that allows the OA Framework to establish the responsibility context automatically. The OA Framework will try to establish your responsibility context using the following rules:

• If the permission is associated with just one of your responsibilities, then that is set as your responsibility context.
• If the permission is associated with more than one of your responsibilities, then the OA Framework picks the responsibility that is associated with the same organization as your current organization to display the page. If a match is not found, or if an organization is not available, then the OA Framework chooses your first responsibility associated with the permission.

  You have a responsibility context switcher on the page to switch to another responsibility (associated with the permission) if you like.

• If the permission is not associated with any of your responsibilities, then the OA Framework prohibits you from accessing the page.
• As we stated earlier, if the permission is associated with a GUEST user grant, then the OA Framework requires no responsibility context. In our example, Benefits Registration Page is granted to the GUEST user. So, you can display that page without picking a responsibility.
• If your page has no permission set on its rendered flag, then the OA Framework displays a responsibility context switcher of all your responsibilities and then picks the first responsibility to display the page.

  You can use the responsibility context switcher to switch to another responsibility if you like.

  Tip: If your page is bookmarkable then it most likely falls either under Case 1 or Case 2 or both, unless you want to prompt the user to login and/or choose a responsibility.

Case 3 : Shared/Reusable Page that Needs a Specific Responsibility Context

This is an extension of Case 2. If your page is used in a cross application flow where each application has its own security context,  then you should secure your page with a permission. The OA Framework uses this permission to identify your responsibility required for rendering the page, and makes a responsibility switch if necessary.

In our example, the My Benefits page can be launched from the Workflow Notifications Page. Let's assume that the Workflow page needs a Workflow responsibility and the My Benefits page needs a Benefits responsibility. When you navigate to the Benefits page from the Workflow page, you want to switch to the workflow responsibility automatically without prompting the user.

You can do so by associating a permission with the rendered attribute My Benefits page. As we discussed in Case 2 above, the OA Framework uses this permission to set or to switch to the Benefits responsibility automatically.  

You should also handle the case where a user can revisit the Workflow page from the Benefits page. Since the workflow page needs a Workflow responsibility, you should set a permission on its rendered attribute as well. This permission will then be used to switch to the Workflow responsibility automatically.

Step 3: Create Grantees or Roles

Previously, a responsibility was the primary mechanism for grouping users into role-based sets. You would then assign menus to responsibilities, and create security rules by excluding individual menu functions from your responsibility. At runtime, the current responsibility, organization and security group together comprised the security context.

The concept of responsibility has been expanded to a more generic role. Users can belong to one or more roles. All users assigned to a particular responsibility are also assigned to a corresponding role. Security rules are based on permission grants instead of function exclusion rules. At runtime, these grants are evaluated for the current security context, which now includes roles (also known as a "grantee") in addition to responsibility, organization and security group.

A granteecan either be a user (FND_USER), or auser group(also known as role), or "global".  User identities are created in FND_USERS, and should map one-to-one with individual humans or systems. Users can belong to groups or roles that are formed by grouping organizational or position relationships modeled in products such as Human Resources. Roles are defined in WF_ROLES, and in future can map to user groups in a customer's LDAP system. Although its membership is not explicitly populated, there is a Global group which includes "everyone". Ideally, users would belong to predefined Workflow roles, so you don't have to group them again.

Note: The GLOBAL role actually includes everyone except the GUEST user.

You need three user roles for our example above: one that groups all managers into a manager role, one that represents the GUEST user and a third that groups all employees. Since all employees includes everyone, you can use a GLOBAL role for this purpose.

Alternately, you can create a responsibility that is assigned to all managers, and use that for your grants setup.

 

Note: When using a Proxy User, there is a change in the UserInfo Named Child.
For the proxy user we add a StackLayout region as a userInfo named child of the PageLayout.
If the product team has added any other region as an userInfo named child, then we add that region under the StackLayout region.
Because of this change, for a user with proxy privilege, the call to the api getUserInfo() on the OAPageLayoutBean will return a OAStackLayoutBean instead of the region which the Product team added.
Hence, product teams should modify their code to reflect this change.
i.e., for a user with proxy privileges, the getUserInfo() api will return a OAStackLayoutBean and the userInfo region added by the product team will be an indexed child of the OAStackLayoutBean.

Step 4: Create Permission Sets

Permission Sets are implemented as menus, but they are exist solely to group a flat list of permissions into sets for easy access granting.

Ideally, you should group permissions that are required by a role into one or more permission sets.

You need three permission sets for our example:

• A Manager permission set for all the tasks to which only managers should have access. This includes:
  • The navigation functions Administer Benefits, and Create Benefit.
  • The MANAGER_RENDERED_ONLY permission that we created in Step 4 associated with the Create Button. 

• A GLOBAL permission set with permissions that are accessible by everyone. This includes:

  • The navigation functions Benefits Registration Page, My Benefits and Update Beneficiaries.

• A GUEST permission set for the publically accessible page

Here are the step by step instructions to create the manager permission set:

Step 1: Start Oracle E-Business Suite Release 12 in your development environment and log in as SYSADMIN/SYSADMIN (or specify the corresponding username/password for your environment). .

Step 2: Select either the System Administrator or the Application Developer responsibility.

Step 3: Select the Navigator to choose the Menus form from the Application > Menus menu (or, it might also be in the Top 10 list). As described above, permission sets are flat menus.

Step 4: To create a new permission set, simply start entering values in the blank fields. Set values for the following properties. Note that you can accept all the other default values.

• Menu - this is the unique developer key for your permission set. In our example, we'll call this the BENEFITS_MANAGER_PS (the product short code followed by a descriptive name for the permission set).

• User Menu Name - this is the unique, user-friendly version of the permission set that displays when administering. In our example, we'll call this Benefits Manager Permission Set.

• Description - provides a short description of the permission set.

• Menu Type - You can choose any menu type for permission sets, but for convenience and easy access, we recommend that you use the SECURITY menu type.
  

Step 5: Add all permissions for this permission set as individual menu entries. Note that since the same form is used for creating a navigation menu (as we saw in Chapter 4: Tabs/Navigation) and a permission set, there are some UI- or navigation-only properties for menus that are not applicable to permission sets. This includes sequence and prompt. You can enter any value for these two properties. The properties that should have valid values are:

• Submenu or Function - the permission name to be used in the permission set. In our example, MANAGER_RENDERED_ONLY is one of the permissions that you should specify here.

• Description - a brief description of the permission.

• Grant Flag - as stated in the Navigation Menu section, this should be unchecked. When unchecked, the OA Framework will evaluate your permission set based on its grants and your runtime security context. We will create the appropriate Grants in the next step.

Step 6 : To save your work, select File > Save from the menu.

Step 5: Create Grants 

A Grant defines security rules that allows only certain users of your system access to specific functions or pages within your application. A grant gives a grantee access to the permission sets described above. In simple terms, grants link your grantees to your permission sets.

You need three grants for the example above:

• A Manager Grant to associate the manager permission set with the manager role.
• An Employee Grant that is associated with your Global permission set with a global grantee.
• A GUEST Grant that is associated with your GUEST permission set with a GUEST grantee.

In addition to specifying a grantee, you couldalso restrict your grant further with additional security context. This includes the current user's responsibility, organization and security group. So, for example, to restrict the manager grant to a specific organization, you can associate an organization context with the grant. 

Note that grants, just like responsibilities, are mostly created at the customer site. You create the permission sets, and the customer then creates the WF roles and creates grants to associate these roles with your permission sets.

Instead of granting the manager permission set to the manager role, you can grant it to a global grantee. You can then restrict it to managers alone by associating a security context with the responsibility to which only managers have access. However note that the OA Framework recommends the use of role based grants instead of responsibilities.

At runtime, a user is granted access to a page if the permission associated with the page is granted access to the current user's security context. The user's security context as described above includes the user's role, responsibility, organization and security group.

To create the Manager grant, we:

Step 1: Login to your development database and choose the Functional Administrator responsibility. This takes you to the Applications Administration Home Page.

Step 2 : Navigate to the Grants sub tab under Security tab. Select the Create Function Grant button. Note that since the grant that we are creating is associated with a permission, it is also called a Functional Grant. You can use the page navigation buttons to complete the steps below.

Step 3 : Choose the grantee for your grant. You have the following options:

• You should choose the All Users option to create a global grant that is accessible by everyone.

  Tip: You should choose this option for the Employee Grant.

• You should choose the Group of Users option to create a grant that is associated with a specific role.

  In our example, you should choose this option, and pick the manager role that you created from the LOV.

• You should choose the Single User option to create a grant that is associated with just one user.

  Tip: You should choose this option for the GUEST Grant.

Step 4: Associate your grantee with the permission set by picking it from the LOV. In our example, you should pick the Benefits Manager Permission Set that you just created.

Step 5: Pick any additional security context to associate with this grant. In our example, as we stated above, to restrict the manager grant to a specific organization, pick the organization from the LOV.

Step 6: Pick the start date to activate your grant and optionally specify an end date.

Step 7: Select Finish to create your grant.

The Grants model is a very versatile model for modeling any security requirement of your application. The above steps to create your security rules by using roles, permission sets and grants is just one aspect of what it offers. You can find more information on its full list of features from the Oracle E-Business Suite Security Guide.

Step 6: Extract Security Seed Data

To deploy your security data to a different database (or to ship it if you are an Oracle E-Business Suite internal developer) you must extract your seed data using the generic Oracle E-Business Suite loader FNDLOAD. You can find more information on FNDLOAD from the Oracle E-Business Suite Security Guide.

The syntax you use for FNDLOAD is

FNDLOAD logon 0 Y mode configfile datafile [ entity [ param ... ] ]

where
logon is username/password[@connect]
mode is either UPLOAD or DOWNLOAD
configfile is the configuration file
datafile is the data file
entity is an entity name, or - to specify all values in an upload
param is a NAME=VALUE string used for parameter substitution

The following table describes which configuration file to use for the entities you want to extract. The configuration files are published in $FND_TOP/patch/115/import.

Entity Name	Description	Configuration File
FND_RESPONSIBILITY	To extract the responsibilities that you created with your navigation menu.	afscursp.lct
MENU	Extracting a menu will also extract any submenus or functions associated with it. In our example, use this to extract the navigation menu.	afsload.lct
GRANT	Extracting the grant will also extract its permission set and its permissions. In our example, use this to extract the manager and the employee grants.	afsload.lct.

For example, to extract Grants seed data, you would specify:

FNDLOAD [username/password]@seed115 0 Y DOWNLOAD 
  $FND_TOP/patch/115/import/afsload.lct somefile.ldt
  GRANT GNT_MENU_NAME=the_menu_under_which_grants_exist

---

 Step 1: Set the Security Mode property of your page to Self secured. 

Step 2: Implement the validateParameters() method in your controllers to protect the integrity of the URL.  

 

     public String[] validateParameters(OAPageContext pageContext, 
                                       java.util.Vector alreadyValidatedParameters) {
        super.validateParameters(pageContext, alreadyValidatedParameters);
        String[] list = { "operate","paymentRequestId","isformOutSideSystem","UserName"};
        return list;
    }