19.5 Providing Security Through Authorization

Authorization is a broad term for controlling access to resources based on user privileges. While conditions control the rendering and processing of specific page controls or components, authorization schemes control user access to specific controls or components.

19.5.1 How Authorization Schemes Work

An authorization scheme extends the security of your application's authentication scheme. You can specify an authorization scheme for an entire application, page, or specific control such as a region, item, or button. For example, you could use an authorization scheme to selectively determine which tabs, regions, or navigation bars a user sees.

An authorization scheme either succeeds or fails. Common authorization scheme types include Exists, Not Exists SQL Queries, and PL/SQL Function Returning Boolean. If a component or control level authorization scheme succeeds, the user can view the component or control. If it fails, the user cannot view the component or control. If an application or page-level authorization scheme fails, then Oracle Application Express displays a previously defined message.

When you define an authorization scheme, you give it a unique name. Once defined, you can attach it to any component or control in your application. To attach an authorization scheme to a component or control in your application, simply navigate to the appropriate attributes page and select an authorization scheme from the Authorization Scheme list.

19.5.2 Creating and Editing an Authorization Scheme

This section explains how to create and edit an authorization scheme. Before you can attach an authorization scheme to an application or an application component or control, you must first create it.

19.5.2.1 About Authorization Scheme Types

When you create an authorization scheme you select an authorization scheme type. The authorization scheme type determines how an authorization scheme is applied. Developers can create new authorization type plug-ins to extend this list.

Table 19-1 Authorization Scheme Types

Authorization Scheme Types Description

Exists SQL Query

Enter a query that causes the authorization scheme to pass if it returns at least one row and causes the scheme to fail if it returns no rows

NOT Exists SQL Query

Enter a query that causes the authorization scheme to pass if it returns no rows and causes the scheme to fail if it returns one or more rows

PL/SQL Function Returning Boolean

Enter a function body. If the function returns true, the authorization succeeds.

Item in Expression 1 is NULL

Enter an item name. If the item is null, the authorization succeeds.

Item in Expression1 is NOT NULL

Enter an item name. If the item is not null, the authorization succeeds.

Value of Item in Expression 1 Equals Expression 2

Enter and item name and value.The authorization succeeds if the item's value equals the authorization value.

Value of Item in Expression 1 Does NOT Equal Expression 2

Enter an item name and a value. The authorization succeeds if the item's value is not equal to the authorization value.

Value of Preference in Expression 1 Does NOT Equal Expression 2

Enter an preference name and a value. The authorization succeeds if the preference's value is not equal to the authorization value.

Value of Preference in Expression 1 Equals Expression 2

Enter an preference name and a value. The authorization succeeds if the preference's value equal the authorization value.

Is In Group

Enter a group name. The authorization succeeds if the group is enabled as a dynamic group for the session. See "APEX_AUTHORIZATION.ENABLE_DYNAMIC_GROUPS" in Oracle Application Express API Reference.

If the application uses Application Express Accounts Authentication, this check also includes workspace groups that are granted to the user. If the application uses Database Authentication, this check also includes database roles that are granted to the user.

Is Not In Group

Enter a group name. The authorization succeeds if the group is not enabled as a dynamic group for the session.

19.5.2.2 Creating an Authorization Scheme

To create an authorization scheme:

  1. On the Workspace home page, click the App Builder icon.

  2. Select an application.

  3. On the Application home page, click Shared Components.

    The Shared Components page appears.

  4. Under Security, select Authorization Schemes.

  5. Click Create.

  6. Specify how to create an authorization scheme by selecting one of the following:

    • From Scratch

    • As a Copy of an Existing Authorization Scheme

  7. On Create Authorization Scheme - Details:

    1. Name - Enter an unique name that identifies this authorization scheme.

    2. Scheme Type - Select how this authorization scheme will be applied. See "About Authorization Scheme Types."

    3. Identify error message displayed when scheme violated - Enter error text that displays if the authorization scheme fails (that is, the current user fails the security check).

    4. Validate Authorization Scheme - Authorization schemes are evaluated on first use in a session. Use this option to controls if future uses cause re-evaluations and when a memorized result can be taken instead.

    For more details, see field-level Help.

  8. Click Create Authorization Scheme.

19.5.2.3 Editing Attributes of an Existing Authorization Scheme

To edit attributes of an existing authorization scheme:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. On the Application home page, click Shared Components.

    The Shared Components page appears.

  4. Under Security, select Authorization Schemes.

    The Authorization Schemes page appears. By default, each scheme displays as an icon. You can customize the appearance the page using the Search bar at the top of the page. To learn more, see "About the Search Bar."

  5. Select an authorization scheme.
  6. Edit the appropriate attributes.

    To learn more, see field-level Help. See "Viewing Field-Level Help."

  7. To save your changes, click Apply Changes.

19.5.2.4 Changing the Evaluation Point Attribute

You can control when an authorization scheme is validated using the Evaluation Point, Validate authorization scheme attribute.

To change the authorization scheme evaluation point:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. On the Application home page, click Shared Components.

    The Shared Components page appears.

  4. Under Security, select Authorization Schemes.

    The Authorization Schemes page appears.

    By default, each scheme displays as an icon. You can customize the appearance the page using the Search bar at the top of the page.

  5. Select an authorization scheme.
  6. Scroll down to Evaluation Point and edit the Validate authorization scheme attribute. Options include:
    • Once per session - Evaluate only once and always use the memorized result afterwards.

    • Once per page view - Evaluate once for each request that is processed. Use the memorized result if the authorization scheme is referenced in more than one component on the page.

    • Once per component - Evaluate once for each component that references the authorization scheme, but save the result in the session. Further requests to render or process the scheme use the result that was memorized for the component.

    • Always (No Caching) - The authorization scheme will always be evaluated.

    To learn more, see field-level Help.

  7. To save your changes, click Apply Changes.

Tip:

The default value Once per session is the most efficient. You should choose another value if the authorization check depends on changing session state or other factors that are not consistent over an entire session.

19.5.2.5 About Resetting Authorization Scheme State

If an authorization scheme is validated once for each session, Oracle Application Express caches the validation results in each user's session cache. You can reset a session's authorization scheme state by calling the APEX_AUTHORIZATION.RESET_CACHE API.

See Also:

"APEX_AUTHORIZATION.RESET_CACHE Procedure" in Oracle Application Express API Reference

19.5.3 Attaching an Authorization Scheme to an Application, Page, or Components

Once you have created an authorization scheme you can attach it to an entire application, page, control, or component.

19.5.3.1 Attaching an Authorization Scheme to an Application

To attach an authorization scheme to an application:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. Click the Shared Components icon.

    The Shared Components page appears.

  4. Under Security, click Security Attributes.
  5. Scroll down to Authorization and make a selection from the Authorization Scheme list.
  6. For Run on Public Pages, select Yes or No to specify whether the application-level authorization scheme is checked on public pages (that is, pages that do not require authorization). To learn more, see "Authorization."
  7. To define a new authorization scheme, click Define Authorization Schemes.

19.5.3.2 Attaching an Authorization Scheme to a Page

To attach an authorization scheme to a page:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. Select a page.
  4. To access the Edit Page:
    • Tree view - Under Page Rendering, double-click the page title at the top of the tree.

    • Component view- Under Page, click the page name.

  5. Scroll down to Security and make a selection from the Authorization Scheme list.

19.5.3.3 Attaching an Authorization Scheme to a Control or Component

To attach an authorization scheme to a page component or control:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. Select a page.
  4. Click the name of the component or control to which you want to apply the authorization scheme.
  5. Scroll down to Security and make a selection from the Authorization Scheme list.

19.5.4 Viewing Authorization Reports

You can use the Authorization Scheme Subscription and Authorization Scheme Utilization reports to better manage authorization schemes within your application.

To view authorization scheme reports:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. On the Application home page, click Shared Components.

    The Shared Components page appears.

  4. Under Security, select Authorization Schemes.
  5. Click the appropriate tab at the top of the page:
    • Subscription - Use the Authorization Scheme Subscription report to view details about authorization schemes subscription.

    • By Component - Use the By Component report to view all components within this application which have an associated authorization scheme. For a component to be rendered it must pass authorization schemes placed on the component level, the page level, and at the application level.

    • Utilization - Use the Authorization Scheme Utilization report to view details about authorization schemes utilization.

      To view additional reports indicating which pages having authorization schemes and which do not, select one of the following from the Tasks list:

      • Report Pages With Authorization Schemes

      • Report Pages Without Authorization Schemes

    • History - Use the Authorization Scheme History report to view recent modifications made to Authorization Schemes in this application.