Oracle  DBMS_XS_SESSIONS
Version 12.1.0.2

General Information
Library Note Morgan's Library Page Header
"I spent my entire adult life looking out for the well-being, the training, the equipping of the troops for whom I was responsible. I will not be lectured about what our military needs by a five-deferment draft dodger,"
~ Sen. Tammy Duckworth
Purpose Real Application Security
AUTHID CURRENT_USER
Constants
Name Data Type Value
Defined operation codes passed into namespace event handling functions
attribute_first_read_operation INTEGER 1
modify_attribute_operation INTEGER 2
Bit values that identify events of interest for a particular attribute in a namespace that has an event handling function
attribute_first_read_event INTEGER 1
modify_attribute_event INTEGER 2
Define return codes that can be returned by a namespace event handling function
event_handling_succeeded INTEGER 0
event_handling_failed INTEGER 1
The following constants are used as input into the add/delete/enable_global_callback procedure
create_session_event PLS_INTEGER 1
attach_session_event PLS_INTEGER 2
guest_to_user_event PLS_INTEGER 3
proxy_to_user_event PLS_INTEGER 4
revert_to_user_event INTEGER 5
enable_role_event INTEGER 6
disable_role_event INTEGER 7
enable_dynamic_role_event INTEGER 8
disable_dynamic_role_event INTEGER 9
detach_session_event INTEGER 10
terminate_session_event PLS_INTEGER 11
direct_login_event PLS_INTEGER 12
direct_logoff_event PLS_INTEGER 13
Dependencies
DBMS_XS_NSATTR DBMS_XS_SESSIONS_FFI XS$LIST
DBMS_XS_NSATTRLIST PLITBLM XS$NAME_LIST
Documented Yes
Exceptions
Error Code Reason
ORA-46094 XS user not effective
ORA-46210 Source user is not anonymous in user assignment operation
First Available 12cR1
Security Model Owned by SYS with EXECUTE granted to PUBLIC

For attaching to a RAS session, the executing user requires ATTACH_SESSION privilege. If dynamic roles are specified ADMINISTER_SESSION privilege is required. If namespaces are specified, appropriate privilege (MODIFY_NAMESPACE,  MODIFY_ATTRIBUTE) on the namespaces or ADMIN_ANY_NAMESPACE system privilege is required.
Source {ORACLE_HOME}/rdbms/admin/xssess.sql
Subprograms
 
ADD_GLOBAL_CALLBACK
Registers a PL/SQL procedure as the event handler with the session operation specified by the event_type parameter dbms_xs_sessions.add_global_callback(
event_type         IN PLS_INTEGER,
callback_schema    IN VARCHAR2,
callback_package   IN VARCHAR2,
callback_procedure IN VARCHAR2);
conn sys@pdbdev as sysdba

CREATE OR REPLACE PACKAGE sec_mgr.sess_pkg AUTHID CURRENT_USER AS
  PROCEDURE logoff_proc;
END sess_pkg;
/

CREATE OR REPLACE PACKAGE BODY sec_mgr.sess_pkg AS
  PROCEDURE logoff_proc IS
  BEGIN
    NULL;
  END logoff_proc
END sess_pkg;
/

exec dbms_xs_sessions.add_global_callback(dbms_xs_sessions.direct_logoff_event, 'SEC_MGR', 'SESS_PKG', 'LOGOFF_PROC');

exec dbms_xs_sessions.enable_global_callback(dbms_xs_sessions.direct_logoff_event, TRUE, 'SEC_MGR', 'SESS_PKG', 'LOGOFF_PROC');

exec dbms_xs_sessions.enable_global_callback(dbms_xs_sessions.direct_logoff_event, FALSE, 'SEC_MGR', 'SESS_PKG', 'LOGOFF_PROC');

exec dbms_xs_sessions.delete_global_callback('dbms_xs_sessions.direct_logoff_event, 'SEC_MGR', 'SESS_PKG', 'LOGOFF_PROC');
 
ASSIGN_USER
Assigns a named application user to the currently attached anonymous application session dbms_xs_sessions.assign_user(
username              IN VARCHAR2,
is_external           IN BOOLEAN                  DEFAULT FALSE,
enable_dynamic_roles  IN xs$name_list             DEFAULT NULL,
disable_dynamic_roles IN xs$name_list             DEFAULT NULL,
external_roles        xs$name_list             DEFAULT NULL,
authentication_time   IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
namespaces            IN dbms_xs_nsattrlist       DEFAULT NULL,);
SQL> exec sys.xs_principal.create_user('SEC_USER', 'HR', start_date=>SYSDATE, end_date=>SYSDATE+30);

DECLARE
 sessID RAW(16);
BEGIN
  dbms_xs_sessions.create_session('SEC_USER', sessID);
  dbms_output.put_line(sessID);
  dbms_xs_sessions.attach_session(sessID);
  dbms_xs_sessions.assign_user('UW_USER');
  dbms_xs_sessions.detach_session(TRUE);
  dbms_xs_sessions.destroy_session(sessID);
END;
/
 
ATTACH_SESSION
Attach to an already created RAS session specified by the sessionid dbms_xs_sessions.attach_session(
sessionid             IN RAW,
enable_dynamic_roles  IN xs$name_list             DEFAULT NULL,
disable_dynamic_roles IN xs$name_list             DEFAULT NULL,
external_roles        IN xs$name_list             DEFAULT NULL,
authentication_time   IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
namespaces            IN dbms_xs_nsattrlist       DEFAULT NULL);
See CREATE_SESSION Demo Below
 
CREATE_ATTRIBUTE
Creates a new custom attribute in the specified namespace in the currently attached application session dbms_xs_sessions.create_attribute(
namespace IN VARCHAR2,
attribute IN VARCHAR2,
value     IN VARCHAR2    DEFAULT NULL,
eventreg  IN PLS_INTEGER DEFAULT NULL);
BEGIN
  dbms_xs_sessions.dbms_xs_sessions.create_attribute('UWNS', 'item_type', 'generic');
  dbms_xs_sessions.dbms_xs_sessions.delete_attribute('UWNS', 'item_type');
END;
/
 
CREATE_NAMESPACE
Creates a new namespace in the currently attached application session dbms_xs_sessions.create_namespace(namespace IN VARCHAR2);
-- log in and attach to a RAS session

exec dbms_xs_sessions.create_namespace('UWNS');

exec dbms_xs_sessions.delete_namespace('UWNS');
 
CREATE_SESSION
Create a RAS session with specified 128 char case sensitive username string dbms_xs_sessions.create_session(
username    IN         VARCHAR2,
sessionid   OUT NOCOPY RAW,
is_external IN         BOOLEAN            DEFAULT FALSE,
is_trusted  IN         BOOLEAN            DEFAULT FALSE,
namespaces  IN         dbms_xs_nsattrlist DEFAULT NULL,
cookie      IN         VARCHAR2           DEFAULT NULL);
exec sys.xs_principal.create_user('SEC_USER', 'HR', start_date=>SYSDATE, end_date=>SYSDATE+30);

SQL> DECLARE
  2  sessID RAW(16);
  3  BEGIN
  4    dbms_xs_sessions.create_session('SEC_USER', sessID);
  5    dbms_output.put_line(sessID);
  6    dbms_xs_sessions.attach_session(sessID);
  7    dbms_xs_sessions.detach_session(TRUE);
  8   dbms_xs_sessions.destroy_session(sessID);
  9  END;
 10  /

4973DC2F46B643F6913A7C5D99AF78CF

PL/SQL procedure successfully completed.
 
DELETE_ATTRIBUTE
Deletes the specified attribute and its associated value from the specified namespace in the currently attached session dbms_xs_sessions.delete_attribute(
namespace IN VARCHAR2,
attribute IN VARCHAR2);
See CREATE_ATTRIBUTE Demo Above
 
DELETE_GLOBAL_CALLBACK
Deletes the global callback procedure for the session event specified by event_type dbms_xs_sessions.delete_global_callback(
event_type         IN PLS_INTEGER,
callback_schema    IN VARCHAR2 DEFAULT NULL,
callback_package   IN VARCHAR2 DEFAULT NULL,
callback_procedure IN VARCHAR2 DEFAULT NULL);
See ADD_GLOBAL_CALLBACK Demo Above
 
DELETE_NAMESPACE
Delete the specified namespace from the currently attached RAS session dbms_xs_sessions.delete_namespace(namespace IN VARCHAR2);
See CREATE_NAMESPACE Demo Above
 
DESTROY_SESSION
Implicitly detaches all traditional sessions from the application session and destroys the specified session dbms_xs_sessions.destroy_session(
sessionid IN RAW,
force     IN BOOLEAN DEFAULT FALSE);
See ASSIGN_USER Demo Above
 
DETACH_SESSION
Detaches the current traditional database session from the application session to which it is attached dbms_xs_sessions.detach_session(abort IN BOOLEAN DEFAULT FALSE);
See ASSIGN_USER Demo Above
 
DISABLE_ROLE
Disables a real application role from the specified application session dbms_xs_sessions.disable_role(role IN VARCHAR2);
exec xs_principal.create_role('RAS_ROLE', TRUE, SYSDATE, SYSDATE+30, description=>'RAS Test Role');
exec dbms_xs_sessions.enable_role('RAS_ROLE');
exec dbms_xs_sessions.disable_role('RAS_ROLE');
 
ENABLE_GLOBAL_CALLBACK
Enables or disables the global callback for the session event specified by event_type dbms_xs_sessions.enable_global_callback(
event_type         IN PLS_INTEGER,
enable             IN BOOLEAN  DEFAULT TRUE,
callback_schema    IN VARCHAR2 DEFAULT NULL,
callback_package   IN VARCHAR2 DEFAULT NULL,
callback_procedure IN VARCHAR2 DEFAULT NULL);
See ADD_GLOBAL_CALLBACK Demo Above
 
ENABLE_ROLE
Enables a real application role in the currently attached application session dbms_xs_sessions.enable_role(role IN VARCHAR2);
See DISABLE_ROLE Demo Above
 
GET_ATTRIBUTE
Gets the value of the specified attribute in the namespace in the currently attached session dbms_xs_sessions.get_attribute(
namespace IN         VARCHAR2,
attribute IN         VARCHAR2,
value     OUT NOCOPY VARCHAR2);
DECLARE
 attrlist xs$ns_attribute_list;
BEGIN
  attrlist := xs$ns_attribute_list();
  attrlist.extend(2);
  attrlist(1) := xs$ns_attribute('desc', 'general');
  attrlist(2) := xs$ns_attribute(name=>'item_no',
  attribute_events => xs_namespace.firstread_event);

  sys.xs_namespace.create_template('POAttrs', attrlist, 'SH', 'order', 'fulfillment', 'sys.ns_unrestricted_acl', 'Purchase Order');
END;
/

DECLARE
 attrVal dba_xs_session_ns_attributes.attribute%TYPE;
BEGIN
  sys.dbms_xs_sessions.get_attribute('POAttrs','item_no',attrVal);
END;
/
 
GET_SESSIONID_FROM_COOKIE
Get SID for the specified cookie. Raises an exception if no session with specified cookie exists dbms_xs_sessions.get_sessionid_from_cookie(
cookie    IN         VARCHAR2,
sessionid OUT NOCOPY RAW);
TBD
 
REAUTH_SESSION
Updates the last authentication time for the specified session ID as the current time. Applications must call this procedure when it has reauthenticated an application user. dbms_xs_sessions.reauth_session (sessionid IN RAW DEFAULT NULL);
exec dbms_xs_sessions.reauth_session('4973DC2F46B643F6913A7C5D99AF78CF');
 
RESET_ATTRIBUTE
Resets the value of an attribute to its default value (if present) or to NULL in the namespace in the current attached session dbms_xs_sessions.reset_attribute(
namespace IN VARCHAR2,
attribute IN VARCHAR2);
exec dbms_xs_sessions.reset_attribute('UWNS', 'item_no');
 
SAVE_SESSION
Persist the changes done in currently attached Triton session to the metadata table. It can only be performed from an attached session. dbms_xs_sessions.save_session;
dbms_xs_sessions.save_session;
 
SET_ATTRIBUTE
Sets the value for the specified attribute to the specified value in the namespace in the currently attached session dbms_xs_sessions_ffi.set_attribute(
namespace IN VARCHAR2,
attribute IN VARCHAR2,
value     IN VARCHAR2);
exec dbms_xs_sessions_ffi.set_attribute('UWNS', 'item_type', 'generic');
 
SET_INACTIVITY_TIMEOUT
Sets the inactivity timeout (in minutes) for the session which is the maximum period of  inactivity allowed before the session can be terminated and resource be reclaimed dbms_xs_sessions.set_inactivity_timeout(
time      IN NUMBER,
sessionid IN RAW DEFAULT NULL);
exec dbms_xs_sessions.set_inactivity_timeout('4973DC2F46B643F6913A7C5D99AF78CF', 10);
 
SET_SESSION_COOKIE
Set the cookie, which must be a unique string, for the session specified by sessionid dbms_xs_sessions.set_session_cookie(
cookie    IN VARCHAR2,
sessionid IN RAW DEFAULT NULL);
TBD
 
SWITCH_USER
Switch / proxy from current user to another user in  currently assigned RAS session dbms_xs_sessions.switch_user (
username   IN VARCHAR2,
keep_state IN BOOLEAN            DEFAULT FALSE,
namespaces IN dbms_xs_nsattrlist DEFAULT NULL) ;
exec dbms_xs_sessions.switch_user ('SEC_USER', TRUE, 'UWNS');

Related Topics
DBMS_XS_PRINCIPALS
DBMS_XS_SESSIONS_FFI
DBMS_XS_SIDP
DBMS_XS_SYSTEM
DBMS_XS_SYSTEM_FFI
Packages
What's New In 12cR1
What's New In 12cR2
XS_ACL
XS_ADMIN_UTIL
XS_DATA_SECURITY
XS_DATA_SECURITY_UTIL
XS_DIAG
XS_DIAG_INT
XS_NAMESPACE
XS_PRINCIPAL
XS_SECURITY_CLASS

Morgan's Library Page Footer
This site is maintained by Dan Morgan. Last Updated: This site is protected by copyright and trademark laws under U.S. and International law. © 1998-2017 Daniel A. Morgan All Rights Reserved