Overview    Package  Object Type   Deprecated   Index   Help  
Oracle Application Server Portal PL/SQL API Reference - 904
PREV PACKAGE    NEXT PACKAGE FRAMES    NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE

Package wwsec_app_priv

This package contains methods to check user access privileges before routines are executed, and to redirect browsers to the Single Sign-On Server when authentication is necessary.

Application must make a check_privilege call before executing routines because OracleAS Portal 10G implements a single DAD concept. Therefore all login routines are done through the Single Sign-On Server.

When mod_plsql receives a request for a procedure, it is able to invoke the procedure as long as the package is accessible to PUBLIC in general, and to the database schema to which the user is mapped, in particular. This procedure then, should perform access control checks to determine if the user has appropriate access rights.

Note: All procedures and functions in packages granted to PUBLIC or to a database schema mapped to the PUBLIC portal user, must make this check before further processing if they require specific privileges to be executed. For more information, see Check privilege function logic.

For information about privilege constants referenced when using wwsec_app_priv APIs, see wwa_api_privilege global privilege objects.

Scope:
Public
Since:
Oracle9iAS Portal 3.0.6.6.5



Function/Procedure Summary
check_if_logged_on
Checks if the user is logged in (not using the PUBLIC account) and displays the user Login Page if the user is not.
 boolean
check_privilege
Checks if the user has the privilege necessary to access an object and creates an error message if the user does not.
 boolean
check_privilege
Checks if a user has any of a passed-in list of privileges.
 boolean
check_privilege
Checks if the user has at least a given privilege code value for those privileges that have hierarchical code values.
 boolean
get_login_link
Provides applications with a hyperlink to the user Login Page.
 varchar2
get_login_url
Provides the applications with the URL to the user Login Page.
 varchar2
get_logout_link
Returns the anchor tag that generates the Logout hyperlink.
 varchar2
get_logout_url
Returns the URL of the procedure that logs the current user out from OracleAS Portal 10G and the Single Sign-On Server.
 varchar2
get_portal_login_link_text
Returns the hyperlink text string for the Login or Logout link, depending on whether the user is logged in or out.
 varchar2
get_portal_login_url
Returns the URL for the Login or Logout link based on whether the current user is logged in or out.
 varchar2
login
Performs a redirect of the browser to the user Login Page.
 
logout
Logs the current user out of OracleAS Portal 10G and emits an image of a checkmark for the Single Sign-On Server's global logout screen.
 
process_signon
This procedure is registered as the SUCCESS_URL of the OracleAS Portal 10G in the Single Sign-On Server.
 
retrieve_requested_url
Returns the requested URL from session storage.
 varchar2

Function/Procedure Detail

check_if_logged_on

function  
      
check_if_logged_on(
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home'
) return boolean
    
Checks if the user is logged in (not using the PUBLIC account) and displays the user Login Page if the user is not.

Example:

  if wwsec_app_priv.check_if_logged_on
  (
     p_requested_url => wwctx_api.get_product_schema || '.this_procedure'
  )
  then...
Parameters:
p_requested_url - the URL that the user is attempting to access. Note that:
  • the requested URL is the location that the user's browser displays after a successful authorization
  • the requested URL may be passed in as an argument, and if not specified, will default to the home page.
Returns:
TRUE if the user is logged in, FALSE if not
Since:
Oracle9iAS Portal 3.0.6.6.5

check_privilege

function  
      
check_privilege(
    p_object in varchar2,
    p_privilege in varchar2,
    p_name in varchar2,
    p_auto_redirect in boolean default true,
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home',
    p_owner in varchar2 default wwctx_api . get_product_schema,
    p_reqd_auth_level in number default wwctx_api . required_authentication_level
) return boolean
    
Checks if the user has the privilege necessary to access an object and creates an error message if the user does not.

If the user does not have the right privilege, it could mean that the user is not logged on and that the PUBLIC user does not have the necessary privilege. Alternatively, a logged on user may simply not have sufficient privileges.

