APEX_CUSTOM

You can use the APEX_CUSTOM_AUTH package to perform various operations related to authentication and session management.

APPLICATION_PAGE_ITEM_EXISTS Function

This function checks for the existence of page-level item within the current page of an application. This function requires the parameter p_item_name. This function returns a Boolean value (true or false).

Syntax

APEX_CUSTOM_AUTH.APPLICATION_PAGE_ITEM_EXISTS(
    p_item_name   IN    VARCHAR2)
RETURN BOOLEAN;

Parameters

Table: APPLICATION_PAGE_ITEM_EXISTS Parameters describes the parameters available in the APPLICATION_PAGE_ITEM_EXISTS function.

APPLICATION_PAGE_ITEM_EXISTS Parameters

Parameter	Description
`p_item_name`	The name of the page-level item.

Example

The following example checks for the existance of a page-level item, ITEM_NAME, within the current page of the application.

DECLARE
    L_VAL BOOLEAN;
BEGIN
    VAL := APEX_CUSTOM_AUTH.APPLICATION_PAGE_ITEM_EXISTS(:ITEM_NAME);
    IF L_VAL THEN
        htp.p('Item Exists');
    ELSE
        htp.p('Does not Exist');
    END IF;
END;

CURRENT_PAGE_IS_PUBLIC Function

This function checks whether the current page's authentication attribute is set to Page Is Public and returns a Boolean value (true or false)

DEFINE_USER_SESSION Procedure

This procedure combines the SET_USER and SET_SESSION_ID procedures to create one call.

Syntax

APEX_CUSTOM_AUTH.DEFINE_USER_SESSION(
    p_user         IN    VARCHAR2,
    p_session_id   IN    NUMBER);

Parameters

Table: DEFINE_USER_SESSION Parameters describes the parameters available in the DEFINE_USER_SESSION procedure.

DEFINE_USER_SESSION Parameters

Parameter	Description
`p_user`	Login name of the user.
`p_session_id`	The session ID.

Example

In the following example, a new session ID is generated and registered along with the current application user.

APEX_CUSTOM_AUTH.DEFINE_USER_SESSION (
    :APP_USER, 
    APEX_CUSTOM_AUTH.GET_NEXT_SESSION_ID);

GET_COOKIE_PROPS Procedure

This procedure obtains the properties of the session cookie used in the current authentication scheme for the specified application. These properties can be viewed directly in the Application Builder by viewing the authentication scheme attributes.

Syntax

APEX_CUSTOM_AUTH.GET_COOKIE_PROPS(
    p_app_id                       IN  NUMBER,
    p_cookie_name                  OUT VARCHAR2,
    p_cookie_path                  OUT VARCHAR2,
    p_cookie_domain                OUT VARCHAR2);

Parameters

Table: GET_COOKIE_PROPS Parameters describes the parameters available in the GET_COOKIE_PROPS procedure.

GET_COOKIE_PROPS Parameters

Parameter	Description
`p_app_id`	An application ID in the current workspace.
`p_cookie_name`	The cookie name.
`p_cookie_path`	The cookie path.
`p_cookie_domain`	The cookie domain.

Example

The following example retrieves the session cookie values used by the authentication schema of the current application.

DECLARE
    l_cookie_name   varchar2(256);
    l_cookie_path   varchar2(256);
    l_cookie_domain varchar2(256);
BEGIN
    APEX_CUSTOM_AUTH.GET_COOKIE_PROPS(
        p_app_id => 2918,
        p _cookie_name => l_cookie_name,
        p _cookie_path => l_cookie_path,
        p _cookie_domain => l_cookie_domain);
END;

GET_LDAP_PROPS Procedure

This procedure obtains the LDAP attributes of the current authentication scheme for the current application. These properties can be viewed directly in Application Builder by viewing the authentication scheme attributes.

Syntax

APEX_CUSTOM_AUTH.GET_LDAP_PROPS(
    p_ldap_host                OUT VARCHAR2,
    p_ldap_port                OUT INTEGER,
    p_ldap_dn                  OUT VARCHAR2,
    p_ldap_edit_function       OUT VARCHAR2);

Parameters

Table: GET_LDAP_PROPS Parameters describes the parameters available in the GET_LDAP_PROPS procedure.

GET_LDAP_PROPS Parameters

Parameter	Description
`p_ldap_host`	LDAP host name.
`p_ldap_port`	LDAP port number.
`p_ldap_dn`	LDAP DN string.
`p_ldap_edit_function`	LDAP edit function name.

Example

The following example retrieves the LDAP attributes associated with the current application.

DECLARE
    l_ldap_host          VARCHAR2(256);
    l_ldap_port          INTEGER;
    l_ldap_dn            VARCHAR2(256);
    l_ldap_edit_function VARCHAR2(256);
BEGIN
APEX_CUSTOM_AUTH.GET_LDAP_PROPS (
    p_ldap_host       => l_ldap_host,
    p_ldap_port       => l_ldap_port,
    p_ldap_dn         => l_ldap_dn,
    p_ldap_edit_function => l_ldap_edit_function);
END;

GET_NEXT_SESSION_ID Function

This function generates the next session ID from the Oracle Application Express sequence generator. This function returns a number.

Syntax

APEX_CUSTOM_AUTH.GET_NEXT_SESSION_ID 
RETURN NUMBER;

Example

The following example generates the next session ID and stores it into a variable.

DECLARE
    VAL NUMBER;
BEGIN
    VAL := APEX_CUSTOM_AUTH.GET_NEXT_SESSION_ID;
END;

GET_SECURITY_GROUP_ID Function

This function returns a number with the value of the security group ID that identifies the workspace of the current user.

Syntax

APEX_CUSTOM_AUTH.GET_SECURITY_GROUP_ID 
RETURN NUMBER;

Example

The following example retrieves the Security Group ID for the current user.

DECLARE
    VAL NUMBER;
BEGIN
    VAL := APEX_CUSTOM_AUTH.GET_SECURITY_GROUP_ID;
END;

GET_SESSION_ID Function

This function returns APEX_APPLICATION.G_INSTANCE global variable. GET_SESSION_ID returns a number.

Syntax

APEX_CUSTOM_AUTH.GET_SESSION_ID 
RETURN NUMBER;

Example

The following example retrieves the session ID for the current user.

DECLARE
    VAL NUMBER;
BEGIN
    VAL := APEX_CUSTOM_AUTH.GET_SESSION_ID;
END;

GET_SESSION_ID_FROM_COOKIE Function

This function returns the Oracle Application Express session ID located by the session cookie in the context of a page request in the current browser session.

Syntax

APEX_CUSTOM_AUTH.GET_SESSION_ID_FROM_COOKIE
RETURN NUMBER;

Example

The following example retrieves the session ID from the current session cookie.

DECLARE 
    VAL NUMBER;
BEGIN
    VAL := APEX_CUSTOM_AUTH.GET_SESSION_ID_FROM_COOKIE;
END;

GET_USER Function

This function returns the APEX_APPLICATION.G_USER global variable (VARCHAR2).

Syntax

APEX_CUSTOM_AUTH.GET_USER 
RETURN VARCHAR2;

Examples

The following example retrieves the username associated with the current session.

DECLARE
    VAL VARCHAR2(256);
BEGIN
    VAL := APEX_CUSTOM_AUTH.GET_USER;
END;

GET_USERNAME Function

This function returns user name registered with the current Oracle Application Express session in the internal sessions table. This user name is usually the same as the authenticated user running the current page.

Syntax

APEX_CUSTOM_AUTH.GET_USERNAME
RETURN VARCHAR2;

Example

The following example retrieves the username registered with the current application session.

DECLARE
    VAL VARCHAR2(256);
BEGIN
    VAL := APEX_CUSTOM_AUTH.GET_USERNAME;
END;

IS_SESSION_VALID Function

This function is a Boolean result obtained from executing the current application's authentication scheme to determine if a valid session exists. This function returns the Boolean result of the authentication scheme's page sentry.

Syntax

APEX_CUSTOM_AUTH.IS_SESSION_VALID
RETURN BOOLEAN;

Example

The following example verifies whether the current session is valid.

DECLARE
    L_VAL BOOLEAN;
BEGIN
    L_VAL := APEX_CUSTOM_AUTH.IS_SESSION_VALID;
    IF L_VAL THEN
        htp.p('Valid');
    ELSE
        htp.p('Invalid');
    END IF;
END;

LOGIN Procedure

Also referred to as the "Login API," this procedure performs authentication and session registration.

Syntax

APEX_CUSTOM_AUTH.LOGIN(
    p_uname                    IN  VARCHAR2  DEFAULT NULL,
    p_password                 IN  VARCHAR2  DEFAULT NULL,
    p_session_id               IN  VARCHAR2  DEFAULT NULL,
    p_app_page                 IN  VARCHAR2  DEFAULT NULL,
    p_entry_point              IN  VARCHAR2  DEFAULT NULL,
    p_preserve_case            IN  BOOLEAN   DEFAULT FALSE);

Parameter

Table: LOGIN Parameters describes the parameters available in the LOGIN procedure.

Parameter	Description
`p_uname`	Login name of the user.
`p_password`	Clear text user password.
`p_session_id`	Current Oracle Application Express session ID.
`p_app_page`	Current application ID. After login page separated by a colon (:).
`p_entry_point`	Internal use only.
`p_preserve_case`	If true, do not upper `p_uname` during session registration

Example

The following example performs the user authentication and session registration.

BEGIN
    APEX_CUSTOM_AUTH.LOGIN (
        p_uname       => 'FRANK',
        p_password    => 'secret99',
        p_session_id  => V('APP_SESSION'),
        p_app_page    => :APP_ID||':1');
END;

Note:

Do not use bind variable notations for p_session_id argument.

LOGOUT Procedure

This procedure causes a logout from the current session by unsetting the session cookie and redirecting to a new location.

Syntax

APEX_CUSTOM_AUTH.LOGOUT(
    p_this_app                   IN VARCHAR2  DEFAULT NULL,
    p_next_app_page_sess         IN VARCHAR2  DEFAULT NULL,
    p_next_url                   IN VARCHAR2  DEFAULT NULL);

Parameter

Table: LOGOUT Parameters describes the parameters available in the LOGOUT procedure.

LOGOUT Parameters

Parameter	Description
`p_this_app`	Current application ID.
`p_next_app_page_sess`	Application and page number to redirect to. Separate multiple pages using a colon (:) and optionally followed by a colon (:) and the session ID (if control over the session ID is desired).
`p_next_url`	URL to redirect to (use this instead of `p_next_app_page_sess`).

Example

The following example causes a logout from the current session and redirects to page 99 of application 1000.

BEGIN
    APEX_CUSTOM_AUTH.LOGOUT (
        p_this_app            => '1000',
        p_next_app_page_sess  => '1000:99');
END;

POST_LOGIN Procedure

This procedure performs session registration, assuming the authentication step has been completed. It can be called only from within an Oracle Application Express application page context.

Syntax

APEX_CUSTOM_AUTH.POST_LOGIN(
    p_uname                    IN  VARCHAR2  DEFAULT NULL,
    p_session_id               IN  VARCHAR2  DEFAULT NULL,
    p_app_page                 IN  VARCHAR2  DEFAULT NULL,
    p_preserve_case            IN  BOOLEAN   DEFAULT FALSE);

Parameter

Table: POST_LOGIN Parameters describes the parameters available in the POST_LOGIN procedure.

POST_LOGIN Parameters

Parameter	Description
`p_uname`	Login name of user.
`p_session_id`	Current Oracle Application Express session ID.
`p_app_page`	Current application ID and after login page separated by a colon (:).
`p_preserve_case`	If true, do not include `p_uname` in uppercase during session registration.

Example

The following example performs the session registration following a successful authentication.

BEGIN
    APEX_CUSTOM_AUTH.POST_LOGIN (
        p_uname       => 'FRANK',
        p_session_id  => V('APP_SESSION'),
        p_app_page    => :APP_ID||':1');
END;

SESSION_ID_EXISTS Function

This function returns a Boolean result based on the global package variable containing the current Oracle Application Express session ID. Returns true if the result is a positive number and returns false if the result is a negative number.

Syntax

APEX_CUSTOM_AUTH.SESSION_ID_EXISTS 
RETURN BOOLEAN;

Example

The following example checks whether the current session ID is valid and exists.

DECLARE
    L_VAL BOOLEAN;
BEGIN
    L_VAL := APEX_CUSTOM_AUTH.SESSION_ID_EXISTS;
    IF VAL THEN
        htp.p('Exists');
    ELSE
        htp.p('Does not exist');
    END IF;
END;

SET_SESSION_ID Procedure

This procedure sets APEX_APPLICATION.G_INSTANCE global variable. This procedure requires the parameter P_SESSION_ID (NUMBER) which specifies a session ID.

Syntax

APEX_CUSTOM_AUTH.SET_SESSION_ID( 
    p_session_id    IN    NUMBER);

Parameters

Table: SET_SESSION_ID Parameters describes the parameters available in the SET_SESSION_ID procedure.

SET_SESSION_ID Parameters

Parameter	Description
`p_session_id`	The session ID to be registered.

Example

In the following example, the session ID value registered is retrieved from the browser cookie.

APEX_CUSTOM_AUTH.SET_SESSION_ID(APEX_CUSTOM_AUTH.GET_SESSION_ID_FROM_COOKIE);

SET_SESSION_ID_TO_NEXT_VALUE Procedure

This procedure combines the operation of GET_NEXT_SESSION_ID and SET_SESSION_ID in one call.

Syntax

APEX_CUSTOM_AUTH.SET_SESSION_ID_TO_NEXT_VALUE;

Example

In the following example, if the current session is not valid, a new session ID is generated and registered.

IF NOT APEX_CUSTOM_AUTH.SESSION_ID_EXISTS THEN
    APEX_CUSTOM_AUTH.SET_SESSION_ID_TO_NEXT_VALUE;
END IF;

SET_USER Procedure

This procedure sets the APEX_APPLICATION.G_USER global variable. SET_USER requires the parameter P_USER (VARCHAR2) which defines a user ID.

Syntax

APEX_CUSTOM_AUTH.SET_USER(
    p_user   IN    VARCHAR2);

Parameters

Table: SET_USER Parameters describes the parameters available in the SET_USER procedure.

SET_USER Parameters

Parameter	Description
`p_user`	The user ID to be registered.

Example

In the following example, if the current application user is NOBODY, then JOHN.DOE is registered as the application user.

IF V('APP_USER') = 'NOBODY' THEN
    APEX_CUSTOM_AUTH.SET_USER('JOHN.DOE');
END IF;