Another example of getting context information occurs in the is_runnable

8-28 Oracle Fusion Middleware Developers Guide for Oracle Portal Portlet security is invoked when a portlet is displayed on a portal page and when a portlet is returned in a portlet list by the get_portlet_list function for database providers. Security services in the Portal framework have the following key features: ■ Portlet Display: Before a portlet is displayed on a page, the provider checks for the portlets access privileges. The provider needs to define the is_portlet_ runnable function which calls the portlets is_runnable function to check access privileges. ■ User Group: You can find which default group a user belongs to by using the wwsec_api.get_defaultgroup function. ■ Check Privileges: You can find whether a user or group has the required privileges to personalize a portlet by using the wwsec_api.has_privilege function. ■ Highest Privilege: You can find the highest available privilege of a user across all groups by using the wwsec_api.get_privilege_level function. ■ Accessible Objects: You can find all the objects to which a user has access, given a privilege level, by using the wwsec_api.accessible_objects function. You can find other similar associated functions in the API documentation. The API Reference can be found on Portal Center http:portalcenter.oracle.com or, if you downloaded PDK-PLSQL pdkplsql.zip, in ..\pdkplsql\pdk\plsql\doc.

8.7.1 Using Security

To implement PLSQL portlet security, the portal requires the function is_portlet_ runnable be implemented by database providers. The actual implementation of this function is up to the application; that is, the security scheme that determines whether the current user has enough privileges to access the portlet is defined by the individual portlet implementation. The portal also requires the function get_portlet_list for database providers to return the set of portlets that are accessible by the current user. Guidelines for Using the Security APIs The portlet security mechanism may use the context and security subsystem APIs and infrastructure. The context APIs can be used to retrieve information about the current user. The security subsystem can be used to check the privileges of the current user. While using these APIs, keep in mind the following: ■ Only authorized users should be able to see your portlet in the Add Portlet dialog. This objective can be accomplished by implementing the is_portlet_ runnable function in the provider. You can also allow public access to your portlet. ■ If a portlet does not want to render itself to a user, it should return no HTML or return an exception that the page engine will ignore. It should not return an error message. Doing so adds unnecessarily to the error stack, which has its limits. Refer to Section 8.9, Implementing Error Handling for more information. Note: For more information on the context and security subsystem APIs, see the PLSQL API Reference. The API Reference can be found on Portal Center http:portalcenter.oracle.com or, if you downloaded PDK-PLSQL pdkplsql.zip, in ..\pdkplsql\pdk\plsql\doc. Creating PLSQL Portlets 8-29 ■ Portlet security allows the portlet to perform a runtime security check to ensure that the current user has the necessary authorization to access the portlet. ■ When a portlet is rendered in Show mode, it may call the is_runnable function for database providers to determine whether the portlet should be displayed for the currently logged on user. The portal does not make the call to this function directly. It is not a requirement, however, for the portlet to make this call. The portlet should make this call in its Show mode only if it implements portlet security. ■ The result of the call to is_runnable determines whether the portlet is actually displayed. If the result is true, the portlet displays; otherwise it does not display. The portlet is rendered in Show mode when it is displayed in a portal page. ■ When a portlet is returned in a portlet list by a call to the provider function get_ portlet_list, the value of the p_security_level parameter determines the purpose of the function call. When the call is made from the Portlet Repository refresh operation in order to retrieve the master list of portlets that the provider implements, the parameter p_security_level has a value of false. This setting indicates to the provider that no portlet security check should be made and a master list of all the portlets that the provider implements must be returned. The master list of portlets returned in this case is used to populate the Portlet Repository for that provider. ■ If the value of p_security_level is true, then it is up to the provider implementation to decide whether portlet security should be performed. If portlet security is implemented, the provider may return a different list of portlets depending on the current user. ■ When the Portlet Repository is displayed, Oracle Portal calls the is_portlet_ runnable function for database providers for each of the portlets that exist in the Portlet Repository. This step is done to display only the portlets that the currently logged on user is authorized to see. One example where the Portlet Repository is displayed is in the Add Portlets dialog.

8.7.2 Coding Security

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PLSQL pdkplsql.zip, illustrates how you can implement security. You can browse through this example as follows to see how the security functions are implemented in a portlet: 1. Open the services_provider.pkb file in an editor. 2. Find the is_portlet_runnable function. This function calls the security implementation through the portlets is_runnable function to check portlet access privileges. function is_portlet_runnable p_portlet_instance in wwpro_api_provider.portlet_instance_record return boolean is begin if p_portlet_instance.portlet_id = SERVICES_PORTLET_ID then return services_portlet.is_runnable p_provider_id = p_portlet_instance.provider_id ,p_reference_path = p_portlet_instance.reference_path ;