In the first case, the user should login. In the second case, an appropriate message is displayed to the user.

Example:

  procedure display_user_mgr ( ... )
  begin
      -- always begin with a privilege check
      if wwsec_app_priv.check_privilege
      (
          p_object    => wwsec_api.PAGE_OBJ,
          p_privilege => wwsec_api.VIEW_PRIV,
          p_name      => '0/156',
          p_requested_url   => wwctx_api.get_product_schema||
              '.wwsec_app_user_mgr.display_user_mgr',
          p_reqd_auth_level => wwctx_api.REQUIRED_AUTHENTICATION_LEVEL
      )
      then
          -- will not reach here if no privileges...
          -- privileged application code may follow
          ...
      end if;
  end display_user_mgr;
Parameters:
p_object - the type of object being secured
p_privilege - the privilege name being checked
p_name - a unique identifier for the specified object instance
p_auto_redirect - indicates if the screen should display the Login Page if a user is not logged in and does not have sufficient privileges in PUBLIC mode to access the object. If TRUE is returned, the user is redirected to the Login Page.
Note that because this parameter defaults to TRUE, it has no effect if the user is already logged in.
p_requested_url - the URL of the object for which privileges are being checked. Note that the p_requested_url parameter should point the user's browser to the page to be displayed after successful authorization.
p_owner - the name of the schema that owns the p_name object
p_reqd_auth_level - the minimum authentication level that a calling function requires in order to pass a privilege check.
The API fails the authorization check if the current authentication level (returned by wwctx_api.get_authentication_level) is less than the value of this parameter.
Note that if the object is granted PUBLIC access, the authentication level is not checked at all.
The default value for this parameter is wwctx_api.REQUIRED_AUTHENTICATION_LEVEL and this is equivalent to wwctx_api.PUBLIC_AUTHENTICATION. This implies that the user must be authenticated by the Single Sign-On Server for the authorization check to pass.
Portlets that require authorization fail the authorization check for a weakly authenticated user. If a portlet wants to display itself to a weakly authenticated user, it should pass p_reqd_auth_level as wwctx_api.WEAK_AUTHENTICATION while invoking the authorization APIs.
Note: This parameter is available in Oracle9iAS Portal 3.0.9 or later.
Returns:
TRUE if the user can execute this procedure. If the user does not, it returns FALSE.
Since:
Oracle9iAS Portal 3.0.6.6.5

check_privilege

function  
      
check_privilege(
    p_object in varchar2,
    p_privilege_array in wwsec_api.array,
    p_name in varchar2,
    p_auto_redirect in boolean default true,
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home',
    p_owner in varchar2 default wwctx_api . get_product_schema,
    p_reqd_auth_level in number default wwctx_api . required_authentication_level
) return boolean
    
Checks if a user has any of a passed-in list of privileges.

Example:

  l_priv_array wwsec_api.array;
  l_priv_array(1):= wwsec_api.PAGE_PRIV;
  if wwsec_app_priv.check_privilege
  (
       p_object            => wwsec_api.PAGE_OBJ,
       p_privilege_array   => l_priv_array,
       p_name              => '0/156',
       p_requested_url     => wwctx_api.get_product_schema ||'
                              .wwsec_app_user_mgr.display_user_mgr'
  )
  then...
Parameters:
p_object - the type of object being secured
p_privilege_array - the list of privilege names being checked. Note that these names are specified with privilege name constants of the wwsec_api package.
p_name - a unique identifier for the specified object instance
p_auto_redirect - indicates if the screen should display the Login Page if a user is not logged in and does not have sufficient privileges in PUBLIC mode to access the object. If TRUE is returned, the user is redirected to the Login Page.
Note that because this parameter defaults to TRUE, it has no effect if the user is already logged in.
p_requested_url - the URL of the object for which privileges are being checked. Note that the p_requested_url parameter should point the user's browser to the page to be displayed after successful authorization.
p_owner - the name of the schema that owns the p_name object
p_reqd_auth_level - the minimum authentication level that a calling function requires in order to pass a privilege check.
The API fails the authorization check if the current authentication level (returned by wwctx_api.get_authentication_level) is less than the value of this parameter.
Note that if the object is granted PUBLIC access, the authentication level is not checked at all.
The default value for this parameter is wwctx_api.REQUIRED_AUTHENTICATION_LEVEL and this is equivalent to wwctx_api.PUBLIC_AUTHENTICATION. This implies that the user must be authenticated by the Single Sign-On Server for the authorization check to pass.
Portlets that require authorization fail the authorization check for a weakly authenticated user. If a portlet wants to display itself to a weakly authenticated user, it should pass p_reqd_auth_level as WEAK_AUTHENTICATION while invoking the authorization APIs.
Note: This parameter is available in Oracle9iAS Portal 3.0.9 or later.
Returns:
TRUE if the user has any privilege on the specified list. If the user does not, it returns FALSE.
Since:
Oracle9iAS Portal 3.0.6.6.5

check_privilege

function  
      
check_privilege(
    p_object in varchar2,
    p_privilege_code in number,
    p_name in varchar2,
    p_auto_redirect in boolean default true,
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home',
    p_owner in varchar2 default wwctx_api . get_product_schema,
    p_reqd_auth_level in number default wwctx_api . required_authentication_level
) return boolean
    
Checks if the user has at least a given privilege code value for those privileges that have hierarchical code values. When using this function, set privilege_code to the minimum privilege that you expect the user to have to access the object.

Note: A typical use would be to learn if a user has a VIEW privilege for a particular folder.

Example:

  if wwsec_app_priv.check_privilege
  (
       p_object => wwsec_api.PAGE_OBJ,
       p_privilege_code => wwsec_api.PAGE_VIEW,
       p_name => '0/156',
       p_requested_url => wwctx_api.get_product_schema ||'
                          .wwsec_app_user_mgr.display_user_mgr'
  )
  then...
Parameters:
p_object - the type of object being secured
p_privilege_code - the privilege code being checked. Set this parameter to the minimum privilege code the user should have to access the object.
p_name - a unique identifier for the specified object instance
p_auto_redirect - indicates if the screen should display the Login Page if a user is not logged in and does not have sufficient privileges in PUBLIC mode to access the object. If TRUE is returned, the user is redirected to the Login Page.
Note that because this parameter defaults to TRUE, it has no effect if the user is already logged in.
p_requested_url - the URL of the object for which privileges are being checked. Note that the p_requested_url parameter should point the user's browser to the page to be displayed after successful authorization.
p_owner - the name of the schema that owns the p_name object
p_reqd_auth_level - the minimum authentication level that a calling function requires in order to pass a privilege check.
The API fails the authorization check if the current authentication level (returned by wwctx_api.get_authentication_level) is less than the value of this parameter.
Note that if the object is granted PUBLIC access, the authentication level is not checked at all.
The default value for this parameter is wwctx_api.REQUIRED_AUTHENTICATION_LEVEL and this is equivalent to wwctx_api.PUBLIC_AUTHENTICATION. This implies that the user must be authenticated by the Single Sign-On Server for the authorization check to pass.
Portlets that require authorization fail the authorization check for a weakly authenticated user. If a portlet wants to display itself to a weakly authenticated user, it should pass p_reqd_auth_level as wwctx_api.WEAK_AUTHENTICATION while invoking the authorization APIs.
Note: This parameter is available in Oracle9iAS Portal 3.0.9 or later.
Returns:
TRUE if the user has at least the specified privilege code. If the user does not, it returns FALSE.
Since:
Oracle9iAS Portal 3.0.6.6.5

get_login_link

function  
      
get_login_link(
    p_nls_link_text in varchar2 default null,
    p_image_filename in varchar2 default null,
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home'
) return varchar2
    
Provides applications with a hyperlink to the user Login Page. Use this function to render a link to the user Login Page. Note that:
  • The function returns a string containing anchor tags and a hyperlink reference to the URL.
  • The second option allows the link text to be set by the application, or it can use the default.

Example:

   htp.htmlopen;
   htp.bodyopen;
   htp.p
   (
       wwsec_app_privs.get_login_link(
           p_nls_link_text => wwnls_api.get_string(
               p_domain        => 'research',
               p_sub_domain    => 'main',
               p_language      => 'us',
               p_name          => 'login_link_text'
           ),
           p_image_filename => wwctx_api.get_image_path('login.gif'),
           p_requested_url  => wwctx_api.get_product_schema || '.home'
       )
   );
   htp.bodyclose;
   htp.htmlclose;
Parameters:
p_nls_link_text - optional text that is used as the hyperlink text if the format CONTENT_TYPE_HTML is specified. Note that this text should be in the NLS language requested by the user.
p_image_filename - an optional image filename and path for inclusion in an image tag to use for the Login link. The default (null) results in a simple text link. Note that when this parameter is specified, the nls_link_text is used as alternative (mouseover) text, i.e. Alt text.
p_requested_url - an optional parameter indicating the URL that you want to be redirected to upon successful authentication. Note that this parameter allows an application to specify a page to be redirected to upon successful authentication.
Returns:
anchor tags and a hyperlink reference to the URL
See Also:
get_login_url
Since:
Oracle9iAS Portal 3.0.6.6.5

get_login_url

function  
      
get_login_url(
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home',
    p_cancel_url in varchar2 default wwctx_api . get_product_schema || '.home'
) return varchar2
    
Provides the applications with the URL to the user Login Page. Use this function whenever a URL to the user Login Page must be obtained.

Example:

 declare
     l_url varchar2(100);
 begin
     l_url := wwsec_app_priv.get_login_url
 end;
Parameters:
p_requested_url - the URL (page) to be displayed upon successful authentication
p_cancel_url - the URL (page) to be displayed when the user cancels authentication
Returns:
This function returns the user Login Page URL as text or as an HTTP formatted hyperlink
See Also:
get_login_link
Since:
Oracle9iAS Portal 3.0.6.6.5

get_logout_link

function  
      
get_logout_link(
    p_nls_link_text in varchar2 default null,
    p_image_filename in varchar2 default null,
    p_done_url in varchar2 default wwctx_api . get_product_schema || '.home'
) return varchar2
    
Returns the anchor tag that generates the Logout hyperlink.

Example:

   if wwctx_api.is_logged_on then
       wwsec_app_priv.get_logout_link
       (
           p_done_url => 'home'
       );
   ...
Parameters:
p_nls_link_text - the translated text to be displayed for the Logout link
p_image_filename - the image to be displayed for the Logout link
p_done_url - the page to display after logging out
Returns:
an anchor tag that generates the Logout link for OracleAS Portal 10G
Since:
Oracle9iAS Portal 3.0.6.6.5

get_logout_url

function  
      
get_logout_url(
    p_done_url in varchar2 default wwctx_api . get_product_schema || '.home'
) return varchar2
    
Returns the URL of the procedure that logs the current user out from OracleAS Portal 10G and the Single Sign-On Server. This produces the URL to the associated SSO Server's global logout procedure.

Example:

   begin
   htp.anchor
   (
       curl    => wwsec_app_priv.get_logout_url,
       ctext   => wwsec_ui.nls ('logout_link_text')
   );
   end;
Parameters:
p_done_url - the URL of the page to be displayed after the user logs out
Returns:
the URL of the page displayed to log out the current user from OracleAS Portal 10G and the Single Sign-On Server
Since:
Oracle9iAS Portal 3.0.6.6.5

get_portal_login_link_text

function  
      
get_portal_login_link_text
return varchar2
    
