About Managing Real Application Security Sessions

This section describes the following topics:

• Creating a Real Application Security User Session

• Attaching an Application Session

• Assigning or Switching an Application User

• Enabling Real Application Security Application Roles

• About Performing Namespace Operations as Session User

• About Performing Miscellaneous Session-Related Activities

• Detaching an Application Session

• Destroying A Real Application Security Application Session

Creating a Real Application Security User Session

To create a Real Application Security user session, for example, lws, for the application user lwuser, use the createSession method of the XSSessionManager class (see Example: How to Create a Real Application Security Session in Java). The createSession method (in bold typeface). creates a session on the server with the specified parameters passed. A database round-trip is required to perform this operation.

To create an anonymous Real Application Security application session, use the createAnonymousSession method of the XSSessionManager class. The application user for this session is a predefined anonymous user, so no user parameter is passed in this method.

Both methods support using a cookie and a namespace.

The cookie, passed as the parameter, can be used to identify the newly created Real Application Security application session in future calls, until the cookie value is changed or the session is destroyed.

The namespace, passed as the parameter, can be used to create a namespace in the session. For details, see “About Performing Namespace Operations as Session User”.

It is possible to reassign a specific application user to take over this session. In this case, some of the state of the session for the anonymous user is still preserved. For details, see “Assigning or Switching an Application User”.

Example: How to Create a Real Application Security Session in Java

Session lws = null;
static XSSessionManager manager;
static Connection lwsConn = null;
static String user = "lwuser";
String cookie="nst";
...
lws = manager.createSession(lwsConn, user, cookie, null);
...

Attaching an Application Session

To attach an application session, use the attachSession method of the XSSessionManager class (see Example: How to Attach a Real Application Security Session in Java). The attachSession method (in bold typeface) attaches the JDBC connection to the specified Real Application Security application session object. It also enables or disables the dynamic application roles, creates namespaces of the session, and sets the authentication time.

You can also attach to a session by using either ID or cookie as shown in Example: How to Attach Using a Cookie. See Example: Attaching a Real Application Security Session for External Users for another example of attaching to a session by using a cookie.

Example: How to Attach a Real Application Security Session in Java

Session lws = null;
static Connection lwsConn = null;
static XSSessionManager manager;
static String user = "lwuser";
String cookie = "lwscookie";
List <String> edynamicRoles = new ArrayList <String>();
edynamicRoles.add("EDYNROLE001");
edynamicRoles.add("EDYNROLE002");
List <String> ddynamicRoles = new ArrayList <String>();
ddynamicRoles.add("DDYNROLE001");
ddynamicRoles.add("DDYNROLE002");
...
lws = manager.createSession(lwsConn, user, cookie, null);
manager.attachSession(lwsConn, lws, edynamicRoles, ddynamicRoles, null, new Timestamp(System.currentTimeMillis()));

Example: How to Attach Using a Cookie

Session lws = null;
static Connection lwsConn = null;
static XSSessionManager manager;
...
lws = manager.attachSessionByCookie(lwsConn, "myCookie", null, null, null, null, null);

Assigning or Switching an Application User

If you have an anonymous session, you can reassign it to another application user later. Otherwise, if your session is assigned to an application user already, you can switch the session to another application user. In either case, the session must be attached first, before assigning or switching an application user.

To assign a name to a previously anonymous application user, use the assignUser method of the XSSessionManager class (see Example: How to Assign an Application User to a Session in Java). The assignUser method (in bold typeface) changes the session context (user and roles) to the given user, for example, lwuser, but keeps the existing namespace. It can also change the session at the same time, by any given dynamic roles and namespace parameters, in the same way as the attachSession method. The associated session attributes remain in effect unless they are removed through another call.

To change a session user from a named user (non-anonymous) to another named user, use the switchUser method of the Session object.

Any request for retaining the dynamic application roles, which were assigned while attaching the session, is disabled. The dynamic application roles are retained for the new application user only when they are also included in the dynamic application roles list for the new application user. The associated session attributes remain in effect unless the session attributes list is reset.

This method changes the session context (user and roles) to the target user (see “Switching a Current Application User to Another Application User in the Current Application Session” for details about roles change), but not keeping the existing namespace by default. If you want to retain the existing namespace, you can use the switchUserKeepState method of the Session object. It can also change the session at the same time, by any given dynamic roles and namespace parameters, in the same way as the attachSession method.

Example: How to Switch an Application User in a Session in Java demonstrates how to switch the application user from lwuser to lwuser1. The switchUser method is in bold typeface.

Example: How to Assign an Application User to a Session in Java

Session lws = null;
static XSSessionManager manager;
static String user = "lwuser";
...
manager.assignUser(lws, user, null, null, null, new Timestamp(System.currentTimeMillis()));

Example: How to Switch an Application User in a Session in Java

Session lws = null;
Vector<String> listOfNamespaces;
static String user = "lwuser";
List<String> nslist1 = new ArrayList<String>();
...
manager.assignUser(lws, user, nslist1, nslist2, nslist3, new Timestamp(System.currentTimeMillis()));
...
lws.switchUser("lwuser1",listOfNamespaces);

Enabling Real Application Security Application Roles

A Real Application Security application role is a role that can be granted only to a Real Application Security application user or to another Real Application Security application role. Real Application Security application roles are granted database privileges through database roles. The database privileges are granted to a database role, which in turn is granted to a Real Application Security application role. For more information about Real Application Security application users and application roles, refer to “Principals: Users and Roles”.

This section describes the following operation associated with application roles:

• Enabling a Real Application Security Application Role

• Disabling a Real Application Security Application Role

• Checking If a Real Application Security Application Role Is Enabled

Enabling a Real Application Security Application Role

To enable a Real Application Security application role granted to the current application user for the session, use the enableRole method of the Session interface (see Example: How to Enable a Real Application Security Application Role in Java).

The enableRole method (in bold typeface) has no effect if the particular application role is currently disabled. This operation requires a database round-trip.

Example: How to Enable a Real Application Security Application Role in Java

static Session lws;
static Roles r1;
...
r1=new Role("HROLE1",null,0);
lws.enableRole(r1);

Disabling a Real Application Security Application Role

To disable a Real Application Security application role granted to the current user for the session, use the disableRole method of the Session interface (see Example: How to Disable a Real Application Security Application Role in Java). This operation requires a database round-trip. The disableRole method is in bold typeface.

Example: How to Disable a Real Application Security Application Role in Java

static Session lws;
static Roles r1;
...
r1=new Role("HROLE1",null,0);
lws.enableRole(r1);
...
lws.disableRole(r1);

Checking If a Real Application Security Application Role Is Enabled

To test if the specified application role is enabled in the Real Application Security application session, use the isRoleEnabled method of the Session interface (see Example: How to Test If a Real Application Security Application Role Is Enabled in Java). The isRoleEnabled method is in bold typeface.

This method does not have an associated database operation. You must have the administerSession Real Application Security application privilege to call this method.

Example: How to Test If a Real Application Security Application Role Is Enabled in Java

static Session lws;
...
lws.enableRole("HROLE1");
...
boolean b = lws.isRoleEnabled("HROLE1");

About Performing Namespace Operations as Session User

A namespace is a group of additional attributes of the session context. An application uses a namespace to store application defined attribute-value pairs. The current session user should have MODIFY_NAMESPACE (for namespace) and MODIFY_ATTRIBUTE (for attribute) application privileges. For more information about namespaces, refer to “About Using Namespace Templates to Create Namespaces”.

This section describes how to perform the following activities:

• Creating Namespaces

• Deleting Namespaces

• Implicitly Creating Namespaces

• About Using Namespace Attributes

Creating Namespaces

To create a namespace in Java, use the createNamespace method of the Session interface (see Example: How to Create a Namespace in Java). The createNamespace method (in bold typeface) creates a new session namespace using the namespace template document, whose name matches with the specified name. If an event handler is specified in the template document, then the specified event handler applies to all the namespaces created using that template.

Note: You can also create a namespace by passing a namespace name as a parameter with the createSession and attachSession methods discussed in the previous sections.

Example: How to Create a Namespace in Java

Session lws = null;
...
SessionNamespace ns = lws.createNamespace("TESTNS1");

Deleting Namespaces

To delete a namespace in Java, use the deleteNamespace method of the Session interface (see Example: How to Delete a Namespace in Java). The deleteNamespace method (in bold typeface) removes a namespace from a session.

Example: How to Delete a Namespace in Java

Session lws = null;
...
SessionNamespace ns = lws.createNamespace("TESTNS1");
...
lws.deleteNamespace("TESTNS1");

Implicitly Creating Namespaces

To implicitly create the namespace object to represents the session namespace, use the getNamespace method of the Session interface (see Example: How to Implicitly Create the Namespace in Java). The getNamespace method is in bold typeface. If the namespace specified already exists, an error is thrown.

To retrieve a String representation of the namespace, use the toString method of the SessionNamespace interface.

Example: How to Implicitly Create the Namespace in Java

Session lws = null;
...
SessionNamespace ns2 = lws.getNamespace("TESTNS1");

About Using Namespace Attributes

A session namespace manages the attributes that a single application module stores for the duration of the session. The session namespace stores the attributes in a single namespace, a single set of access control restrictions, or a single event handler procedure that dispatches the attribute change events for that namespace.

This section describes how to perform the following activities:

• Creating a Session Namespace Attribute

• About Setting a Session Namespace Attribute

• Getting a Session Namespace Attribute

• Listing Attributes

• Resetting Attributes

• Deleting Attributes

Creating a Session Namespace Attribute

To create a session namespace attribute in Java, use the createAttribute method of the SessionNamespace interface (see Example: How to Create a Session Namespace Attribute in Java). The createAttribute method (in bold typeface) creates a new attribute in the namespace.

Example: How to Create a Session Namespace Attribute in Java

String name1="empid';
String value1="JB007";
SessionNamespace ns;
...
SessionNamespaceAttribute sa1=ns.createAttribute(name1,value1);
...

About Setting a Session Namespace Attribute

To set a session namespace attribute in Java, use the setAttribute method of the SessionNamespace interface.

Getting a Session Namespace Attribute

To retrieve a session namespace attribute in Java, use the getAttribute method of the SessionNamespace interface (see Example: How to Retrieve a Session Namespace Attribute in Java). The getAttribute method (in bold typeface) returns the attribute whose name is specified as the parameter.

Example: How to Retrieve a Session Namespace Attribute in Java

String name="empid';
String value="JB007";
SessionNamespace ns;
...
SessionNamespaceAttribute sa=ns.createAttribute(name,value);
...
String attrvalue =  ns.getAttribute("empid").getValue();
ns.getAttribute("empid").setValue("newValue");
...

Listing Attributes

To list the attributes in the namespace, use the listAttributes method of the SessionNamespace interface (see Example: How to List Attributes in Java). The listAttributes method (in bold typeface) returns a collection of the attribute names in the namespace

Example: How to List Attributes in Java

String name1="empid';
String value1="JB007";
SessionNamespace ns;
...
SessionNamespaceAttribute sa1=ns.createAttribute(name1,value1);
...
for (Enumeration e = ns.listAttributes() ; e.hasMoreElements() ;) {
 System.out.println("   -- " + e.nextElement());
}
...

Resetting Attributes

To reset an attribute in Java, use the resetAttribute method of the SessionNamespace interface (see Example: How to Reset an Attribute in Java). The resetAttribute method (in bold typeface) resets the attribute in the namespace to its default value.

Example: How to Reset an Attribute in Java

String name1="empid';
String value1="JB007";
SessionNamespace ns;
...
SessionNamespaceAttribute sa1=ns.createAttribute(name1,value1);
...
ns.resetAttribute("empid");
...

Deleting Attributes

To delete an attribute in Java, use the deleteAttribute method of the SessionNamespace interface (see Example: How to Delete an Attribute in Java). The deleteAttribute method (in bold typeface) deletes the particular attribute in the namespace.

Example: How to Delete an Attribute in Java

String name1="empid';
String value1="JB007";
SessionNamespace ns;
...
SessionNamespaceAttribute sa1=ns.createAttribute(name1,value1);
...
ns.deleteAttribute("empid");
...

About Performing Namespace Operations as Session Manager

Each namespace has an associated ACL to determine who can manipulate the namespace and its attributes. If an application does not want the current session user to manipulate the namespace, but allows a session manager to do it, this can be done as session manager XSSessionManager.

XSSessionManager has a set of overloaded methods as Session, to manage the namespace. The usage is similar to that described for session user in “About Performing Namespace Operations as Session User”.

Note that the session manager instance XSSessionManager may not be available to the application code; only the trusted infrastructure layer can use the session manager to manipulate such a secured namespace.

About Performing Miscellaneous Session-Related Activities

This section describes the following topics:

• About Getting the Oracle Connection Associated with the Session

• About Getting the Application User ID for the Session

• Getting the Session ID for the Session

• About Getting a String Representation of the Session

• Getting the Session Cookie

• Setting Session Inactivity Timeout as Session Manager

• Setting the Session Cookie as Session Manager

About Getting the Oracle Connection Associated with the Session

To get the Oracle connection associated with the session, if it is currently bound to one, use the getConnection method of the Session interface.

About Getting the Application User ID for the Session

To get the application user identifier (ID) for a particular session, use the getUserId method of the Session interface.

To check if the application user for the session is anonymous, use the isAnonymous method of the Session interface.

Getting the Session ID for the Session

To get the session identifier (ID) for a particular session, use the getId method of the Session interface (see Example: How to Get the Session ID for the Session in Java). The getId method is in bold typeface.

Example: How to Get the Session ID for the Session in Java

Session lws=null;
...
System.out.println( "The Session ID is" +  lws.getId());

About Getting a String Representation of the Session

To get a String representation of the session, use the toString method of the Session interface.

Getting the Session Cookie

To get the secure session cookie used for the session, use the getSessionCookie method of the Session interface (see Example: How to Get the Secure Session Cookie in Java). The getSessionCookie method is in bold typeface.

Example: How to Get the Secure Session Cookie in Java

static Session lws;
...
System.out.println(lws.getSessionCookie());

Setting Session Inactivity Timeout as Session Manager

To set the timeout on the session, use the setInactivityTimeout method of the SessionManager interface. This method sets the session timeout in minutes.

The setInactivityTimeout method overrides the normal session timeout configuration. The method is:

sessionManager.setInactivityTimeout(Session session, int minutes);

Setting the Session Cookie as Session Manager

To set the secure session cookie used for the session, use the setCookie method of the SessionManager interface (see Example: How to Set the Secure Session Cookie in Java). The setCookie method (in bold typeface) returns the secure session cookie used for this session. The method is:

sessionManager.setCookie(lws,"newCookieValue");

Example: How to Set the Secure Session Cookie in Java

static XSSessionManager manager;
...
manager.sessionManager.setCookie(lws,"chocolate chip");

Detaching an Application Session

To detach a Real Application Security application session in Java, use the detachSession method of the XSSessionManager class (see Example: How to Detach a Real Application Security Session in Java). The detachSession method (in bold typeface) detaches the session whose object it accepts as a parameter. The detachSession method call commits all changes in the request at the database level. A database round-trip is required to perform this operation.

Example: How to Detach a Real Application Security Session in Java

Session lws = null;
static XSSessionManager manager;
static Connection lwsConn = null;
static String user = "lwuser";
String cookie;
...
lws = manager.createSession(lwsConn, user, cookie, null);
manager.attachSession(lwsConn, lws, null, null, null, new Timestamp(System.currentTimeMillis()));
...
manager.detachSession(lws);
...

Destroying A Real Application Security Application Session

To destroy a Real Application Security application session in Java, use the destroySession method of the XSSessionManager class (see Example: How to Destroy a Real Application Security Session in Java). The destroySession method (in bold typeface) accepts the database connection object and a session object as parameters. After you call this method, the destroyed session can no longer be accessed from any JVM. A database round-trip is required to perform this operation and for create session as well.

Example: How to Destroy a Real Application Security Session in Java

Session lws = null;
static Connection lwsConn = null;
static XSSessionManager manager;
static String user = "lwuser";
String cookie;
...
lws = manager.createSession(lwsConn, user, cookie, null);
manager.attachSession(lwsConn, lws, null, null, null, new Timestamp(System.currentTimeMillis()));
...
manager.detachSession(lws);
manager.destroySession(lwsConn, lws);
...