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;
    }