6 Using Application Contexts to Retrieve User Information

About the Package That Manages the Database Session-Based Application Context

The PL/SQL package, usually created in the schema of the security administrator, defines procedures that manage the session data represented by the application context. It must perform the following tasks:

• Retrieve session information. To retrieve the user session information, you can use the SYS_CONTEXT SQL function. The SYS_CONTEXT function returns the value of the parameter associated with the context namespace. You can use this function in both SQL and PL/SQL statements. Typically, you will use the built-in USERENV namespace to retrieve the session information of a user. (For detailed information about the SYS_CONTEXT function, see Oracle Database SQL Language Reference.)

• Set the name-value attributes of the application context you created with CREATE CONTEXT. You can use the DBMS_SESSION.SET_CONTEXT procedure to set the name-value attributes of the application context. The name-value attributes can hold information such as the user ID, IP address, authentication mode, the name of the application, and so on. The values of the attributes you set remain either until you reset them, or until the user ends the session. Note the following:

  • If the value of the parameter in the namespace already has been set, then SET_CONTEXT overwrites this value.

  • Be aware that any changes in the context value are reflected immediately and subsequent calls to access the value through the SYS_CONTEXT function will return the most recent value.

• Be executed by users. After you create the package, the user will need to execute the package when he or she logs on. You can create a logon trigger to execute the package automatically when the user logs on, or you can embed this functionality in your applications. Remember that the application context session values are cleared automatically when the user ends the session, so you do not need to manually remove the session data.

It is important to remember that the procedure is a trusted procedure: It is designed to prevent the user from setting his or her own application context attribute values. The user runs the procedure, but the procedure sets the application context values, not the user.

"Tutorial: Creating and Using a Database Session-Based Application Context" shows how to create a database session-based application context.

Using SYS_CONTEXT to Retrieve Session Information

The syntax for the PL/SQL function SYS_CONTEXT is as follows:

SYS_CONTEXT ('namespace','parameter'[,length])

In this specification:

• namespace: The name of the application context. You can specify either a string or an expression that evaluates to a string. The SYS_CONTEXT function returns the value of parameter associated with the context namespace at the current instant. If the value of the parameter in the namespace already has been set, then SET_CONTEXT overwrites this value.

• parameter: A parameter within the namespace application context. This value can be a string or an expression.

• length: Optional. The default maximum size of the return type is 256 bytes, but you can override the length by specifying a value up to 4000 bytes. Enter a value that is a NUMBER data type, or a value that can be can be implicitly converted to NUMBER. The data type of the SYS_CONTEXT return type is a VARCHAR2.

The SYS_CONTEXT function provides a default namespace, USERENV, which describes the current session of the user logged on. You can use SYS_CONTEXT to retrieve different types of session-based information about a user, such as the user host computer ID, host IP address, operating system user name, and so on. Remember that you only use USERENV to retrieve session data, not set it. The predefined attributes are listed in the description for the PL/SQL function in the Oracle Database SQL Language Reference.

For example, to retrieve the name of the host computer to which a client is connected, you can use the HOST parameter of USERENV as follows:

SYS_CONTEXT ('userenv','host')

You can check the SYS_CONTEXT settings by issuing a SELECT SQL statement on the DUAL table. The DUAL table is a small table in the data dictionary that Oracle Database and user-written programs can reference to guarantee a known result. This table has one column called DUMMY and one row that contains the value X.

Example 6-2 demonstrates how to find the host computer on which you are logged, assuming that you are logged on to the SHOBEEN_PC host computer under EMP_USERS.

SELECT SYS_CONTEXT ('USERENV', 'HOST') FROM DUAL;

SYS_CONTEXT(USERENV,HOST)
-------------------------
EMP_USERS\SHOBEEEN_PC

Using Dynamic SQL with SYS_CONTEXT

During a session in which you expect a change in policy between executions of a given query, the query must use dynamic SQL. You must use dynamic SQL because static SQL and dynamic SQL parse statements differently:

• Static SQL statements are parsed at compile time. They are not parsed again at execution time for performance reasons.

• Dynamic SQL statements are parsed every time they are executed.

Consider a situation in which Policy A is in force when you compile a SQL statement, and then you switch to Policy B and run the statement. With static SQL, Policy A remains in force. Oracle Database parses the statement at compile time, but does not parse it again upon execution. With dynamic SQL, Oracle Database parses the statement upon execution, then the switch to Policy B takes effect.

For example, consider the following policy:

EMPLOYEE_NAME = SYS_CONTEXT ('USERENV', 'SESSION_USER')

The policy EMPLOYEE_NAME matches the database user name. It is represented in the form of a SQL predicate in Oracle Virtual Private Database: the predicate is considered a policy. If the predicate changes, then the statement must be parsed again to produce the correct result.

Using SYS_CONTEXT in a Parallel Query

If you use SYS_CONTEXT inside a SQL function that is embedded in a parallel query, then the function includes the application context.

Consider a user-defined function within a SQL statement, which sets the user ID to 5:

CREATE FUNCTION set_id 
 RETURN NUMBER IS
BEGIN
 IF SYS_CONTEXT ('hr', 'id') = 5
   THEN RETURN 1; ELSE RETURN 2;
 END IF;
END;

Now consider the following statement:

SELECT * FROM emp WHERE set_id( ) = 1;

When this statement is run as a parallel query, the user session, which contains the application context information, is propagated to the parallel execution servers (query child processes).

Using SYS_CONTEXT with Database Links

When SQL statements within a user session involve database links, then Oracle Database runs the SYS_CONTEXT SQL function at the host computer of the database link, and then captures the context information there (at the host computer).

If remote PL/SQL procedure calls are run on a database link, then Oracle Database runs any SYS_CONTEXT function inside such a procedure at the destination database of the link. In this case, only externally initialized application contexts are available at the database link destination site. For security reasons, Oracle Database propagates only the externally initialized application context information to the destination site from the initiating database link site.

Using DBMS_SESSION.SET_CONTEXT to Set Session Information

After you have used the SYS_CONTEXT function to retrieve the session data of a user, you are ready to set the application context values from the session of this user. To do so, use the DBMS_SESSION.SET_CONTEXT procedure. (Ensure that you have the EXECUTE privilege for the DBMS_SESSION PL/SQL package.)

Its syntax is as follows:

DBMS_SESSION.SET_CONTEXT (
   namespace VARCHAR2,
   attribute VARCHAR2,
   value     VARCHAR2,
   username  VARCHAR2,
   client_id VARCHAR2);

In this specification:

• namespace: The namespace of the application context to be set, limited to 30 bytes. For example, if you were using a namespace called custno_ctx, you would specify it as follows:

  namespace => 'custno_ctx',
  

• attribute: The attribute of the application context to be set, limited to 30 bytes. For example, to create the ctx_attrib attribute for the custno_ctx namespace:

  attribute => 'ctx_attrib',
  

• value: The value of the application context to be set, limited to 4000 bytes. Typically, this is the value retrieved by the SYS_CONTEXT function and stored in a variable. For example:

  value => ctx_value,
  

• username: Optional. The database user name attribute of the application context. The default is NULL, which permits any user to access the session. For database session-based application contexts, omit this setting so that it uses the NULL default.

  The username and client_id parameters are used for globally accessed application contexts. See "Setting the DBMS_SESSION.SET_CONTEXT username and client_id Parameters" for more information.

• client_id: Optional. The application-specific client_id attribute of the application context (64-byte maximum). The default is NULL, which means that no client ID is specified. For database session-based application contexts, omit this setting so that it uses the NULL default.

See Oracle Database PL/SQL Packages and Types Reference for detailed information about the DBMS_SESSION package.

For example, remember the application context created in Example 6-1:

CREATE CONTEXT empno_ctx USING set_empno_ctx_proc;

Example 6-3 shows how to create a simple procedure that creates an attribute for the empno_ctx application context.

1
2
3
4
5
6
7

CREATE OR REPLACE PROCEDURE set_empno_ctx_proc(
  emp_value IN VARCHAR2)
 IS   
 BEGIN
  DBMS_SESSION.SET_CONTEXT('empno_ctx', 'empno_attrib', emp_value);
 END; 
/

In this example:

• Line 2: Takes emp_value as the input parameter. This parameter specifies the value associated with the application context attribute empno_attrib. Its limit is 4000 bytes.

• Line 5: Sets the value of the application context by using the DBMS_SESSION.SET_CONTEXT procedure:

  • 'empno_ctx': Refers to the application context namespace. Enclose its name in single quotation marks.

  • 'empno_attrib': Creates the attribute associated with the application context namespace.

  • emp_value: Specifies the value for the empno_attrib attribute. Here, it refers to the emp_value parameter defined in Line 2.

At this stage, you can run the set_empno_ctx_proc procedure to set the application context:

EXECUTE set_empno_ctx_proc ('42783');

(In a real world scenario, you would set the application context values in the procedure itself, so that it becomes a trusted procedure. This example is only used to show how data can be set for demonstration purposes.)

To check the application context setting, run the following SELECT statement:

SELECT SYS_CONTEXT ('empno_ctx', 'empno_attrib') empno_attrib FROM DUAL;

EMPNO_ATTRIB
--------------
42783

You can also query the SESSION_CONTEXT data dictionary view to find all the application context settings in the current session of the database instance. For example:

SELECT * FROM SESSION_CONTEXT;

NAMESPACE                ATTRIBUTE          VALUE
--------------------------------------------------
EMPNO_CTX                EMP_ID             42783

About This Tutorial

This tutorial shows how to create an application context that checks the employee ID of any database user who tries to log in to the database.

Step 1: Create User Accounts and Ensure the User SCOTT Is Active

1. Log on as user SYS and connect using the AS SYSDBA privilege.

   sqlplus sys as sysdba
   Enter password: password
   

2. Create the sysadmin_ctx account, who will administer the database session-based application context.

   GRANT CREATE SESSION, CREATE ANY CONTEXT, CREATE PROCEDURE, CREATE TRIGGER, ADMINISTER DATABASE TRIGGER TO sysadmin_ctx IDENTIFIED BY password;
   GRANT SELECT ON HR.EMPLOYEES TO sysadmin_ctx;
   GRANT EXECUTE ON DBMS_SESSION TO sysadmin_ctx;
   

   Replace password with a password that is secure. See "Minimum Requirements for Passwords" for more information.

3. Create the following user account for Lisa Ozer, who is listed as having lozer for her e-mail account in the HR.EMPLOYEES table.

   GRANT CREATE SESSION TO LOZER IDENTIFIED BY password;
   

   Replace password with a password that is secure. See "Minimum Requirements for Passwords" for more information.

4. The sample user SCOTT will also be used in this tutorial, so query the DBA_USERS data dictionary view to ensure that SCOTT is not locked or expired.

   SELECT USERNAME, ACCOUNT_STATUS FROM DBA_USERS WHERE USERNAME = 'SCOTT';
   

   If the DBA_USERS view lists user SCOTT as locked and expired, then enter the following statement to unlock the SCOTT account and create a new password for him:

   ALTER USER SCOTT ACCOUNT UNLOCK IDENTIFIED BY password;
   

   Enter a password that is secure. For greater security, do not give the SCOTT account the same password from previous releases of Oracle Database. See "Minimum Requirements for Passwords" for the minimum requirements for creating passwords.

Step 2: Create the Database Session-Based Application Context

1. Log on to SQL*Plus as sysadmin_ctx.

   CONNECT sysadmin_ctx
   Enter password: password
   

2. Create the application context using the following statement:

   CREATE CONTEXT empno_ctx USING set_empno_ctx_pkg;
   

   Remember that even though user sysadmin_ctx has created this application context, the SYS schema owns the context.

Step 3: Create a Package to Retrieve Session Data and Set the Application Context

Example 6-7 shows how to create the package you need to retrieve the session data and set the application context. Before creating the package, ensure that you are still logged on as user sysadmin_ctx. (You can copy and paste this text by positioning the cursor at the start of CREATE OR REPLACE in the first line.)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

CREATE OR REPLACE PACKAGE set_empno_ctx_pkg IS 
   PROCEDURE set_empno; 
 END; 
 /
 CREATE OR REPLACE PACKAGE BODY set_empno_ctx_pkg IS
   PROCEDURE set_empno 
   IS 
    emp_id HR.EMPLOYEES.EMPLOYEE_ID%TYPE;
   BEGIN 
    SELECT EMPLOYEE_ID INTO emp_id FROM HR.EMPLOYEES 
       WHERE email = SYS_CONTEXT('USERENV', 'SESSION_USER');
    DBMS_SESSION.SET_CONTEXT('empno_ctx', 'employee_id', emp_id);
   EXCEPTION  
    WHEN NO_DATA_FOUND THEN NULL;
  END;
 END;
/

This package creates a procedure called set_empno that performs the following actions:

• Line 8: Declares a variable, emp_id, to store the employee ID for the user who logs on. It uses the same data type as the EMPLOYEE_ID column in HR.EMPLOYEES.

• Line 10: Performs a SELECT statement to copy the employee ID that is stored in the employee_id column data from the HR.EMPLOYEES table into the emp_id variable.

• Line 11: Uses a WHERE clause to find all employee IDs that match the e-mail account for the session user. The SYS_CONTEXT function uses the predefined USERENV context to retrieve the user session ID, which is the same as the email column data. For example, the user ID and e-mail address for Lisa Ozer are both the same: lozer.

• Line 12: Uses the DBMS_SESSION.SET_CONTEXT procedure to set the application context:

  • 'empno_ctx': Calls the application context empno_ctx. Enclose empno_ctx in single quotes.

  • 'employee_id': Creates the attribute value of the empno_ctx application context name-value pair, by naming it employee_id. Enclose employee_id in single quotes.

  • emp_id: Sets the value for the employee_id attribute to the value stored in the emp_id variable. The emp_id variable was created in Line 8 and the employee ID was retrieved in Lines 10–11.

  To summarize, the set_empno_ctx_pkg.set_empno procedure says, "Get the session ID of the user and then match it with the employee ID and e-mail address of any user listed in the HR.EMPLOYEES table."

• Lines 13–14: Add a WHEN NO_DATA_FOUND system exception to catch any no data found errors that may result from the SELECT statement in Lines 10–11. Without this exception, the package and logon trigger will work fine and set the application context as needed, but then any non-system administrator users other than the users listed in the HR.EMPLOYEES table will not be able to log in to the database. Other users should be able to log in to the database, assuming they are valid database users. Once the application context information is set, then you can use this session information as a way to control user access to a particular application.

Step 4: Create a Logon Trigger for the Package

As user sysadmin_ctx, create the following trigger:

CREATE TRIGGER set_empno_ctx_trig AFTER LOGON ON DATABASE
 BEGIN
  sysadmin_ctx.set_empno_ctx_pkg.set_empno;
 END;
/

Step 5: Test the Application Context

1. Log on as user lozer.

   CONNECT lozer
   Enter password: password
   

   When user lozer logs on, the empno_ctx application context collects her employee ID. You can check it as follows:

   SELECT SYS_CONTEXT('empno_ctx', 'employee_id') emp_id FROM DUAL;
   

   The following output should appear:

   EMP_ID
   --------------------------------------------------------
   168
   

2. Log on as user SCOTT.

   CONNECT SCOTT
   Enter password: password
   

   User SCOTT is not listed as an employee in the HR.EMPLOYEES table, so the empno_ctx application context cannot collect an employee ID for him.

   SELECT SYS_CONTEXT('empno_ctx', 'employee_id') emp_id FROM DUAL;
   

   The following output should appear:

   EMP_ID
   --------------------------------------------------------
   

From here, the application can use the user session information to determine how much access the user can have in the database. You can use Oracle Virtual Private Database to accomplish this. See Chapter 7, "Using Oracle Virtual Private Database to Control Data Access," for more information.

Step 6: Remove the Components for This Tutorial

1. Log on as SYS and connect using AS SYSDBA.

   CONNECT SYS/AS SYSDBA
   Enter password: password
   

2. Drop the users sysadmin_ctx and lozer:

   DROP USER sysadmin_ctx CASCADE;
   DROP USER lozer;
   

3. Drop the application context.

   DROP CONTEXT empno_ctx;
   

   Remember that even though sysadmin_ctx created the application context, it is owned by the SYS schema.

4. If you want, lock and expire SCOTT, unless other users want to use this account:

   ALTER USER SCOTT PASSWORD EXPIRE ACCOUNT LOCK; 
   

Obtaining Default Values from Users

Sometimes you need the default values from users. Initially, these default values may be hints or preferences, and then after validation, they become trusted contexts. Similarly, it may be more convenient for clients to initialize some default values, and then rely on a login event trigger or applications to validate the values.

For job queues, the job submission routine records the context being set at the time the job is submitted, and restores it when executing the batched job. To maintain the integrity of the context, job queues cannot bypass the designated PL/SQL package to set the context. Rather, the externally initialized application context accepts initialization of context values from the job queue process.

Automatic propagation of context to a remote session may create security problems. Developers or administrators can effectively handle the context that takes default values from resources other than the designated PL/SQL procedure by using logon triggers to reset the context when users log in.

Obtaining Values from Other External Resources

You can create an application context that accepts the initialization of attributes and values through external resources. Examples include an OCI interface, a job queue process, or a database link.

Externally initialized application contexts provide the following features:

• For remote sessions, automatic propagation of context values that are in the externally initialized application context namespace

• For job queues, restoration of context values that are in the externally initialized application context namespace

• For OCI interfaces, a mechanism to initialize context values that are in the externally initialized application context namespace

Although any client program that is using Oracle Call Interface can initialize this type of namespace, you can use login event triggers to verify the values. It is up to the application to interpret and trust the values of the attributes.

Example 6-8 shows how to create a database session-based application context that obtains values from an external source.

CREATE CONTEXT ext_ctx USING ext_ctx_pkg INITIALIZED EXTERNALLY;

Initializing Application Context Values from a Middle-Tier Server

Middle-tier servers can initialize application context values on behalf of database users. Context attributes are propagated for the remote session at initialization time, and the remote database accepts the values if the namespace is externally initialized.

For example, a three-tier application creating lightweight user sessions through OCI or JDBC/OCI can access the PROXY_USER attribute in USERENV. This attribute enables you to determine if the user session was created by a middle-tier application. You could allow a user to access data only for connections where the user is proxied. If users connect directly to the database, then they would not be able to access any data.

You can use the PROXY_USER attribute from the USERENV namespace within Oracle Virtual Private Database to ensure that users only access data through a particular middle-tier application. For a different approach, you can develop a secure application role to enforce your policy that users access the database only through a specific proxy.

About Initializing Database Session-Based Application Contexts Globally

You can use a centralized location to store the database session-based application context of the user. This enables applications to set up a user context during initialization based upon user identity. In particular, this feature supports Oracle Label Security labels and privileges. Initializing an application context globally makes it easier to manage contexts for large numbers of users and databases.

For example, many organizations want to manage user information centrally, in an LDAP-based directory. Enterprise User Security, a feature of Oracle Advanced Security, supports centralized user and authorization management in Oracle Internet Directory. However, there may be additional attributes an application must retrieve from Lightweight Directory Access Protocol (LDAP) to use for Oracle Virtual Private Database enforcement, such as the user title, organization, or physical location. Initializing an application context globally enables you to retrieve these types of attributes.

Using Database Session-Based Application Contexts with LDAP

An application context that is initialized globally uses LDAP, a standard, extensible, and efficient directory access protocol. The LDAP directory stores a list of users to which this application is assigned. Oracle Database uses a directory service, typically Oracle Internet Directory, to authenticate and authorize enterprise users.

The orclDBApplicationContext LDAP object (a subclass of groupOfUniqueNames) stores the application context values in the directory. The location of the application context object is described in Figure 6-1, which is based on the Human Resources example.

On the LDAP side, an internal C function is required to retrieve the orclDBApplicationContext value, which returns a list of application context values to the database. In this example, HR is the namespace; Title and Project are the attributes; and Manager and Promotion are the values.

Figure 6-1 Location of Application Context in LDAP Directory Information Tree

Description of "Figure 6-1 Location of Application Context in LDAP Directory Information Tree"

How Globally Initialized Database Session-Based Application Contexts Work

To use a globally initialized secure application, you need to first configure Enterprise User Security, a feature of Oracle Advanced Security. Then, you set up the application context values for the user in the database and the directory.

When a global user (enterprise user) connects to the database, Enterprise User Security verifies the identity of the user connecting to the database. After authentication, the global user roles and application context are retrieved from the directory. When the user logs on to the database, the global roles and initial application context are already set.

Example of Initializing a Database Session-Based Application Context Globally

You can configure and store the initial application context for a user, such as the department name and title, in the LDAP directory. The values are retrieved during user login so that the context is set properly. In addition, any information related to the user is retrieved and stored in the SYS_USER_DEFAULTS application context namespace. The following procedure shows how this is accomplished:

1. Create the application context in the database.

   CREATE CONTEXT hr USING hrapps.hr_manage_pkg INITIALIZED GLOBALLY;
   

2. Create and add new entries in the LDAP directory.

   An example of the entries added to the LDAP directory follows. These entries create an attribute named Title with the attribute value Manager for the application (namespace) HR, and assign user names user1 and user2. In the following, cn=example refers to the name of the domain.

   dn: cn=OracleDBAppContext,cn=example,cn=OracleDBSecurity,cn=Products,cn=OracleContext,ou=Americas,o=oracle,c=US
   changetype: add
   cn: OracleDBAppContext
   objectclass: top
   objectclass: orclContainer
   
   dn: cn=hr,cn=OracleDBAppContext,cn=example,cn=OracleDBSecurity,cn=Products,cn=OracleContext,ou=Americas,o=oracle,c=US
   changetype: add
   cn: hr
   objectclass: top
   objectclass: orclContainer
   
   dn: cn=Title,cn=hr, cn=OracleDBAppContext,cn=example,cn=OracleDBSecurity,cn=Products,cn=OracleContext,ou=Americas,o=oracle,c=US
   changetype: add
   cn: Title
   objectclass: top
   objectclass: orclContainer
   
   dn: cn=Manager,cn=Title,cn=hr, cn=OracleDBAppContext,cn=example,cn=OracleDBSecurity,cn=Products,cn=OracleContext,ou=Americas,o=oracle,c=US
   cn: Manager
   objectclass: top
   objectclass: groupofuniquenames
   objectclass: orclDBApplicationContext
   uniquemember: CN=user1,OU=Americas,O=Oracle,L=Redwoodshores,ST=CA,C=US
   uniquemember: CN=user2,OU=Americas,O=Oracle,L=Redwoodshores,ST=CA,C=US
   

3. If an LDAP inetOrgPerson object entry exists for the user, then the connection retrieves the attributes from inetOrgPerson, and assigns them to the namespace SYS_LDAP_USER_DEFAULT. The following is an example of an inetOrgPerson entry:

   dn: cn=user1,ou=Americas,O=oracle,L=redwoodshores,ST=CA,C=US
   changetype: add
   objectClass: top
   objectClass: person
   objectClass: organizationalPerson
   objectClass: inetOrgPerson
   cn: user1
   sn: One
   givenName: User
   initials: UO
   title: manager, product development
   uid: uone
   mail: uone@us.example.com
   telephoneNumber: +1 650 555 0105
   employeeNumber: 00001
   employeeType: full time
   

4. Connect to the database.

   When user1 connects to a database that belongs to the example domain, user1 will have his Title set to Manager. Any information related to user1 will be retrieved from the LDAP directory. The value can be obtained using the following syntax:

   SYS_CONTEXT('namespace','attribute name') 
   

   For example:

   DECLARE 
    tmpstr1 VARCHAR2(30);
    tmpstr2 VARCHAR2(30);
   BEGIN
    tmpstr1 = SYS_CONTEXT('HR','TITLE);
    tmpstr2 = SYS_CONTEXT('SYS_LDAP_USER_DEFAULT','telephoneNumber');
    DBMS_OUTPUT.PUT_LINE('Title is ' || tmpstr1);
    DBMS_OUTPUT.PUT_LINE('Telephone Number is ' || tmpstr2);
   END;
   

   The output of this example is:

   Title is Manager
   Telephone Number is +1 650 555 0105
   

About the Package That Manages the Global Application Context

The task of the PL/SQL package that you associate with a global application context is to use the DBMS_SESSION package to set and clear the global application context values. You must have the EXECUTE privilege for the DBMS_SESSION package before you use its procedures. Typically, you create and store this package in the database schema of a security administrator. The SYS schema owns the DBMS_SESSION package.

Unlike PL/SQL packages used to set a local application context, you do not include a SYS_CONTEXT function to get the user session data. You do not need to include this function because the owner of the session, recorded in the USERENV context, is the same for every user who is connecting.

You can run the procedures within the PL/SQL package for a global application context at any time. You do not need to create logon and logoff triggers to execute the package procedures associated with the global application context. A common practice is to run the package procedures from within the database application. Additionally, for nondatabase users, you use middle-tier applications to get and set client session IDs.

How Editions Affects the Results of a Global Application Context PL/SQL Package

You can control the behavior of a global application context package—and for packages used for Oracle Virtual Private Database and fine-grained audit policies, as well—across multiple editions, as follows:

• Have the PL/SQL package results be the same across all editions. To do so, create the package in the schema of a user who has not been editions enabled. To find users who are not editions enabled, you can query the DBA_USERS and USER_USERS data dictionary views. Remember that SYS, SYSTEM, and other default Oracle Database administrative accounts that are listed in the DBA_REGISTRY data dictionary view are not and cannot be editions enabled.

• Have the PL/SQL package results depend on the current state of the edition in which the package is run. Here, the results may be different across all editions to which the package applies. In this case, create the package in the schema of a user who has been editions enabled. If the schema is editions enabled, then it is likely that there will be different actual copies of the package in different editions, where each copy has different behavior. This is useful for the following types of scenarios:

  • The package must use a new application context.

  • The package must encode input values using a different scheme.

  • The package must apply different validation rules for users logging in to the database.

  For PL/SQL packages that set a global application context, use a single getter function to wrap the primitive SYS_CONTEXT calls that will read the key-value application context pairs. You can put this getter function in the same package as the application context setter procedure. This approach lets you tag the value for the application context key to reflect a relevant concept. For example, the tag can be the edition in which the setter function is actual. Or, it can be the current edition of the session that set the context, which you can find by using SYS_CONTEXT('USERENV', 'CURRENT_EDITION_NAME'). This tag can be any specific notion to which the setter function applies.

  See Also:

  Oracle Database Advanced Application Developer's Guide for detailed information about editions

Setting the DBMS_SESSION.SET_CONTEXT username and client_id Parameters

In addition to the namespace, attribute, and value parameters, the DBMS_SESSION.SYS_CONTEXT procedure provides the client_id and username parameters. Use these settings for global application contexts. Table 6-2 explains how the combination of these settings controls the type of global application context you can create.

Sharing Global Application Context Values for All Database Users

To share global application values for all database users, set the namespace, attribute, and value parameters in the SET_CONTEXT procedure. In this scenario, all users who have database accounts will potentially have access to data in the database.

Example 6-10 shows how to create a package that sets and clears this type of global application context.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

CREATE OR REPLACE PACKAGE hr_ctx_pkg 
   AS  
    PROCEDURE set_hr_ctx(sec_level IN VARCHAR2); 
    PROCEDURE clear_hr_context;
   END;  
  /
  CREATE OR REPLACE PACKAGE BODY hr_ctx_pkg 
   AS                                            
    PROCEDURE set_hr_ctx(sec_level IN VARCHAR2)      
    AS   
    BEGIN  
     DBMS_SESSION.SET_CONTEXT(  
      namespace  => 'global_hr_ctx', 
      attribute  => 'job_role', 
      value      => sec_level);
     END set_hr_ctx;
           
  PROCEDURE clear_hr_context  
    AS
    BEGIN  
     DBMS_SESSION.CLEAR_CONTEXT('global_hr_ctx', 'job_role'); 
    END clear_context;  
  END; 
 /

In this example:

• Lines 12–16: Uses the DBMS_SESSION.SET_CONTEXT procedure to set values for the namespace, attribute, and value parameters. The sec_level value is specified when the database application runs the hr_ctx_pkg.set_hr_ctx procedure.

  The username and client_id values are not set, hence, they are NULL. This enables all users (database users) to have access to the values, which is appropriate for server-wide settings.

• Line 13: In the SET_CONTEXT procedure, sets the namespace to global_hr_ctx.

• Line 14: Creates the job_role attribute.

• Line 15: Sets the value for the job_role attribute to sec_level.

• Lines 18–24: Creates the clear_hr_context procedure to clear the context values. See "Clearing Session Data When the Session Closes" for more information.

Typically, you execute this procedure within a database application. For example, if all users logging in are clerks, and you want to use "clerk" as a security level, you would embed a call within a database application similar to the following:

BEGIN
 hr_ctx_pkg.set_hr_ctx('clerk');
END;
/

If the procedure successfully completes, you can check the application context setting as follows:

SELECT SYS_CONTEXT('global_hr_ctx', 'job_role') job_role FROM DUAL;

JOB_ROLE
-----------
clerk

To clear this application context, enter the following:

BEGIN
 hr_ctx_pkg.clear_hr_context;
END;
/

To check that it is really cleared, the following SELECT statement should return no values:

SELECT SYS_CONTEXT('global_hr_ctx', 'job_role') job_role FROM DUAL;

JOB_ROLE
-----------

EXEC DBMS_SESSION.CLEAR_IDENTIFIER;

Setting a Global Context for Database Users Who Move Between Applications

To set a global application context for database users who move from one application to another, particularly when the applications have different access requirements, include the username parameter in the SET_CONTEXT procedure. This parameter specifies that the same schema be used for all sessions.

Use the following SET_CONTEXT parameters:

• namespace

• attribute

• value

• username

Oracle Database matches the username value so that the other application can recognize the application context. This enables the user to move between applications.

By omitting the client_id setting, its value is NULL, the default. This means that values can be seen by multiple sessions if the username setting is the same for a database user who maintains the same context in different applications. For example, you can have a suite of applications that control user access with Oracle Virtual Private Database policies, with each user restricted to a job role.

Example 6-11 demonstrates how to set the username parameter so that a specific user can move between applications. This example is similar to the package that was created in Example 6-10. The use of the username parameter is indicated in bold typeface.

CREATE OR REPLACE PACKAGE hr_ctx_pkg
  AS
    PROCEDURE set_hr_ctx(sec_level IN VARCHAR2, user_name IN VARCHAR2);
    PROCEDURE clear_hr_context;
   END;
  /
  CREATE OR REPLACE PACKAGE BODY hr_ctx_pkg
   AS
    PROCEDURE set_hr_ctx(sec_level IN VARCHAR2, user_name IN VARCHAR2)
    AS
     BEGIN
      DBMS_SESSION.SET_CONTEXT(
       namespace  => 'global_hr_ctx',
       attribute  => 'job_role',
       value      => sec_level,
       username   => user_name);
      END set_hr_ctx;
 
   PROCEDURE clear_hr_context
    AS
     BEGIN
      DBMS_SESSION.CLEAR_CONTEXT('global_hr_ctx');
     END clear_context;
  END;
 / 

Typically, you execute this procedure within a database application by embedding a call similar to the following example. Ensure that the value for the user_name parameter (scott in this case) is a valid database user name.

BEGIN
 hr_ctx_pkg.set_hr_ctx('clerk', 'scott');
END;

A secure way to manage this type of global application context is within your applications, embed code to grant a secure application role to the user. This code should include EXECUTE permissions on the trusted PL/SQL package that sets the application context. In other words, the application, not the user, will set the context for the user.

Setting a Global Application Context for Nondatabase Users

When a nondatabase user, that is, a user who is not known to the database (such as a Web application user), starts a client session, the application server generates a client session ID. Once this ID is set on the application server, it must be passed to the database server side. You do this by using the DBMS_SESSION.SET_IDENTIFIER procedure to set the client session ID. To set the context, you set the client_id parameter in the DBMS_SESSION.SET_CONTEXT procedure, in a PL/SQL procedure on the server side. This enables you to manage the application context globally, yet each client sees only his or her assigned application context.

The client_id value is the key here to getting and setting the correct attributes for the global application context. Remember that the client identifier is controlled by the middle-tier application, and once set, it remains open until it is cleared.

A typical way to manage this type of application context is to place the session_id value (client_identifier) in a cookie, and send it to the end user's HTML page so that is returned on the next request. A lookup table in the application should also keep client identifiers so that they are prevented from being reused for other users and to implement an end-user session time out.

For nondatabase users, configure the following SET_CONTEXT parameters:

• namespace

• attribute

• value

• username

• client_id

Example 6-12 shows how to create a package that manages this type of global application context.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

CREATE OR REPLACE PACKAGE hr_ctx_pkg  
  AS                         
   PROCEDURE set_session_id(session_id_p IN NUMBER); 
   PROCEDURE set_hr_ctx(sec_level_attr IN VARCHAR2,  
      sec_level_val IN VARCHAR2);    
   PROCEDURE clear_hr_session(session_id_p IN NUMBER); 
   PROCEDURE clear_hr_context;  
  END;     
/
  CREATE OR REPLACE PACKAGE BODY hr_ctx_pkg 
   AS                     
    session_id_global NUMBER;  
  PROCEDURE set_session_id(session_id_p IN NUMBER) 
   AS                     
   BEGIN   
    session_id_global := session_id_p; 
    DBMS_SESSION.SET_IDENTIFIER(session_id_p);
  END set_session_id; 
     
  PROCEDURE set_hr_ctx(sec_level_attr IN VARCHAR2,
     sec_level_val IN VARCHAR2) 
   AS     
   BEGIN      
    DBMS_SESSION.SET_CONTEXT(  
     namespace  => 'global_hr_ctx',  
     attribute  => sec_level_attr,
     value      => sec_level_val,
     username   => USER,
     client_id  => session_id_global); 
   END set_hr_ctx;  
        
  PROCEDURE clear_hr_session(session_id_p IN NUMBER)
   AS 
   BEGIN   
      DBMS_SESSION.SET_IDENTIFIER(session_id_p); 
      DBMS_SESSION.CLEAR_IDENTIFIER;  
   END clear_hr_session;   
   
  PROCEDURE clear_hr_context 
  AS       
  BEGIN            
   DBMS_SESSION.CLEAR_CONTEXT('global_hr_ctx', session_id_global);
  END clear_hr_context;  
 END;  
 /

In this example:

• Line 12: Creates the session_id_global variable, which will hold the client session ID. The session_id_global variable is referenced throughout the package definition, including the procedure that creates the global application context attributes and assigns them values. This means that the global application context values will always be associated with this particular session ID.

• Lines 13–18: Creates the set_session_id procedure, which writes the client session ID to the session_id_global variable.

• Lines 20–30: Creates the set_hr_ctx procedure, which creates global application context attributes and enables you to assign values to these attributes. Within this procedure:

  • Line 28: Specifies the username value. This example sets it by calling the Oracle Database-supplied USER function, which adds the session owner from the context retrieval process. The USER function ensures that only the user who set the application context can access the context. See Oracle Database SQL Language Reference for more information about the USER function.

    If you had specified NULL (the default for the username parameter), then any user can access the context.

    Setting both the username and client_id values enables two scenarios. For lightweight users, set the username parameter to a connection pool owner (for example, APPS_USER), and then set client_id to the client session ID. If you want to use a stateless Web session, set the user_name parameter to the same database user who has logged in, and ensure that this user keeps the same client session ID. See "Setting the DBMS_SESSION.SET_CONTEXT username and client_id Parameters" for an explanation of how different username and client_id settings work.

  • Line 29: Specifies client_id value. This example sets it to the session_id_global variable. This associates the context settings defined here with a specific client session ID, that is, the one that is set when you run the set_session_id procedure. If you specify the client_id parameter default, NULL, then the global application context settings could be used by any session.

• Lines 32–37: Creates the clear_hr_session procedure to clear the client session identifier. Line 33 sets it to ensure that you are clearing the correct session ID, that is, the one stored in variable session_id_p defined in Line 10.

• Lines 39–44: Creates the clear_hr_context procedure, so that you can clear the context settings for the current user session, which were defined by the global_hr_ctx variable. See "Clearing Session Data When the Session Closes" for more information.

Clearing Session Data When the Session Closes

The application context exists entirely within memory. When the user exits a session, you need to clear the context for the client_identifier value. This releases memory and prevents other users from accidentally using any left over values.

To clear session data when a user exits a session, use either of the following methods in the server-side PL/SQL package:

• Clearing the client identifier when a user exits a session. Use the DBMS_SESSION.CLEAR_IDENTIFIER procedure. For example:

  DBMS_SESSION.CLEAR_IDENTIFIER;
  

• Continuing the session but still clearing the context. If you want the session to continue, but you still need to clear the context, use the DBMS_SESSION.CLEAR_CONTEXT or the DBMS_SESSION.CLEAR_ALL_CONTEXT procedure. For example:

  DBMS_SESSION.CLEAR_CONTEXT('my_ctx', 'my_attribute');
  

  The CLEAR_CONTEXT procedure clears the context for the current user. To clear the context values for all users, for example, when you need to shut down the application server, use the CLEAR_ALL_CONTEXT procedure.

  Global application context values are available until they are cleared, so you should use CLEAR_CONTEXT or CLEAR_ALL_CONTEXT to ensure that other sessions do not have access to these values. Be aware that any changes in the context value are reflected immediately and subsequent calls to access the value through the SYS_CONTEXT function will return the most recent value.

About Managing Client Session IDs Using a Middle-Tier Application

The application server generates the client session ID. From a middle-tier application, you can get, set, and clear the client session IDs. To do so, embed either Oracle Call Interface (OCI) calls or DBMS_SESSION PL/SQL package procedures into the middle-tier application code.

The application authenticates the user, sets the client identifier, and sets it in the current session. The PL/SQL package SET_CONTEXT sets the client_identifier value in the application context. See "Setting a Global Application Context for Nondatabase Users" for more information.

Retrieving the Client Session ID Using a Middle-Tier Application

When a user starts a client session, the application server generates a client session ID. To retrieve this client ID, you can use the OCIStmtExecute call with any of the following statements:

SELECT SYS_CONTEXT('userenv', 'client_identifier') FROM dual;

SELECT CLIENT_IDENTIFIER from V$SESSION;

SELECT value FROM session_context WHERE attribute='CLIENT_IDENTIFIER';

Example 6-13 shows how to use the OCIStmtExecute call to retrieve a client session ID value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

oratext    clientid[31]; 
 OCIDefine  *defnp1 = (OCIDefine *) 0; 
 OCIStmt    *statementhndle; 
 oratext    *selcid = (oratext *)"SELECT SYS_CONTEXT('userenv', 
             'client_identifier') FROM  DUAL"; 
 
 OCIStmtPrepare(statementhndle, errhp, selcid, 
  (ub4) strlen((char *) selcid), (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
 
OCIDefineByPos(statementhndle, &defnp1, errhp, 1, (dvoid *)clientid, 31, 
  SQLT_STR, (dvoid *) 0, (ub2 *) 0, (ub2 *) 0, OCI_DEFAULT);
 
OCIStmtExecute(servhndle, statementhndle, errhp, (ub4) 1, (ub4) 0,
  (CONST OCISnapshot *) NULL, (OCISnapshot *) NULL, OCI_DEFAULT); 
 
printf("CLIENT_IDENTIFIER = %s \n", clientid);

In this example:

• Lines 1–5: Create variables to store the client session ID, reference call for OCIDefine, the statement handle, and the SELECT statement to use.

• Lines 7–8: Prepare the statement selcid for execution.

• Lines 10–11: Define the output variable clientid for client session ID.

• Lines 13–14: Execute the statement in the selcid variable.

• Line 16: Prints the formatted output for the retrieved client session ID.

Setting the Client Session ID Using a Middle-Tier Application

After you use the OCIStmtExecute call to retrieve the client session ID, you are ready to set this ID. The DBMS_SESSION.SET_CONTEXT procedure in the server-side PL/SQL package then sets this session ID and optionally, overwrites the application context values.

Ensure that the middle-tier application code checks that the client session ID value (for example, the value written to user_id in the previous examples) matches the client_id setting defined in the server-side DBMS_SESSION.SET_CONTEXT procedure. The sequence of calls on the application server side should be as follows:

1. Get the current client session ID. The session should already have this ID, but it is safer to ensure that it truly has the correct value.

2. Clear the current client session ID. This prepares the application to service a request from a different end user.

3. Set the new client session ID or the client session ID that has been assigned to the end user. This ensures that the session is using a different set of global application context values.

You can use the following methods to set the client session ID on the application server side:

• Oracle Call Interface. Set the OCI_ATTR_CLIENT_IDENTIFIER attribute in an OCIAttrSet OCI call. This attribute sets the client identifier in the session handle to track the end user identity.

  The following example shows how to use OCIAttrSet with the ATTR_CLIENT_IDENTIFIER parameter. The user_id setting refers to a variable that stores the ID of the user who is logging on.

  OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, 
             (void *) user_id, (ub4)strlen(user_id),
             OCI_ATTR_CLIENT_IDENTIFIER, error_handle);
  

• DBMS_SESSION package. Use the DBMS_SESSION.SET_IDENTIFIER procedure to set the client identifier for the global application context. For example, assuming you are storing the ID of the user logging on in a variable called user_id, you would enter the following line into the middle-tier application code:

  DBMS_SESSION.SET_IDENTIFIER(user_id);
  

For both OCIAttrSet and DBMS_SESSION.SET_IDENTIFIER, you can check the value of this identifier as follows:

SELECT SYS_CONTEXT('userenv', 'client_identifier') FROM dual;

Another way to check this value is to query the V$SESSION view:

SELECT CLIENT_IDENTIFIER from V$SESSION;

Clearing Session Data Using a Middle-Tier Application

The application context exists entirely within memory. When the user exits a session, you need to clear the context for the client_identifier value. This releases memory and prevents other users from accidentally using any left over values

To clear session data when a user exits a session, use either of the following methods in the middle-tier application code:

• Clearing the client identifier when a user exits a session. Use the DBMS_SESSION.CLEAR_IDENTIFIER procedure. For example:

  DBMS_SESSION.CLEAR_IDENTIFIER;
  

• Continuing the session but still clearing the context. If you want the session to continue, but you still need to clear the context, use the DBMS_SESSION.CLEAR_CONTEXT or the DBMS_SESSION.CLEAR_ALL_CONTEXT procedure. For example:

  DBMS_SESSION.CLEAR_CONTEXT(namespace, client_identifier, attribute);
  

  The CLEAR_CONTEXT procedure clears the context for the current user. To clear the context values for all users, for example, when you need to shut down the application server, use the CLEAR_ALL_CONTEXT procedure.

  Global application context values are available until they are cleared, so you should use CLEAR_CONTEXT or CLEAR_ALL_CONTEXT to ensure that other sessions do not have access to these values.

About This Tutorial

This tutorial shows how to create a global application context that uses a client session ID for a lightweight user application. It demonstrates how to control nondatabase user access by using a connection pool.

Step 1: Create User Accounts

You must create two users for this example: a security administrator who will manage the application context and its package, and a user account that owns the connection pool.

In this tutorial:

1. Log on to SQL*Plus as SYS and connect using AS SYSDBA.

   sqlplus sys as sysdba
   Enter password: password
   

2. Create the sysadmin_ctx account, who will administer the global application context.

   GRANT CREATE SESSION, CREATE ANY CONTEXT, CREATE PROCEDURE TO sysadmin_ctx IDENTIFIED BY password;
   
   GRANT EXECUTE ON DBMS_SESSION TO sysadmin_ctx;
   

   Replace password with a password that is secure. See "Minimum Requirements for Passwords" for more information.

3. Create the database account apps_user, who will own the connection pool.

   GRANT CREATE SESSION TO apps_user IDENTIFIED BY password;
   

   Replace password with a password that is secure. See "Minimum Requirements for Passwords" for more information.

Step 2: Create the Global Application Context

1. Log on as the security administrator sysadmin_ctx.

   CONNECT sysadmin_ctx
   Enter password: password
   

2. Create the cust_ctx global application context.

   CREATE CONTEXT global_cust_ctx USING cust_ctx_pkg ACCESSED GLOBALLY;
   

   The cust_ctx context is created and associated with the schema of the security administrator sysadmin_ctx. However, the SYS schema owns the application context.

Step 3: Create a Package for the Global Application Context

1. As sysadmin_ctx, create the following PL/SQL package:

   CREATE OR REPLACE PACKAGE cust_ctx_pkg
     AS
      PROCEDURE set_session_id(session_id_p IN NUMBER); 
      PROCEDURE set_cust_ctx(sec_level_attr IN VARCHAR2, 
        sec_level_val IN VARCHAR2);
      PROCEDURE clear_hr_session(session_id_p IN NUMBER);
      PROCEDURE clear_hr_context;
     END;
    /
   CREATE OR REPLACE PACKAGE BODY cust_ctx_pkg
     AS
     session_id_global NUMBER;
    
    PROCEDURE set_session_id(session_id_p IN NUMBER) 
     AS
     BEGIN
      session_id_global := session_id_p;
      DBMS_SESSION.SET_IDENTIFIER(session_id_p);
    END set_session_id;
    
    PROCEDURE set_cust_ctx(sec_level_attr IN VARCHAR2, sec_level_val IN VARCHAR2)
     AS
     BEGIN
      DBMS_SESSION.SET_CONTEXT(
       namespace  => 'global_cust_ctx',
       attribute  => sec_level_attr,
       value      => sec_level_val,
       username   => USER, -- Retrieves the session user, in this case, apps_user
       client_id  => session_id_global);
     END set_cust_ctx;
    
     PROCEDURE clear_hr_session(session_id_p IN NUMBER)
      AS
      BEGIN
        DBMS_SESSION.SET_IDENTIFIER(session_id_p);
        DBMS_SESSION.CLEAR_IDENTIFIER;
      END clear_hr_session;
   
    PROCEDURE clear_hr_context
     AS
     BEGIN
      DBMS_SESSION.CLEAR_CONTEXT('global_cust_ctx', session_id_global);
     END clear_hr_context;
    END;
   /
   

   For a detailed explanation of how this type of package works, see Example 6-12.

2. Grant EXECUTE privileges on the cust_ctx_pkg package to the connection pool owner, apps_user.

   GRANT EXECUTE ON cust_ctx_pkg TO apps_user;
   

Step 4: Test the Global Application Context

At this stage, you are ready to explore how this global application context and session ID settings work.

1. Log on to SQL*Plus as the connection pool owner, user apps_user.

   CONNECT apps_user
   Enter password: password
   

2. When the connection pool user logs on, the application sets the client session identifier as follows:

   BEGIN
    sysadmin_ctx.cust_ctx_pkg.set_session_id(34256);
   END;
   /
   

   You can test and check the value of the client session identifier as follows:

   1. Connect to SQL*Plus as the connection pool user apps_user.

   2. Set the session ID:

      EXEC sysadmin_ctx.cust_ctx_pkg.set_session_id(34256);
      

   3. Check the session ID:

      SELECT SYS_CONTEXT('userenv', 'client_identifier') FROM dual;
      

      The following output should appear:

      SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER')
      --------------------------------------------------
      34256
      

3. As user apps_user, set the global application context as follows:

   EXEC sysadmin_ctx.cust_ctx_pkg.set_cust_ctx('Category', 'Gold Partner');
   EXEC sysadmin_ctx.cust_ctx_pkg.set_cust_ctx('Benefit Level', 'Highest');
   

   (In a real-world scenario, the middle-tier application would set the global application context values, similar to how the client session identifier was set in Step 2.)

4. Enter the following SELECT SYS_CONTEXT statement to check that the settings were successful:

   col category format a13
   col benefit_level format a14
   
   SELECT SYS_CONTEXT('global_cust_ctx', 'Category') category, SYS_CONTEXT('global_cust_ctx', 'Benefit Level') benefit_level FROM dual;
   

   The following output should appear:

   CATEGORY       BENEFIT_LEVEL
   -------------  --------------
   Gold Partner   Highest
   

What apps_user has done here, within the client session 34256, is set a global application context on behalf of a nondatabase user. This context sets the Category and Benefit Level DBMS_SESSION.SET_CONTEXT attributes to be Gold Partner and Highest, respectively. The context exists only for user apps_user with client ID 34256. When a nondatabase user logs in, behind the scenes, he or she is really logging on as the connection pool user apps_user. Hence, the Gold Partner and Highest context values are available to the nondatabase user.

Suppose the user had been a database user and could log in without using the intended application. (For example, the user logs in using SQL*Plus.) Because the user has not logged in through the connection pool user apps_user, the global application context appears empty to our errant user. This is because the context was created and set under the apps_user session. If the user runs the SELECT SYS_CONTEXT statement, the following output appears:

CATEGORY       BENEFIT_LEVEL
-------------  --------------

Next, try the following test:

1. As user apps_user, clear the session ID.

   EXEC sysadmin_ctx.cust_ctx_pkg.clear_hr_session(34256);
   

2. Check the global application context settings again.

   SELECT SYS_CONTEXT('global_cust_ctx', 'Category') category, SYS_CONTEXT('global_cust_ctx', 'Benefit Level') benefit_level FROM dual;
   
   CATEGORY       BENEFIT_LEVEL
   -------------  --------------
   

   Because apps_user has cleared the session ID, the global application context settings are no longer available.

3. Restore the session ID to 34256, and then check the context values.

   EXEC sysadmin_ctx.cust_ctx_pkg.set_session_id(34256);
   
   SELECT SYS_CONTEXT('global_cust_ctx', 'Category') category, SYS_CONTEXT('global_cust_ctx', 'Benefit Level') benefit_level FROM dual;
   

   The following output should appear:

   CATEGORY       BENEFIT_LEVEL
   -------------  --------------
   Gold Partner   Highest
   

   As you can see, resetting the session ID to 34256 brings the application context values back again. To summarize, the global application context must be set only once for this user, but the client session ID must be set each time the user logs on.

4. Now try clearing and then checking the global application context values.

   EXEC sysadmin_ctx.cust_ctx_pkg.clear_hr_context;
   
   SELECT SYS_CONTEXT('global_cust_ctx', 'Category') category, SYS_CONTEXT('global_cust_ctx', 'Benefit Level') benefit_level FROM dual;
   

   The following output should appear:

   CATEGORY       BENEFIT_LEVEL
   -------------  --------------
   

   At this stage, the client session ID, 34256 is still in place, but the application context settings no longer exist. This enables you to continue the session for this user but without using the previously set application context values.

Step 5: Remove the Components for This Tutorial

1. Log on as SYS and connect using AS SYSDBA.

   CONNECT sys/as sysdba
   Enter password: password
   

2. Drop the global application context.

   DROP CONTEXT global_cust_ctx;
   

   Remember that even though sysadmin_ctx created the global application context, it is owned by the SYS schema.

3. Drop the two sample users.

   DROP USER sysadmin_ctx CASCADE;
   DROP USER apps_user;
   

Simple Global Application Context Process

Consider the application server, AppSvr, that has assigned the client identifier 12345 to client SCOTT. The AppSvr application uses the SCOTT user to create a session (that is, it is not a connection pool.) The value assigned to the context attribute can come from anywhere, for example, from running a SELECT statement on a table that holds the responsibility codes for users. When the application context is populated, it is stored in memory. As a result, any action that needs the responsibility code can access it quickly with SYS_CONTEXT call, without the overhead of accessing a table. The only advantage of a global context over a local context in this case is if SCOTT were changing applications frequently and used the same context in each application.

The following steps show how the global application context process sets the client identifier for SCOTT:

1. The administrator creates a global context namespace by using the following statement:

   CREATE OR REPLACE CONTEXT hr_ctx USING hr.init ACCESSED GLOBALLY;
   

2. The administrator creates a PL/SQL package for the hr_ctx application context to indicate that, for this client identifier, there is an application context called responsibility with a value of 13 in the HR namespace.:

   CREATE OR REPLACE PROCEDURE hr.init 
    AS
    BEGIN
     DBMS_SESSION.SET_CONTEXT(
       namespace => 'hr_ctx', 
       attribute => 'responsibility', 
       value     => '13', 
       username  => 'SCOTT', 
       client_id => '12345' );
    END;
   /
   

   This PL/SQL procedure is stored in the HR database schema, but typically it is stored in the schema of the security administrator.

3. The AppSvr application issues the following command to indicate the connecting client identity each time scott uses AppSvr to connect to the database:

   EXEC DBMS_SESSION.SET_IDENTIFIER('12345');
   

4. When there is a SYS_CONTEXT('hr_ctx','responsibility') call within the database session, the database matches the client identifier, 12345, to the global context, and then returns the value 13.

5. When exiting this database session, AppSvr clears the client identifier by issuing the following procedure:

   EXEC DBMS_SESSION.CLEAR_IDENTIFIER( );
   

6. To release the memory used by the application context, AppSvr issues the following procedure:

   DBMS_SESSION.CLEAR_CONTEXT('hr_ctx', '12345');
   

   CLEAR_CONTEXT is needed when the user session is no longer active, either on an explicit logout, timeout, or other conditions determined by the AppSvr application.

Global Application Context Process for Lightweight Users

The following steps show the global application context process for a lightweight user application. The lightweight user, robert, is not known to the database through the application.

1. The administrator creates the global context namespace by using the following statement:

   CREATE CONTEXT hr_ctx USING hr.init ACCESSED GLOBALLY;
   

2. The HR application server, AppSvr, starts and then establishes multiple connections to the HR database as the appsmgr user.

3. User robert logs in to the HR application server.

4. AppSvr authenticates robert to the application.

5. AppSvr assigns a temporary session ID (or uses the application user ID), 12345, for this connection.

6. The session ID is returned to the Web browser used by robert as part of a cookie or is maintained by AppSvr.

7. AppSvr initializes the application context for this client by calling the hr.init package, which issues the following statements:

   DBMS_SESSION.SET_CONTEXT( 'hr_ctx', 'id', 'robert', 'APPSMGR', 12345 );
   DBMS_SESSION.SET_CONTEXT( 'hr_ctx', 'dept', 'sales', 'APPSMGR', 12345 );
   

8. AppSvr assigns a database connection to this session and initializes the session by issuing the following statement:

   DBMS_SESSION.SET_IDENTIFIER( 12345 );
   

9. All SYS_CONTEXT calls within this database session return application context values that belong only to the client session.

   For example, SYS_CONTEXT('hr','id') returns the value robert.

10. When finished with the session, AppSvr issues the following statement to clean up the client identity:

    DBMS_SESSION.CLEAR_IDENTIFIER ( );
    

Even if another user logged in to the database, this user cannot access the global context set by AppSvr, because AppSvr specified that only the application with user APPSMGR logged in can see it. If AppSvr used the following, then any user session with client ID set to 12345 can see the global context:

DBMS_SESSION.SET_CONTEXT( 'hr_ctx', 'id', 'robert', NULL , 12345 );
DBMS_SESSION.SET_CONTEXT( 'hr_ctx', 'dept', 'sales', NULL , 12345 );

Setting USERNAME to NULL enables different users to share the same context.

You can query the client identifier set in the session as follows:

SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM dual;

The following output should appear:

SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER')
-------------------------------------------------
12345

A security administrator can see which sessions have the client identifier set by querying the V$SESSION view for the CLIENT_IDENTIFIER and USERNAME, for example:

COL client_identifier format a18
SELECT CLIENT_IDENTIFIER, USERNAME from V$SESSION;

The following output should appear:

CLIENT_IDENTIFIER   USERNAME
------------------  --------
12345               APPSMGR

To check the amount of global context area (in bytes) being used, use the following query:

SELECT SYS_CONTEXT('USERENV','GLOBAL_CONTEXT_MEMORY') FROM dual;

The following output should appear:

SYS_CONTEXT('USERENV','GLOBAL_CONTEXT_MEMORY')
----------------------------------------------
584