APEX_AUTHENTICATION | EOAPEX - Expertos Oracle Apex

El paquete APEX_AUTHENTICATION proporciona una API pública para plugins de autenticación.

Este paquete usa la siguiente constante:

c_default_username_cookie constant varchar2(30) := ‘LOGIN_USERNAME_COOKIE’;

Está compuesto por los siguientes procedimientos y funciones.

Procedimiento CALLBACK

Este procedimiento es el recurso de destino para las páginas de inicio de sesión externas. La llamada a este procedimiento se hace directamente desde el navegador.

La sintaxis utilizada es:

     APEX_AUTHENTICATION.CALLBACK (
          p_session_id IN NUMBER,
          p_app_id IN NUMBER,
          p_page_id IN NUMBER DEFAULT NULL,
          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 );

Donde,

Parámetro	Descripción
`p_session_id`	El identificador de sesión de APEX.
`p_app_id`	El identificador de aplicación de base de datos.
`p_page_id`	Identificador de página opcional.
`p_ajax_identifierp`	El identificador Ajax generado por el sistema.
`p_x01` through `p_x10`	Parámetros opcionales que el proceso de autenticación externo pasa al plugin de autenticación.

A continuación te presento dos ejemplos, el primero de ellos, se realiza una redirección a una página de inicio de sesión externa y la devolución de llamada se pasa a APEX, a la que se redirige el inicio de sesión externo después de una autenticación exitosa.

     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;

El segundo ejemplo, una página de inicio de sesión externa guarda los datos del usuario en una tabla compartida y realiza una devolución de llamada con un identificador de los datos. En Application Express, la devolución de llamada activa el código ajax del complemento de autenticación. Puede tomar el valor de x01 y obtener los datos reales del usuario de la tabla compartida.

     —- 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;

Procedimiento CALLBACK 1

Este procedimiento es el recurso de aterrizaje para esquemas de autenticación basados en OAuth2. Los parámetros están definidos por la especificación OAuth2. Este procedimiento es llamado a través de redirecciones, por proveedores de autenticación externos.

La sintaxis utilizada es:

     PROCEDURE CALLBACK (
          state IN VARCHAR2,
          code IN VARCHAR2 DEFAULT NULL,
          error IN VARCHAR2 DEFAULT NULL,
          error_description IN VARCHAR2 DEFAULT NULL,
          error_uri IN VARCHAR2 DEFAULT NULL,
          error_reason IN VARCHAR2 DEFAULT NULL,
          error_code IN VARCHAR2 DEFAULT NULL,
          error_message IN VARCHAR2 DEFAULT NULL,
          authuser IN VARCHAR2 DEFAULT NULL,
          session_state IN VARCHAR2 DEFAULT NULL,
          prompt IN VARCHAR2 DEFAULT NULL,
          scope IN VARCHAR2 DEFAULT NULL );

Si desea conocer más de cada uno de los parámetros, consulte el estándar OAuth2.

Procedimiento CALLBACK 2

Este procedimiento es una alternativa a CALLBACK 1

La sintaxis utilizada es una de las siguientes:

     PROCEDURE CALLBACK2 (
          p_session_id IN NUMBER,
          p_app_id IN NUMBER,
          p_ajax_identifier IN VARCHAR2,
          p_page_id IN NUMBER DEFAULT NULL,
          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 );

     PROCEDURE CALLBACK2 (
          state IN VARCHAR2,
          code IN VARCHAR2 DEFAULT NULL,
          error IN VARCHAR2 DEFAULT NULL,
          error_description IN VARCHAR2 DEFAULT NULL,
          error_uri IN VARCHAR2 DEFAULT NULL,
          error_reason IN VARCHAR2 DEFAULT NULL,
          error_code IN VARCHAR2 DEFAULT NULL,
          error_message IN VARCHAR2 DEFAULT NULL,
          authuser IN VARCHAR2 DEFAULT NULL,
          session_state IN VARCHAR2 DEFAULT NULL,
          prompt IN VARCHAR2 DEFAULT NULL,
          scope IN VARCHAR2 DEFAULT NULL );

Función GET_CALLBACK_URL

Esta función es una función auxiliar de complemento para devolver una URL que se utiliza como solicitud de destino para páginas de inicio de sesión externas. Cuando el navegador envía la solicitud, activa la devolución de llamada ajax del complemento de autenticación, que se puede usar para iniciar la sesión del usuario.

La sintaxis utilizada es:

     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,
          p_callback_name IN VARCHAR2 DEFAULT NULL )
          RETURN VARCHAR2;

Donde:

Parámetro	Descripción
`p_x01` through `p_x10`	Parámetros opcionales que el proceso de autenticación externo pasa al plugin de autenticación.
`p_callback_name`	Nombre público opcional de la llamada, el valor por defecto es `apex_authentication.callback`.

Para un ejemplo, consulte el procedimiento CALLBACK de arriba.

Función GET_LOGIN_USERNAME_COOKIE

Esta función lee la cookie con el nombre de usuario desde la página de login por defecto.

La sintaxis utilizada es:

     GET_LOGIN_USERNAME_COOKIE (
          p_cookie_name IN VARCHAR2 DEFAULT c_default_username_cookie )
     RETURN VARCHAR2;

En donde,

Parámetro	Descripción
`p_cookie_name`	El nombre de la cookie que almacena el nombre del usuario en el navegador.

Por ejemplo:

     :P101_USERNAME := apex_authentication.get_login_username_cookie;
     :P101_REMEMBER_USERNAME := case when :P101_USERNAME is not null
               then ‘Y’
               else ‘N’
          end;

Función IS_AUTHENTICATED

