About Creating and Maintaining Application Sessions

This section contains:

Creating an Application Session

You can create an application session using the DBMS_XS_SESSIONS.CREATE_SESSION procedure in PL/SQL or using the createSession method of the XSSessionManager class in Java. To create an application session, the invoking user needs CREATE_SESSION application privilege. This privilege can be obtained through XS_SESSION_ADMIN Database role or by XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE API call (see “GRANT_SYSTEM_PRIVILEGE Procedure” for more information). CREATE_SESSION procedure populates the unique identifier of the newly created session in sessionid out parameter. This unique identifier can be used to refer to the session in future calls. The DBA_XS_SESSIONS data dictionary view displays all the application sessions in the database.

You can also specify a list of namespaces to be created when the session is created. If you specify namespaces during creation of the session, the caller must have application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or the ADMIN_NAMESPACE system privilege.

Example: Creating an Application Session shows how to create an application session with lwuser1.

Example: Creating an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
END;

See Also:

Creating an Anonymous Application Session

You can also create an anonymous application session using the DBMS_XS_SESSIONS.CREATE_SESSION procedure in PL/SQL or using the createAnonymousSession method of the XSSessionManager class in Java. To create an anonymous session through the PL/SQL API, you must specify the predefined user name XSGUEST.

Example: Creating an Anonymous Application Session shows how to create an anonymous session with the predefined user XSGUEST.

After creating an anonymous application session, you can assign a named user to the session.

Example: Creating an Anonymous Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('XSGUEST', sessionid);
END;

See Also:

Attaching an Application Session to a Traditional Database Session

To use an application session, it must be associated with a database session. This operation is called attach. You can attach an application session to a traditional database session using the DBMS_XS_SESSIONS.ATTACH_SESSION procedure in PL/SQL or the attachSession method of the XSSessionManager class in Java. A database session can only attach one application session at a time. The DBA_XS_ACTIVE_SESSIONS dynamic data dictionary view displays all attached application sessions in the database.

To execute this procedure, the traditional session user must have the ATTACH_SESSION application privilege. This privilege can be obtained through the XS_SESSION_ADMIN Database role or by the XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE API call. If you specify namespaces, then the user is required to have the application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or ADMIN_NAMESPACE system privilege.

Example: Attaching an Application Session shows how to attach an application session to a database session.

Beginning with Oracle Database 12c Release 2 (12.2), Oracle Label Security supports Real Application Security users. This means that Oracle Label Security context is established in the Real Application Security session during the attach operation, so that Oracle Label Security authorization can be exercised in the Real Application Security user session. Oracle Label Security provides the ability to define data labels, assign user labels and protect sensitive application data within the Oracle database.

For example, using Oracle Label Security data labels allows each row of a table to be labeled based on its level of confidentiality. Data labels consist of 3 components: levels, compartments, and groups. So a given data label should have one level, zero or more compartments and zero or more groups associated with it. Compartments allow defining finer granularity within a level – all data belonging to a particular project can be labeled with the same compartment. Groups are hierarchical and a group can thus be associated with a parent group.

In addition, using Oracle Label Security user labels, each user can be assigned labels that constrain access to labeled data. Each user is assigned a range of levels, compartments, and groups, and each session can operate within that authorized range to access labeled data within that range.

Furthermore, using privileges, Oracle Label Security privileges are policy specific and used to provide users specific rights to perform special operations or to access data beyond their label authorizations. The list of all policy specific privileges is: FULL, READ, COMPACCESS, PROFILE_ACCESS, WRITEUP, WRITEDOWN, and WRITEACROSS.

Using Oracle Label Security, trusted stored programs can be used. A trusted stored program unit is a stored procedure, function, or package that has been granted one or more label security privileges. Trusted stored program units are used to let users perform privileged operations in a controlled manner, or update data at several labels. By granting privileges to a program unit, the privileges required for users can be effectively reduced.

Using Oracle Label Security, a policy is applied to a table or an entire schema after defining data labels or user labels or both and assigning appropriate privileges to users. When a policy is applied on a table, label security creates a policy specific NUMBER column on the table to store numeric equivalent of the data labels defined before for the policy. The column can be created as a user visible column or as a hidden column. The user can specify various enforcement options when the policy is applied on the table. The READ_CONTROL enforcement option for example protects the table from queries and WRITE_CONTROL protects it from DML operations.

Establishing Oracle Label Security context in a Real Application Security session therefore lets SELECT and DML operations return results authorized for the Real Application Security user.

To attach a session with dynamic roles, a list of dynamic roles can be passed in the PL/SQL ATTACH_SESSION procedure.

Note: When developing the application, ensure that all application end user actions are captured within an ATTACH_SESSION … DETACH_SESSION programming block. (For more information, see “Detaching an Application Session from a Traditional Database Session”).

Example: Attaching an Application Session

DECLARE
  sessionid raw(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
END;

See Also:

Setting a Cookie for an Application Session

You can associate a specific cookie with an application session using the DBMS_XS_SESSIONS.SET_SESSION_COOKIE procedure in PL/SQL or the setCookie method of the XSSessionManager class in Java. The cookie can also be associated at the time of creation of the session through the CREATE_SESSION PL/SQL API. A cookie is a token embedded in a user’s session by a web site during an application session. So the next time the same user requests something from that web site, it sends the cookie to the application session, which allows the server to associate the session with that user.

To execute this procedure, the user must be granted the MODIFY_SESSION application privilege. This privilege can be obtained through the XS_SESSION_ADMIN Database role or by the XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE API call.

Example: Setting a Cookie for an Application Session shows how to set a cookie for an application session.

Example: Setting a Cookie for an Application Session

DECLARE
  sessionid raw(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.SET_SESSION_COOKIE('Cookie1', sessionid);
END;

See Also:

Assigning an Application User to an Anonymous Application Session

You can assign a named application user to a currently attached anonymous application session using the DBMS_XS_SESSIONS.ASSIGN_USER procedure in PL/SQL or the assignUser method of the XSSessionManager class in Java. Assigning a user changes the user session from anonymous to a named user.

To execute this procedure, the dispatcher or connection user must have the ASSIGN_USER application privilege. This privilege can be obtained through the XS_SESSION_ADMIN Database role or by the XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE API call. If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or ADMIN_NAMESPACE system privilege. A list of dynamic roles can also be enabled using the DBMS_XS_SESSIONS.ASSIGN_USER procedure.

Beginning with Oracle Database 12c Release 2 (12.2), Oracle Label Security supports Real Application Security users. If the Real Application Security user is authorized in any Oracle Label Security policy then, during an assign_user call, the corresponding label security authorization is established for the named Real Application Security user session. Establishing Oracle Label Security context in a Real Application Security session therefore lets SELECT and DML operations return results authorized for the Real Application Security user.

Example: Assigning an Application User to an Application Session shows how to assign the application user lwuser1 to an application session.

Example: Assigning an Application User to an Application Session

DECLARE
  sessionid raw(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('XSGUEST', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.ASSIGN_USER('lwuser1');
END;

See Also:

Switching a Current Application User to Another Application User in the Current Application Session

You can switch or proxy the security context of the current application session to a newly initialized security context for a specified application user using the DBMS_XS_SESSIONS.SWITCH_USER procedure in PL/SQL or the switchUser method of the Session interface in Java. To proxy another application user, the current application session user must be set up as a proxy user for the target user before performing the switch operation. This is performed through the XS_PRINCIPAL.ADD_PROXY_USER PL/SQL API.

Switching a user changes the user session between two named users.

If the target application user of the proxy operation has a list of filtering roles (proxy roles) set up for the proxy user, they are enabled in the session.

Beginning with Oracle Database 12c Release 2 (12.2), Oracle Label Security supports Real Application Security users. This means that Oracle Label Security context of the target_user will be established on switching from the proxy_user session to the target_user session.

You can either retain or clear the application namespace and attributes after a switch operation. When the keep_state parameter is set to TRUE, all application namespaces and attributes are retained; otherwise, all previous state in the session is cleared.

If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or the ADMIN_NAMESPACE system privilege.

Example: Switching an Application User to Another Application User in the Current Application Session shows how to switch the application user lwuser1 to application user lwuser2 in the current application session. Note that namespace templates ns1 and ns2 should have already have been created by SYSDBA.

Example: Switching an Application User to Another Application User in the Current Application Session

DECLARE
  sessionid RAW(16);
  nsList DBMS_XS_NSATTRLIST;
BEGIN
  nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.SWITCH_USER(username => 'lwuser2',
                               keep_state => TRUE,
                               namespaces => nsList);
END;

See Also:

About Creating a Global Callback Event Handler Procedure

The callback event handler procedure must adhere to the prototype, which includes a specified set of arguments.

For example, the following callback_procedure specifies an existing PL/SQL procedure, which is the event handler and shows its two possible forms.

PROCEDURE callback_procedure (sessionid in raw, error out pls_integer)

This first form includes two parameters, the sessionid in RAW and the out parameter error, which is used for the purpose of setting the error. The sessionid contains the session ID of the session in which the event was triggered. The out error parameter can be used in the event handler code to display the error.

PROCEDURE callback_procedure (sessionid in raw, user in varchar2, error out pls_integer)

This second form includes an additional parameter user in VARCHAR2 to specify the user who triggered this event.

Note:

The error value must be explicitly set to a value in the PL/SQL body or in the exception block as follows, error:= 0;.

Otherwise, the following error is raised, ORA-46071: Error occured in event handler <name-of-event-handler> followed by another error, ORA-1405: fetched column value is NULL, indicating that the error value is NULL.

The following example shows the explicit setting of the error value using the second form of the callback procedure.

CREATE OR REPLACE PACKAGE CALLBACK_PACKAGE AS
PROCEDURE CALLBACK_PROCEDURE (sessionid in RAW, user in VARCHAR2, error out PLS_INTEGER);
END CALLBACK_PACKAGE;
/

CREATE OR REPLACE PACKAGE BODY CALLBACK_PACKAGE AS
PROCEDURE CALLBACK_PROCEDURE (sessionid in RAW, user in VARCHAR2, error out PLS_INTEGER) IS
BEGIN
  error := 0;
  dbms_output.put_line('Inside callback procedure');
EXCEPTION
WHEN OTHERS THEN
        error:=0;
        dbms_output.put_line('Error');
END CALLBACK_PROCEDURE;
END CALLBACK_PACKAGE;

See Also:

Configuring Global Callback Event Handlers for an Application Session

A global callback event handler is a predefined PL/SQL procedure that can be invoked to inspect, log, and modify the session state when certain session events of interest occur. You can add multiple global callback event handlers on a session event. After you create the PL/SQL procedure, you can register or deregister, or enable or disable it using these procedures, respectively:

To execute these APIs the user must have the CALLBACK application privilege. This can be obtained through the XSPROVISIONER application role or by calling the XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE API. You can configure one or more global callback event handlers for use in an application session. If you configure multiple callback event handlers, Oracle Database executes the handlers in the order in which they were created.

Optionally, you can follow these steps to change the execution order:

  1. Run the DBMS_XS_SESSIONS.DELETE_GLOBAL_CALLBACK procedure to deregister any existing callback.

  2. Run the DBMS_XS_SESSIONS.ADD_GLOBAL_CALLBACK procedure to register the callback.

Example: Registering a Global Callback in an Application Session

BEGIN
  SYS.DBMS_XS_SESSIONS.ADD_GLOBAL_CALLBACK
   (DBMS_XS_SESSIONS.CREATE_SESSION_EVENT,
   'CALLBACK_SCHM','CALLBACK_PKG','CALLBACK_PROC');
END;
/

Session Events That Can Use Callback Event Handlers lists session events that can use callback event handlers.

Session Events That Can Use Callback Event Handlers

Session Event When the Callback Will Be Executed
Creating a new application session After the session is created.
Attaching to an existing application session After the session is attached.
Enabling a dynamic application role After a dynamic application role is enabled.
Disabling a dynamic application role After a dynamic application role is disabled.
Direct login of an application session After the session is attached (if the session attach is called as part of the direct logon of an application session).
Assigning a named application user to an anonymous application session After the named user is assigned to the anonymous application session.
Proxying from one named application user to another named application user After the application user is switched (if the application user is not proxying back to the original application user).
Proxying back from a named application user to the original application user After the application user is switched (if the application user is proxying back to the original application user).
Enabling a regular application role After the application role is enabled.
Disabling a regular application role After the application role is disabled.
Detaching from an existing application session or database session Before the session is detached.
Terminating an existing application session or database session Before the session is destroyed.
Direct logoff of an application session or database session Before the session is detached (if the session detach is called as part of the direct logoff of an application session).

Suppose you want to initialize certain application-specific states after creating a session. Example: Registering a Global Callback in an Application Session shows how to register a global callback that sets up the state CALLBACK_PROC, which is defined in the package CALLBACK_PKG and owned by the schema CALLBACK_SCHM.

The state CALLBACK_PROC is registered as a global callback for the event CREATE_SESSION_EVENT.

For more examples, and for details about the syntax of these procedures, see the following:

Saving an Application Session

You can save the current user application session using the DBMS_XS_SESSIONS.SAVE_SESSION procedure in PL/SQL or the saveSession method of the XSSessionManager class in Java. Use the save operation when session changes need to be propagated immediately to other sessions using the same session as this one. If the save operation is not used, then the session changes would be reflected in other sessions only after this session is detached.

The calling user requires no privileges to perform this operation.

Example: Saving the Current User Application Session shows how to save the current user application session.

Example: Saving the Current User Application Session

BEGIN
 SYS.DBMS_XS_SESSIONS.SAVE_SESSION;
END;

See Also:

Detaching an Application Session from a Traditional Database Session

You can detach an application session from the traditional database session using either of these procedures:

Example: Detaching and Committing an Application Session shows how to detach an application session from a database session and commit the changes. Note that you can call DETACH_SESSION anywhere to detach the currently attached session.

You can use the detachSession method of the XSSessionManager class in Java.

Example: Detaching and Not Committing an Application Session shows how to detach a database session from an application session without saving any changes.

Note: When developing the application, ensure that all application end user actions are captured within an ATTACH_SESSION … DETACH_SESSION programming block. (For more information, see “Attaching an Application Session to a Traditional Database Session”)

Example: Detaching and Committing an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
...
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
...
END;

Example: Detaching and Not Committing an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
...
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION(TRUE);
END;

See Also:

Destroying an Application Session

You can terminate an application session using the DBMS_XS_SESSIONS.DESTROY_SESSION procedure in PL/SQL or using the destroySession method of the XSSessionManager class in Java. This procedure also detaches all traditional sessions from the application session.

To execute this procedure, the invoking user must have the TERMINATE_SESSION application privilege. This privilege can be obtained through the XS_SESSION_ADMIN Database role or by the XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE API call.

Example: Destroying an Application Session shows how to destroy an application session.

Example: Destroying an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;

See Also: