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

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

Since:

Oracle9iAS Portal 3.0.6.6.5

See Also:

get_login_url

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

Since:

Oracle9iAS Portal 3.0.6.6.5

See Also:

get_login_link

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

get_req_url_for_site2pstore

function get_req_url_for_site2pstore(
    p_requested_url in varchar2
) return varchar2

This function checks for the below cases and if found then the requested URL is held in the session store instead of passing it through the site2pstoretoken. This is done only if necessary since it degrades performance with the extra access of the session store. 1. The requested url exceeds a limit that would cause IE to not be able to handle the resulting URLC size. The above mentioned workaround is done only if the browser is IE, which has the problem. 2. The requested url has '~' character. This character is used as delimiter on the sso side.

Parameters:

p_requested_url - It is passed into this function, and evaluated to see for the above mentioned cases. In case the above conditions is satisfied then the requested url is held in the session store and a place holder url is returned. Otherwise the value passed in is returned.

Returns:

the URL to pass through the site2pstoretoken

Since:

Oracle9iAS Portal 10.1.4

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',
    p_forced_authentication in boolean default false
) 

Performs a redirect of the browser to the user Login Page. A paranoid application can request the Single Sign-On Server to force the user to authenticate. The request is redirected to the SSO server. In case of forced authentication, the user is always challenged for authentication even if another partner application has authenticated the user earlier.

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

p_forced_authentication - is it a request for forced authentication? TRUE: forced_authentication, FALSE: regular 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.

Since:

Oracle9iAS Portal 9.0.2

See Also:

get_logout_url

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