Esta función comprueba si el usuario está autenticado en la sesión y devuelve VERDADERO (TRUE) si el usuario ya ha iniciado sesión o FALSO (FALSE) si el usuario de la sesión actual aún no está autenticado.

La sintaxis utilizada es:

APEX_AUTHENTICATION.IS_AUTHENTICATED
RETURN BOOLEAN;

Por ejemplo:

     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;

Función IS_PUBLIC_USER

Esta función comprueba si el usuario no está autenticado en la sesión. Se devuelve FALSO si el usuario ya inició sesión o VERDADERO si el usuario de la sesión actual aún no está autenticado.

La sintaxis utilizada es:

APEX_AUTHENTICATION.IS_PUBLIC_USER
return BOLLEAN;

Por ejemplo:

     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;

Procedimiento LOGIN

Este procedimiento autentica al usuario en la sesión actual.

El proceso de inicio de sesión consta de los siguientes pasos:

Ejecuta el procedimiento de autenticación previa del esquema de autenticación.
Ejecuta la función de autenticación del esquema de autenticación para verificar las credenciales del usuario (p_username, p_password), devolviendo VERDADERO en caso de éxito.
Si resultado=true: ejecuta el procedimiento posterior a la autenticación.
Si resultado = true: guarda el nombre de usuario en la tabla de sesión.
Si el resultado = verdadero: configura la URL de redirección para un enlace profundo.
Si resultado=false: configura la URL de redireccionamiento a la página actual, con un mensaje de error en el parámetro notification_msg.
Registra el resultado de la autenticación.
Redirige

La sintaxis utilizada es:

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

Donde,

Parámetro	Descripción
`p_username`	El nombre de usuario.
`p_password`	La contraseña del usuario.
`p_uppercase_username`	Si es `TRUE` entonces `p_username` es convertido a mayúsculas.

Por ejemplo:

apex_authentication.login(‘JOE USER’, ‘mysecret’);

Procedimiento LOGOUT

Este procedimiento cierra la sesión y redirige a la página de inicio de la aplicación. Llame a este procedimiento directamente desde el navegador.

La sintaxis utilizada es:

     APEX_AUTHENTICATION.LOGOUT (
          p_session_id IN NUMBER,
          p_app_id IN NUMBER,
          p_ws_app_id IN NUMBER DEFAULT NULL );

Donde:

Parámetro	Descripción
`p_session_id`	El identificador de sesión APEX de la sesión a cerrar.
`p_app_id`	El identificador de aplicación de base de datos.
`p_ws_app_id`	El identificador de la aplicación de hoja de cálculo.

Por ejemplo:

apex_authentication.logout(:SESSION, :APP_ID);

Procedimiento SAML_METADATA

Este procedimiento emite los metadatos SAML para la aplicación dada o para la instancia APEX.

La sintaxis utilizada es:

APEX_AUTHENTICATION.SAML_METADATA (
p_app_id IN NUMBER DEFAULT NULL );

Donde,

Parámetro	Descripción
`p_app_id`	El ID de la aplicación para la que se deben generar los metadatos del proveedor de servicios. Si es NULL o si la autenticación SAML de la aplicación está configurada para usar el modo de instancia, genera metadatos usando los atributos de la instancia SAML.

Por ejemplo:

$ curl https://www.example.com/apex/apex_authentication.saml_metadata?p_app_id=101

Función PERSISTENT_COOKIES_ENABLED

Esta función devuelve si las cookies persistentes están habilitadas en la instancia. Los administradores de instancias pueden controlar este valor con el parámetro WORKSPACE_NAME_USER_COOKIE.

La sintaxis utilizada es:

FUNCTION PERSISTENT_COOKIES_ENABLED
RETURN BOOLEAN;

Retorna:

TRUE: WORKSPACE_NAME_USER_COOKIE está definada a Y o no se ha definido.
FALSE: WORKSPACE_NAME_USER_COOKIE está definida a N.

Procedimiento POST_LOGIN

Este procedimiento autentica al usuario en la sesión actual. Ejecuta un subconjunto de inicio de sesión(), sin los pasos 1 y 2. Para conocer los pasos, consulte el Procedimiento LOGIN. Es principalmente útil en esquemas de autenticación donde la verificación de credenciales de usuario se realiza externamente a APEX.

La sintaxis utilizada es:

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

Donde:

Parámetro	Descripción
`p_username`	El nombre de usuario.
`p_password`	La contraseña del usuario.
`p_uppercase_username`	Si es `TRUE` entonces `p_username` se convierte a mayúsculas.

Por ejemplo:

apex_authentication.post_login(‘JOE USER’, ‘mysecret’);

Procedimiento SEND_LOGIN_USERNAME_COOKIE

Este procedimiento envía una cookie con el nombre de usuario.

La sintaxis utilizada es:

     SEND_LOGIN_USERNAME_COOKIE (
          p_username IN VARCHAR2,
          p_cookie_name IN VARCHAR2 DEFAULT c_default_username_cookie,
          p_consent IN BOOLEAN DEFAULT FALSE );

Donde:

Parámetro	Descripción
`p_username`	El nombre de usuario.
`p_cookie_name`	El nombre de la cookie que almacena `p_username` en el navegador.
`p_consent`	Controla si la cookie debe ser enviada. Si es `true`, asume que el usuario dió su consentimiento para enviar la cookie. Si es `false`, no envía la cookie. Si no existe el consentimiento del usuario y la cookie ya existe, el procedimiento sobreescribe la cookie existente con `NULL`. Este parámetro es ignorado y no se envía ninguna cookie si persistent_cookies_enabled retorna `false`.

Por ejemplo:

     apex_authentication.send_login_username_cookie (
          p_username => :P101_USERNAME,
          p_consent => :P101_REMEMBER_USERNAME = ‘Y’ );