3 APEX_AUTHENTICATION

The APEX_AUTHENTICATION package provides a public API for authentication plugins.

Topics:

Constants

The following constant is used by this package.

c_default_username_cookie constant varchar2(30) := 'LOGIN_USERNAME_COOKIE';

CALLBACK Procedure

This procedure is the landing resource for external login pages. Call this procedure directly from the browser.

Syntax

APEX_AUTHENTICATION.CALLBACK ( 
    p_session_id IN NUMBER, 
    p_app_id IN NUMBER, 
    p_ajax_identifier IN VARCHAR2, 
    p_x01 IN VARCHAR2 DEFAULT NULL, 
    p_x02 IN VARCHAR2 DEFAULT NULL, 
    p_x03 IN VARCHAR2 DEFAULT NULL, 
    p_x04 IN VARCHAR2 DEFAULT NULL, 
    p_x05 IN VARCHAR2 DEFAULT NULL, 
    p_x06 IN VARCHAR2 DEFAULT NULL, 
    p_x07 IN VARCHAR2 DEFAULT NULL, 
    p_x08 IN VARCHAR2 DEFAULT NULL, 
    p_x09 IN VARCHAR2 DEFAULT NULL, 
    p_x10 IN VARCHAR2 DEFAULT NULL );

Parameters

Table 3-1 describes the parameters available in CALLBACK procedure.

Table 3-1 APEX_AUTHENTICATION.CALLBACK Procedure Parameters

Parameters Description

p_session_id

The Application Express session identifier.

p_app_id

The database application identifier.

p_ajax_identifierp

The system generated AJAX identifier. See "GET_AJAX_IDENTIFIER Function".

p_x01 through p_x10

Optional parameters that the external login passes to the authentication plugin.

Example 1

In this example, a redirect is performed to an external login page and the callback is passed into Application Express, which the external login redirects to after successful authentication.

declare 
    l_callback varchar2(4000) := apex_application.get_callback_url; 
begin 
    sys.owa_util.redirect_url( 
        'https://single-signon.example.com/my_custom_sso.login?p_on_success='|| 
        sys.utl_url.escape ( 
            url => l_callback, 
            escape_reserved_chars => true ); 
    apex_application.stop_apex_engine; 
end;

Example 2

In this example, an external login page saves user data in a shared table and performs a call back with a handle to the data. In Application Express, the callback activates the authentication plugin's ajax code. It can take the value of x01 and fetch the actual user data from the shared table.

---- create or replace package body my_custom_sso as 
procedure login ( 
    p_on_success in varchar2 ) 
    is 
    l_login_id varchar2(32); 
begin 
    l_login_id := rawtohex(sys.dbms_crypto.random(32)); 
    insert into login_data(id, username) values (l_login_id, 'JOE USER'); 
    sys.owa_util.redirect_url ( 
    p_on_success||'&p_x01='||l_login_id ); 
end; 
---- end my_custom_sso;

See Also:

"GET_CALLBACK_URL Function"

GET_CALLBACK_URL Function

This function is a plugin helper function to return a URL that is used as a landing request for external login pages. When the browser sends the request, it triggers the authentication plugin ajax callback, which can be used to log the user in.

Syntax

APEX_AUTHENTICATION.GET_CALLBACK_URL ( 
    p_x01 IN VARCHAR2 DEFAULT NULL, 
    p_x02 IN VARCHAR2 DEFAULT NULL, 
    p_x03 IN VARCHAR2 DEFAULT NULL, 
    p_x04 IN VARCHAR2 DEFAULT NULL, 
    p_x05 IN VARCHAR2 DEFAULT NULL, 
    p_x06 IN VARCHAR2 DEFAULT NULL, 
    p_x07 IN VARCHAR2 DEFAULT NULL, 
    p_x08 IN VARCHAR2 DEFAULT NULL, 
    p_x09 IN VARCHAR2 DEFAULT NULL, 
    p_x10 IN VARCHAR2 DEFAULT NULL ) 
    return VARCHAR2;

Parameters

Table 3-2 describes the parameters available in GET_CALLBACK_URL function.

Table 3-2 APEX_AUTHENTICATION.GET_CALLBACK _URL Function Parameters

Parameters Description

p_x01 through p_x10

Optional parameters that the external login passes to the authentication plugin.

Example

See example in "CALLBACK Procedure".

See Also:

"CALLBACK Procedure"

GET_LOGIN_USERNAME_COOKIE Function

This function reads the cookie with the username from the default login page.

Syntax

APEX_AUTHENTICATION.GET_LOGIN_USERNAME_COOKIE ( 
    p_cookie_name IN VARCHAR2 DEFAULT c_default_username_cookie ) 
    return varchar2;

Parameters

Table 3-3 describes the parameters available in GET_LOGIN_USERNAME_COOKIE function.

Table 3-3 APEX_AUTHENTICATION.GET_LOGIN_USERNAME_COOKIE Function Parameters

Parameters Description

p_cookie_name

The cookie name that stores the username in the browser.

Example

In this example, GET_LOGIN_USERNAME_COOKIE saves the username cookie value into the page item P101_USERNAME.

:P101_USERNAME := apex_authentication.get_login_username_cookie;

IS_AUTHENTICATED Function

This function checks if the user is authenticated in the session and returns TRUE if the user is already logged in or FALSE if the user of the current session is not yet authenticated.

Syntax

APEX_AUTHENTICATION.IS_AUTHENTICATED
    return BOOLEAN;

Parameters

None.

Example

In this example, IS_AUTHENTICATED is used to emit the username if the user has already logged in or a notification if the user has not.

if apex_authentication.is_authenticated then 
    sys.htp.p(apex_escape.html(:APP_USER)||', you are known to the system'); 
else 
    sys.htp.p('Please sign in'); 
end if;

See Also:

"IS_PUBLIC_USER Function"

IS_PUBLIC_USER Function

This function checks if the user is not authenticated in the session. A FALSE is returned if the user is already logged on or TRUE if the user of the current session is not yet authenticated.

Syntax

APEX_AUTHENTICATION.IS_PUBLIC_USER
    return BOLLEAN;

Parameters

None.

Example

In this example, IS_PUBLIC_USER is used to show a notification if the user has not already logged in or the username if the user has not.

if apex_authentication.is_public_user then 
    sys.htp.p('Please sign in'); 
else 
    sys.htp.p(apex_escape.html(:APP_USER)||', you are known to the system'); 
end if;

LOGIN Procedure

This procedure authenticates the user in the current session.

Login processing has the following steps:

  1. Run authentication scheme's pre-authentication procedure.

  2. Run authentication scheme's authentication function to check the user credentials (p_username, p_password), returning true on success.

  3. If result=true: run post-authentication procedure.

  4. If result=true: save username in session table.

  5. If result=true: set redirect url to deep link.

  6. If result=false: set redirect url to current page, with an error message in the notification_msg parameter.

  7. Log authentication result.

  8. Redirect.

Syntax

APEX_AUTHENTICATION.LOGIN ( 
    p_username IN VARCHAR2, 
    p_password IN VARCHAR2, 
    p_uppercase_username IN BOOLEAN DEFAULT TRUE );

Parameters

Table 3-4 describes the parameters available in LOGIN Procedure.

Table 3-4 APEX_AUTHENTICATION.LOGIN Procedure Parameters

Parameters Description

p_username

The user's name.

p_password

The user's password.

p_uppercase_username

If TRUE then p_username is converted to uppercase.

Example

This example passes user credentials, username and password, to the authentication scheme.

apex_authentication.login('JOE USER', 'mysecret');

See Also:

"POST_LOGIN Procedure"

LOGOUT Procedure

This procedure closes the session and redirects to the application's home page. Call this procedure directly from the browser.

Syntax

APEX_AUTHENTICATION.LOGOUT ( 
    p_session_id in number, 
    p_app_id in number, 
    p_ws_app_id in number default null );

Parameters

Table 3-5 describes the parameters available in LOGOUT Procedure.

Table 3-5 APEX_AUTHENTICATION.LOGOUT Procedure Parameters

Parameters Description

p_session_id

The Application Express session identifier of the session to close.

p_app_id

The database application identifier.

p_ws_app_id

The websheet application identifier.

Example

This example logs the session out.

apex_authentication.logout(:SESSION, :APP_ID);

POST_LOGIN Procedure

This procedure authenticates the user in the current session. It runs a subset of login(), without steps 1 and 2. For steps, see "LOGIN Procedure". It is primarily useful in authentication schemes where user credentials checking is done externally to Application Express.

Syntax

APEX_AUTHENTICATION.POST_LOGIN ( 
    p_username IN VARCHAR2, 
    p_password IN VARCHAR2, 
    p_uppercase_username IN BOOLEAN DEFAULT TRUE );

Parameters

Table 3-6 describes the parameters available in POST_LOGIN Procedure.

Table 3-6 APEX_AUTHENTICATION.POST_LOGIN Procedure Parameters

Parameters Description

p_username

The user's name.

p_password

The user's password.

p_uppercase_username

If TRUE then p_username is converted to uppercase.

Example

This procedure call passes user credentials, username and password, to the authentication scheme to finalize the user's authentication.

apex_authentication.post_login('JOE USER', 'mysecret');

See Also:

"LOGIN Procedure"

SEND_LOGIN_USERNAME_COOKIE Procedure

This procedure sends a cookie with the username.

Syntax

APEX_AUTHENTICATION.SEND_LOGIN_USERNAME_COOKIE ( 
    p_username IN VARCHAR2, 
    p_cookie_name IN VARCHAR2 DEFAULT c_default_username_cookie );

Parameters

Table 3-7 describes the parameters available in SEND_LOGIN_USERNAME_COOKIE Procedure.

Table 3-7 APEX_AUTHENTICATION.SEND_LOGIN_USERNAME_COOKIE Procedure Parameters

Parameters Description

p_username

The user's name.

p_cookie_name

The cookie name which stores p_username in the browser.

Example

This example shows how to call SEND_LOGIN_USERNAME_COOKIE, to save the value of item P101_USERNAME in the login cookie.

apex_authentication.send_login_username_cookie (
    p_username => :P101_USERNAME );