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: