Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
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 Oracle9iAS Portal 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 Oracle9iAS Portal 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 Oracle9iAS Portal 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 Oracle9iAS Portal 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 Oracle9iAS Portal
  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 Oracle9iAS Portal 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 Oracle9iAS Portal 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 Oracle9iAS Portal 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 Oracle9iAS Portal 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 Oracle9iAS Portal 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
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE | DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE