11 How to Build an Access Control Page

You can control access to an application, individual pages, or page components by creating an Access Control Administration page. The page contains a list of application modes and an Access Control List.

This tutorial explains how to build an Access Control Administration page and then restrict access to an application so that only privileged users can perform specific functions.

This section contains the following topics:

For additional examples on this topic, please visit the following Oracle by Examples (OBEs):

How Access Control Administration Works

You create an access control list by running the Access Control Wizard to create an Access Control Administration page. This page contains a list of application modes and an Access Control List. Once you create the Access Control Administration page, you:

  1. Run the Access Control Administration page.

  2. Select an application mode:

    • Full access to all, access control list not used.

    • Restricted access. Only users defined in the access control list are allowed.

    • Public read only. Edit and administrative privileges controlled by access control list.

    • Administrative access only.

  3. Add users to the Access Control List.

In addition to creating the Access Control Administration page, the Access Control Wizard also creates:

  • two tables within the application's default schema to manage access control

  • the authorization schemes that correspond to the application mode list options

  • the privileges available in the Access Control List

You can control access to a specific page or page component by selecting one of these authorization schemes on the page or component attributes pages. Once you create an Access Control, you can customize the page, tables and values to suit the specific needs of your application.

Creating an Application

First, you need to create an application based on employee data in a spreadsheet.

Topics in this section include:

Download Spreadsheet Data

Download the following *.csv file to you local machine:

  1. In your Web browser go to:

    http://www.oracle.com/technology/products/database/application_express/packaged_apps/acl_employees.zip

  2. Download the acl_employees.zip file to your computer.

  3. Unzip and extract the acl_employees.csv file:

    • Microsoft Windows - Double-click the acl_employees.zip file

    • UNIX or Linux - Enter the following command:

      $ unzip acl_employees.zip

Create an Application Based on Spreadsheet Data

To create a new application based on spreadsheet data:

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

    The Application Builder home page appears.

  2. Click Create.

  3. Select Create from Spreadsheet and click Next.

  4. Select Upload file, comma separated (*.csv) or tab delimited and click Next.

  5. For Load Method:

    1. Select Upload file, comma separated (*.csv) or tab delimited.

    2. Click Next.

  6. For Data:

    1. Text File - Click Browse and navigate to the acl_employees.csv file.

    2. Accept the remaining defaults and click Next.

  7. For Table Properties:

    1. Schema - Select the appropriate schema.

    2. Table Name - Enter ACL_EMPLOYEES.

    3. Accept the remaining defaults and click Next.

  8. For User Interface Defaults:

    1. Singular Name - Enter Employee.

    2. Plural Names - Enter Employees.

    3. Click Next.

  9. For Summary Page:

    1. Summary by Column - Select DEPARTMENT_ID and click Next.

    2. Aggregate by Column - Do not make a selection and click Next.

  10. For Application Options, accept the defaults and click Next.

  11. For User Interface, select Theme 2 and click Next.

    A theme is collection of templates that define the layout and style of an application. You can change a theme at any time.

  12. Click Create.

    The Application home page appears.

Run the Application

To run the application:

  1. Click the Run Application icon as shown in Figure 11-1.

    Figure 11-1 Run Application Icon

    Description of Figure 11-1 follows
    Description of "Figure 11-1 Run Application Icon"

  2. If prompted to enter a user name and password, enter your workspace user name and password and click Login. See "About Application Authentication".

    The report appears as shown in Figure 11-2.

    Figure 11-2 ACL_EMPLOYEES Application

    Description of Figure 11-2 follows
    Description of "Figure 11-2 ACL_EMPLOYEES Application"

    The ACL_EMPLOYEES application enables you to view and update employee data. To update a specific record, click the Edit icon in the far left column. Clicking the Analyze tab provides you with access to both a visual and tabular breakdown of the number of employees in each department.

Creating an Access Control Administration Page

Next, you need to secure your application so that only privileged users can perform certain operations. When you implement access control on an Oracle Application Express application, the best approach is to use an authorization scheme defined at the application level. The first step is to create an access control page by running the Access Control Page Wizard.

Topics in this section include:

Create an Access Control Page

To create an access control page:

  1. Click Create on the Developer toolbar.

  2. Select New page and click Next.

  3. For Page, select Access Control and click Next.

    The Access Control Wizard appears.

  4. In Administration Page Number, enter 8 and click Next.

  5. For Tabs:

    1. Tab Options - Select Use an existing tab set and create a new tab within the existing tab set.

    2. Tab Set - Select TS1 (Employees, Analyze).

    3. Tab Set Label - Enter Administration.

    4. Click Next.

  6. Review the confirmation page and click Finish.

    A Success page appears.

View the Page

To run the page:

  1. Click Run Page.

    A new page appears as shown in Figure 11-3.

    Figure 11-3 Access Control Administration Page

    Description of Figure 11-3 follows
    Description of "Figure 11-3 Access Control Administration Page"

    Notice the page is divided into two regions: Application Administration and Access Control List. Also note that the default Application Mode is Full Access.

  2. Under Application Mode, select Restricted access. Only users defined in the access control list are allowed.

  3. Click Set Application Mode.

Add Users to the Access Control List

Next, add three users to the Access Control List:

  • Luis Popp (LPOPP) will have View privileges.

  • Adam Fripp (AFRIPP) will have Edit privileges.

  • John Chen (JCHEN) will have Administrator privileges.

To add users to the Access Control List:

  1. Under Access Control List, click Add User.

    A new row appears.

  2. Enter the first user:

    1. Username - Enter LPOPP.

    2. Privilege - Select View.

    3. Click Apply Changes.

    4. Click Add User to add a blank row where you can enter the first user.

  3. Enter the next user:

    1. Username - Enter AFRIPP.

    2. Privilege - Select Edit.

    3. Click Apply Changes.

    4. Click Add User to add a blank row where you can enter the next user.

  4. Enter the next user:

    1. Username - Enter JCHEN.

    2. Privilege - Select Administrator.

    3. Click Apply Changes.

  5. Click Application on the Developer toolbar.

    The Application home page appears.

Creating an Authentication Function

Next, you need to make employees in the ACL_EMPLOYEES table the users of the application. To accomplish this, you create a simple authentication function in the current authentication scheme. Note that the function checks for the userid and its associated last name as a password.

To create the authentication function:

  1. On the Application Builder home page, click the Home breadcrumb link.

    The the Workspace home page appears.

  2. Click SQL Workshop and then SQL Commands.

  3. In the SQL editor pane:

    1. Enter the following code:

      CREATE OR REPLACE FUNCTION acl_custom_auth (
    p_username IN VARCHAR2,
    p_password IN VARCHAR2)
RETURN BOOLEAN IS
BEGIN
  FOR c1 IN (SELECT 1 
              FROM acl_employees
             WHERE upper(userid) = upper(p_username)
               AND upper(last_name) = upper(p_password))
  LOOP
    RETURN TRUE;
  END LOOP;
  RETURN FALSE;
END;
/

    2. Click Run.

  4. Click the Home breadcrumb link.

    The Workspace home page appears.

Updating the Current Authentication Scheme

Next, you need to update the current authentication scheme to use the new function.

To update the current authentication scheme.

  1. Click Application Builder and then click ACL Employees.

    The Application home page appears.

  2. Click Shared Components.

  3. Under Security, click Authentication Schemes.

    The Authentication Schemes page appears.

  4. Click the Application Express - Current icon.

  5. Scroll down to Login Processing.

  6. In Authentication Function, replace -BUILTIN- with the following:

    return acl_custom_auth

  7. Scroll back to the top of the page and click Apply Changes.

Applying Authorization Schemes to Components

Next you need to associate the authorization scheme with the appropriate application components. As you may recall, you previously added three users to the Access Control List:

  • LPOPP had View privileges.

  • AFRIPP had Edit privileges

  • JCHEN had Administrator privileges

In this exercise, you associate the View, Edit, and Administrator privileges with specific application components to control which users are allowed to perform what actions.

Topics in this section include:

Associate an Authorization Scheme with the Application

First, you need to specify that users will only be able to access the application if they have View privileges. To accomplish this, you associate the access control - view authorization scheme with the application.

To associate an authorization scheme with your application:

  1. Click the Application ID breadcrumb link.

    The Application home page appears.

  2. Click Shared Components.

  3. Under Application, click Definition.

  4. Click the Security tab.

  5. Scroll down to Authorization.

  6. From Authorization Scheme, select access control - view.

  7. Click Apply Changes at the top of the page.

Associate Edit Privileges with the ID Column

For this exercise, only users with at least Edit privileges should be able to edit or delete data. To accomplish this, you associate the access control - edit authorization scheme with the ID column. This hides the Edit icon on page 1 for users with View privileges, but displays it for users with Edit or Administrator privileges.

To associate edit privileges with the ID column:

  1. Click the Application ID breadcrumb link.

    The Application home page appears.

  2. Click 1 - Report Page.

    The Page Definition for page 1 appears.

  3. Under Regions, click the Report link.

    The Report Attributes page appears.

  4. Click the Edit icon for ID. The Edit icon resembles a small page with a pencil on top of it.

    The Column Attributes page appears.

  5. Scroll down to Authorization.

  6. From Authorization Scheme, select access control - edit.

  7. Click Apply Changes at the top of the page.

Associate Edit Privileges with the Create Button

Next, associate the access control - edit authorization scheme to the Create button. This will hide the Edit icon for unprivileged users.

To associate edit privileges with the Create button:

  1. Go to the Page Definition for Page 1. Click the Page 1 breadcrumb link.

    The Page Definition for page 1 appears.

  2. Under Buttons, click the Create link (not the icon).

  3. Scroll down to Authorization.

  4. From Authorization Scheme, select access control - edit.

  5. Click Apply Changes at the top of the page.

    The Page Definition for Page 1 appears.

Associate Edit Privileges with Page 2

Next, associate the access control - edit authorization scheme with page 2.

To specify an authorization scheme for page 2:

  1. Go to page 2. In the Page field enter 2 and click Go.

    The Page Definition for page 2 appears.

  2. Under Page, click the Edit page attributes icon.

  3. Scroll down to Security.

  4. From Authorization Scheme, select access control - edit.

  5. Click Apply Changes at the top of the page.

Restrict Access to Page 8

Lastly, you need to restrict access to page 8, Access Control Administration. To accomplish this, you specify the access control - administrator authorization scheme with all of page 8 and with the Administration tab.

Specify an Authorization Scheme for Page 8

To specify an authorization scheme for page 8:

  1. Go to page 8. In the Page field, enter 8 and click Go.

    The Page Definition for page 8 appears.

  2. Under Page, click the Edit page attributes icon.

  3. Scroll down to Security.

  4. From Authorization Scheme, select access control - administrator.

  5. Click Apply Changes at the top of the page.

    The Page Definition for page 8 appears.

Specify an Authorization Scheme for the Administration Tab

To specify an authorization scheme for page 8:

  1. Under Tabs, click the Administration link.

  2. Scroll down to Authorization.

  3. From Authorization Scheme, select access control - administrator.

  4. Click Apply Changes at the top of the page.

    The Page Definition for page 8 appears.

Testing the Application

At the beginning of this tutorial, you added three users to the Access Control List:

  • Luis Popp (LPOPP) has View privileges

  • Adam Fripp (AFRIPP) has Edit privileges

  • John Chen (JCHEN) has Administrator privileges

Next, test your application by logging in as each of these users.

Topics in this section include:

Log In with View Privileges

Luis Popp (LPOPP) has View privileges.

To log in as Luis Popp:

  1. Click the Run Page icon in the upper right corner.

  2. When prompted, specify the following:

    1. Username - LPOPP.

    2. Password - Popp.

    3. Click Login.

    The Employees Report page appears as shown in Figure 11-4.

    Figure 11-4 Employees Report with View Privileges

    Description of Figure 11-4 follows
    Description of "Figure 11-4 Employees Report with View Privileges"

    Note that the Edit icon and the Administration tab no longer appear.

  3. Click Logout in the upper right corner.

Log In with Edit Privileges

Adam Fripp (AFRIPP) has Edit privileges.

To log in as Adam Fripp:

  1. When prompted, specify the following:

    1. Username - AFRIPP.

    2. Password - Fripp.

    3. Click Login.

    The Employees Report page appears as shown in Figure 11-5.

    Figure 11-5 Employees Report with Edit Privileges

    Description of Figure 11-5 follows
    Description of "Figure 11-5 Employees Report with Edit Privileges"

    Note that the Edit icon now appears to the left of the Employee Id column, but the Administration tab still does not appear.

  2. Click Logout in the upper right corner.

Log In with Administrator Privileges

John Chen (JCHEN) has Administrator privileges.

To log in as John Chen:

  1. When prompted, specify the following:

    1. Username - JCHEN

    2. Password - Chen

    3. Click Login.

    The Employees Report page appears as shown in Figure 11-6.

    Figure 11-6 Employees Report with Administrator Privileges

    Description of Figure 11-6 follows
    Description of "Figure 11-6 Employees Report with Administrator Privileges"

  2. Click Administrator tab.