15 Implementing Content Security
This chapter describes how to use the APIs provided with Oracle Portal to ensure that your content is secure. It contains the following sections:
For more information about any of these APIs, refer to the Oracle 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_type_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 the following 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_aclonly) -
p_person_id is the ID of the user to whom you want to grant privileges (
set_user_aclonly) -
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_aclonly). 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_aclonly). 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 Oracle 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 of the following parameters are passed rather than the parameter values:
-
Pass an array of user IDs to
p_itemown_userto grant the Manage privilege to a list of users. -
Pass an array of user IDs to
p_itemmanage_userto grant the Edit privilege to a list of users. -
Pass an array of user IDs to
p_itemview_userto grant the View privilege to a list of users. -
Pass an array of group IDs to
p_itemown_groupto grant the Manage privilege to a list of groups. -
Pass an array of group IDs to
p_itemmanage_groupto grant the Edit privilege to a list of groups. -
Pass an array of group IDs to
p_itemview_groupto 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 shows how you can use the add_item_ils_privileges API to grant item-level privileges to users.
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, as shown in Example 15-10.
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 Oracle Portal user interface). Example 15-11 shows how to use the inherit_folder_privileges API.
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.