Returns the hyperlink text string for the Login or Logout link, depending on whether the user is logged in or out.

Example:

     begin
     htp.anchor
     (
       curl    => wwsec_app_priv.get_portal_login_url,
       ctext   => wwsec_app_priv.get_portal_login_link_text
     );
     end;
Returns:
the text for the Login or Logout link
Since:
Oracle9iAS Portal 3.0.6.6.5

get_portal_login_url

function  
      
get_portal_login_url(
    p_requested_url in varchar2 default wwctx_api . get_proc_path ( p_url => 'home' ),
    p_cancel_url in varchar2 default wwctx_api . get_proc_path ( p_url => 'home' )
) return varchar2
    
Returns the URL for the Login or Logout link based on whether the current user is logged in or out.

Example:

     begin
     htp.anchor
     (
       curl    => wwsec_app_priv.get_portal_login_url,
       ctext   => wwsec_app_priv.get_portal_login_link_text
     );
     end;
Parameters:
p_requested_url - the URL of the user Login Page. This parameter allows an application to specify a page to be displayed after authentication.
p_cancel_url - the URL of the page to be displayed when the user cancels authentication
Returns:
the URL for the Login or Logout link
Since:
Oracle9iAS Portal 3.0.6.6.5

login

procedure  
      
login(
    p_requested_url in varchar2 default wwctx_api . get_product_schema || '.home',
    p_cancel_url in varchar2 default wwctx_api . get_product_schema || '.home'
)
    
Performs a redirect of the browser to the user Login Page.

Example:

  if not wwctx_api.is_logged_on
  then
  wwsec_app_priv.login
  (
       p_requested_url => l_requested_url
  );
  ...
Parameters:
p_requested_url - the URL of the object for which privileges are being checked
p_cancel_url - specifies a page to be displayed when the user cancels authentication
Since:
Oracle9iAS Portal 3.0.6.6.5

logout

procedure  
      
logout
    
Logs the current user out of OracleAS Portal 10G and emits an image of a checkmark for the Single Sign-On Server's global logout screen.

This procedure is intended to be called from the Single Sign-On Server doing a global logout.

See Also:
get_logout_url
Since:
Oracle9iAS Portal 9.0.2

process_signon

procedure  
      
process_signon(
    urlc in varchar2
)
    
This procedure is registered as the SUCCESS_URL of the OracleAS Portal 10G in the Single Sign-On Server. This procedure parses the url cookie to find the username and requested URL. It updates the session information and then redirects to the requested URL. This procedure is only intended to be called from the Single Sign-On Server.
Parameters:
urlc - the authentication token passed from the Single Sign-On Server after successful authentication
Since:
Oracle9iAS Portal 3.0.6.6.5

retrieve_requested_url

function  
      
retrieve_requested_url(
    p_requested_url in varchar2
) return varchar2
    
Returns the requested URL from session storage.

This procedure is used by process_signon in OracleAS Portal 10G and the Single Sign-On Server to retrieve the requested URL from the session storage if it was null in the parse_url_cookie. This is because in some cases, the URL becomes too large to be passed in site2pstoretoken, causing problems in Internet Explorer (IE). So, in these cases, the URL is kept in session storage for later retrieval. This is done only when necessary in order to remain as performant as possible.

Example:

     l_requested_url := wwsec_app_priv.retrieve_requested_url(
         p_requested_url => l_requested_url
     );
Parameters:
p_requested_url - this is the value of the p_requested_url parsed out from the urlc from process_signon. It is passed into this function, and evaluated to see if it indicates that the actual value should be obtained from the session store, and if so, the value in session storage is returned. Otherwise the value passed in is returned.
Returns:
the URL that process_signon should redirect to
Since:
Oracle9iAS Portal 9.0.2

Overview    Package  Object Type   Deprecated   Index   Help  
Oracle Application Server Portal PL/SQL API Reference - 904
PREV PACKAGE    NEXT PACKAGE FRAMES    NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE