Skip Headers

Oracle® Application Server Portal Developer's Guide 10g Release 3 (10.1.3) B25601-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 15 Implementing Content Security

This chapter describes how to use the APIs provided with OracleAS Portal to ensure that your content is secure. It contains the following sections:

- Retrieving Object Privileges

- Setting Page Level Privileges

- Setting Item Level Privileges

For more information about any of these APIs, refer to the Oracle Application Server Portal PL/SQL API Reference on Portal Center:

    http://portalcenter.oracle.com

In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.

Tip: Remember, if you are calling the APIs from a Web provider or external application, you need to set the session context first. For more information, refer to Section 10.1, "Setting the Session Context".

## 15.1 Retrieving Object Privileges

To retrieve a list of privileges that are currently defined for an object, use the `wwsec_api.grantee_list` API. Example 15-1 prints the values of the grantee array for a page with an ID of 17623 in page group with an ID of 33. Example 15-2 prints the values of the grantee array for an item with a master ID of 32919 in a page group with an ID of 53.

Example 15-1 Retrieving the List of Privileges for a Page (grantee_list API)

    declare
      l_grantees         wwsec_api.grantee_array;
      l_object_type_name varchar2(5)  := wwsec_api.PAGE_OBJ;
      l_name             varchar2(60) := '33/17623';
    begin
      -- Call the function.
      l_grantees := wwsec_api.grantee_list(
        p_object_typ_name => l_object_type_name,
        p_name            => l_name
      );
      -- Output the results
      if l_grantees is not null then
        if l_grantees.count > 0 then
          for i in l_grantees.first..l_grantees.last loop
            if l_grantees.exists(i) then
              dbms_output.put.line('GRANTEE_TYPE '||to_char(i)||'= '||l_grantees(i).GRANTEE_TYPE);
              dbms_output.put.line('GRANTEE_ID '||to_char(i)||'= '||l_grantees(i).GRANTEE_ID);
              dbms_output.put.line('GRANTEE_NAME '||to_char(i)||'= '||l_grantees(i).GRANTEE_NAME);
              dbms_output.put.line('PRIVILEGE '||to_char(i)||'= '||l_grantees(i).PRIVILEGE);
            end if;
          end loop;
        end if;
      end if;
    exception
      ...
    end;
    /

Example 15-2 Retrieving the List of Privileges for an Item

    declare
      l_grantees         wwsec_api.grantee_array;
      p_object_type_name varchar2(5)  := wwsec_api.ITEM_OBJ;
      p_name             varchar2(60) := '53/32919';
    begin
      -- Call the function.
      l_grantees := wwsec_api.grantee_list(p_object_type_name, p_name);
      -- Output the results.
      if l_grantees is not null then
        if l_grantees.count > 0 then
          for i in l_grantees.first..l_grantees.last loop
            if l_grantees.exists(i) then
              dbms_output.put.line('GRANTEE_TYPE '||to_char(i)||'= '||l_grantees(i).GRANTEE_TYPE);
              dbms_output.put.line('GRANTEE_ID '||to_char(i)||'= '||l_grantees(i).GRANTEE_ID);
              dbms_output.put.line('GRANTEE_NAME '||to_char(i)||'= '||l_grantees(i).GRANTEE_NAME);
              dbms_output.put.line('PRIVILEGE '||to_char(i)||'= '||l_grantees(i).PRIVILEGE);
            end if;
          end loop;
        end if;
      end if;
    exception
      ...
    end;
    /

The `grantee_list` API takes three parameters:

- p_object_type_name is the type of the object. Use the predefined constants in the WWSEC_API package to specify the value of this parameter, for example wwsec_api.PAGE_OBJ or wwsec_api.ITEM_OBJ.

- p_name is the reference to the object. Use the format `'<page group ID>/<object ID>'`. So for items, use `'<page group ID>/<master item ID>'`, for example `'53/32919'`.

- p_owner is the name of the schema that owns the object. For items, do not pass a value to this parameter as it defaults to the portal schema owner.

The API returns an array (WWSEC_API.GRANTEE_ARRAY) with the following columns:

- grantee_type is either USER or GROUP

- grantee_id is the unique ID of the user or group

- grantee_name is the user name or group name

- privilege is the privilege granted to the user or group

## 15.2 Setting Page Level Privileges

This section shows how to use APIs in the `WWSEC_API` package to set page level privileges.

Note: You can also use the APIs listed in the following sections to set tab level access by using the following format for the `p_name` parameter:
    <page group ID>/<tab ID>
You do not need to specify the ID of the container page, as the tab ID is enough to uniquely identify the tab within the page group.

### 15.2.1 Granting Page Level Privileges

Example 15-3 shows how to use the `set_group_acl` API to grant privileges to a group. Example 15-4 shows how to use the `set_user_acl` API to grant privileges to a user.

Example 15-3 Granting Page Privileges to a Group (set_group_acl API)

    declare
      l_group_id number       := wwsec_api.group_id('MYGROUP');
      l_name     varchar2(60) := '33/17623';
    BEGIN
      wwsec_api.set_group_acl(
        p_group_id         => l_group_id,
        p_object_type_name => wwsec_api.PAGE_OBJ,
        p_name             => l_name,
        p_privilege        => wwsec_api.VIEW_PRIV
      );
    end;
    /

Example 15-4 Granting Page Privileges to a User (set_user_acl API)

    declare
      l_person_id number      := wwsec_api.id('JOHN.SMITH');
      l_name     varchar2(60) := '33/17623';
    begin
      wwsec_api.set_user_acl(
        p_person_id        => l_person_id,
        p_object_type_name => wwsec_api.PAGE_OBJ,
        p_name             => l_name,
        p_privilege        => wwsec_api.VIEW_PRIV
      );
    end;
    /

These two APIs take the following parameters:

- p_group_id is the ID of the group to which you want to grant privileges (`set_group_acl` only)

- p_person_id is the ID of the user to whom you want to grant privileges (`set_user_acl` only)

- p_object_type_name is type of the object on which you want to grant privileges. Use the predefined constants in the WWSEC_API package to specify the value of this parameter, for example wwsec_api.PAGE_OBJ.

- p_name is the reference to the object. Use the format `'<page group ID>/<page ID>'`, for example `'33/17623'`.

- p_privilege is the level of privilege you want to grant to the user or group. Use the predefined constants in the WWSEC_API package to specify the value of this parameter, for example wwsec_api.VIEW_PRIV.

### 15.2.2 Removing Page Level Privileges

At some point, it may become necessary to remove a user or group's privileges from a page. Example 15-5 shows how to use the `remove_group_acl` API to remove a group's privileges. Example 15-6 shows how to use the `remove_user_acl` API to remove a user's privileges.

Example 15-5 Removing Page Privileges from a Group (remove_group_acl API)

    declare
      l_group_id number       := wwsec_api.group_id('MYGROUP');
      l_name     varchar2(60) := '33/17623';
    BEGIN
      wwsec_api.remove_group_acl(
        p_object_type_name => wwsec_api.PAGE_OBJ,
        p_name             => l_name,
        p_group_id        => l_group_id,
        p_privilege        => wwsec_api.MANAGE_PRIV
      );
    end;
    /

Example 15-6 Removing Page Privileges from a User (remove_user_acl API)

    declare
      l_person_id number       := wwsec_api.id('JOHN.SMITH');
      l_name     varchar2(60)  := '33/17623';
    BEGIN
      wwsec_api.remove_user_acl(
        p_object_type_name => wwsec_api.GROUP_OBJ,
        p_name             => l_name,
        p_person_id        => l_person_id,
        p_privilege        => wwsec_api.MANAGE_PRIV
      );
    end;
    /

These two APIs take the following parameters:

- p_object_type_name is type of the object from which you want to remove privileges. Use the predefined constants in the WWSEC_API package to specify the value of this parameter, for example wwsec_api.PAGE_OBJ.

- p_name is the reference to the object. Use the format `'<page group ID>/<page ID>'`, for example `'33/17623'`.

- p_group_id is the ID of the group whose privileges you want to remove (`remove_group_acl` only). Set this parameter to NULL if you want to remove the specified privilege on this page from all groups.

- p_person_id is the ID of the user whose privileges you want to remove (`remove_user_acl` only). Set this parameter to NULL if you want to remove the specified privilege on this page from all users.

- p_privilege is the level of privilege you want to remove from the user or group. Use the predefined constants in the WWSEC_API package to specify the value of this parameter, for example wwsec_api.VIEW_PRIV. Set this parameter to NULL if you want to remove all privileges on the page from the user or group.

## 15.3 Setting Item Level Privileges

If item level security (ILS) is enabled for a page, you can specify access privileges for individual items on the page.

Example 15-7 shows how to use the `modify_folder` API to enable ILS for a page.

Example 15-7 Enabling Item Level Security for a Page

    declare
      l_page     wwsbr_api.page_record;
    begin
      select *
      into l_page
      from   <schema>.wwsbr_user_pages
      where  siteid = 33
        and  id = 1
        and  rownum = 1;
      l_page.haveitemsecurity := 1;
      wwsbr_api.modify_folder(
        p_page => l_page
      );
      -- Process cache invalidation messages.
      wwpro_api_invalidation.execute_cache_invalidation;
    exception
      ...
    end;
    /

For information about the `modify_folder` API and WWSBR_USER_PAGES view used in Example 15-7, refer to Section 11.1, "Editing Page Properties".

Example 15-8 shows how to enable ILS for an individual item (this is the same as selecting Define Item Level Access Privileges in the OracleAS Portal user interface):

Example 15-8 Enabling Item Level Security for an Item (enable_ils_for_item API)

    begin
      wwsbr_api.enable_ils_for_item(
        p_master_item_id => 453,
        p_caid           => 33,
        p_folder_id      => 45
      );
      -- Process cache invalidation messages.
      wwpro_api_invalidation.execute_cache_invalidation;
    exception
      ...
    end;
    /

- p_master_item_id is the master ID of the item. You can find this value in the MASTERID column of the WWSBR_ALL_ITEMS view.

- p_caid is the ID of the page group to which the item belongs.

- p_folder_id is the ID of the page on which the item appears.

Tip: If you want to edit other attributes for the item as well as the ILS setting, you can use the `modify_item` or `modify_item_post_upload` APIs instead. To enable ILS set the `p_access_level` parameter to wwsbr_api.ITEM_ACCESS, to disable ILS set the parameter to wwsbr_api.FOLDER_ACCESS.

### 15.3.1 Granting Item Level Privileges

After enabling ILS for the item, you can define access privileges for one or more users or groups.

When setting item level privileges, the type of privileges that are granted is dependent on which parameters are passed rather than the parameter values:

- Pass an array of user IDs to `p_itemown_user` to grant the Manage privilege to a list of users.

- Pass an array of user IDs to `p_itemmanage_user` to grant the Edit privilege to a list of users.

- Pass an array of user IDs to `p_itemview_user` to grant the View privilege to a list of users.

- Pass an array of group IDs to `p_itemown_group` to grant the Manage privilege to a list of groups.

- Pass an array of group IDs to `p_itemmanage_group` to grant the Edit privilege to a list of groups.

- Pass an array of group IDs to `p_itemview_group` to grant the View privilege to a list of groups.

You can pass values to any combination of these parameters in the same procedure call to set a range of privileges across different users and groups.

Example 15-9 Granting Item Level Privileges to Users (add_item_ils_privileges API)

    declare
      l_itemown_username_array wwsbr_type.array;
      l_itemown_userid_array   wwsbr_type.array;
    begin
      l_itemown_username_array(1) := 'jsmith';
      l_itemown_username_array(2) := 'janesmith';
      l_itemown_username_array(3) := 'joedoe';
      for i in 1 .. l_itemown_username_array.count loop
        -- Get the user ID from the wwsec_api.id_sso API.
        l_itemown_userid_array(i) := wwsec_api.id_sso(
          p_username => l_itemown_username_array(i)
        );
      end loop;
      wwsbr_api.add_item_ils_privileges(
        p_master_item_id => 453,
        p_caid           => 33,
        p_folder_id      => 45,
        p_itemown_user   => l_itemown_userid_array
      );
      -- Process cache invalidation messages.
      wwpro_api_invalidation.execute_cache_invalidation;
    exception
      ...
    end;
    /

- p_master_item_id is the master ID of the item. You can find this value in the MASTERID column of the WWSBR_ALL_ITEMS view.

- p_caid is the ID of the page group to which the item belongs.

- p_folder_id is the ID of the page on which the item appears.

- p_itemown_user is an array of user IDs to which you want to grant Manage privileges.

If you pass the same user or group in more than one of the privilege arrays, the user or group is granted the highest privilege level specified.

Tip: You can also update the access privileges for an item using the `add_item_ils_privileges` API.

### 15.3.2 Removing Item Level Privileges

If for some reason, you need to remove a user or group's privileges on an item, use the `delete_ils_privilege` API.

Example 15-10 Removing Item Level Privileges (delete_ils_privilege API)

    declare
      l_user_id       number := 334;
      l_page_group_id number := 75;
      l_page_id       number := 1;
      l_item_id       number := 74637;
    begin
      wwsbr_api.delete_ils_privilege(
        p_user_or_group_id => l_user_id,
        p_caid             => l_page_group_id,
        p_folder_id        => l_page_id,
        p_master_item_id   => l_item_id
      );
      -- Process cache invalidation messages.
      wwpro_api_invalidation.execute_cache_invalidation;
    exception
      ...
    end;
    /

- p_user_or_group_id is the ID of the user or group for which you want to remove privileges.

- p_caid is the ID of the page group to which the item belongs.

- p_folder_id is the ID of the page on which the item appears.

- p_master_item_id is the master ID of the item. You can find this value in the MASTERID column of the WWSBR_ALL_ITEMS view.

### 15.3.3 Inheriting Item Level Privileges from the Page

If you decide that an item that has its own privileges defined should, in fact, simply inherit its privileges from the page instead, use the `inherit_folder_privileges` API to disable ILS (this is the same as selecting Inherit Parent Page Access Privileges in the OracleAS Portal user interface).

Example 15-11 Inheriting Item Privileges from the Parent Page (inherit_folder_privileges API)

    begin
      wwsbr_api.inherit_folder_privileges(
        p_master_item_id => 453,
        p_caid           => 33,
        p_folder_id      => 45
      );
      -- Process cache invalidation messages.
      wwpro_api_invalidation.execute_cache_invalidation;
    exception
      ...
    end;
    /

- p_master_item_id is the master ID of the item. You can find this value in the MASTERID column of the WWSBR_ALL_ITEMS view.

- p_caid is the ID of the page group to which the item belongs.

- p_folder_id is the ID of the page on which the item appears.

Tip: If you want to edit other attributes for the item as well as the ILS setting, you can use the `modify_item` or `modify_item_post_upload` APIs instead. To enable ILS set the `p_access_level` parameter to wwsbr_api.ITEM_ACCESS, to disable ILS set the parameter to wwsbr_api.FOLDER_ACCESS.