An identity is the actual value of a factor, such an IP_Address factor identity being 192.0.2.4.

A factor identity for a given database session is assigned at run time using the get_expr parameter (to retrieve the identity of a factor) and the identify_by parameter (to determine the identify of the factor) in the DBMS_MACADM.CREATE_FACTOR procedure. You can further configure the identity for the following reasons:

• To define the known identities for a factor

• To add a trust level to a factor identity

• To add an Oracle Label Security label to a factor identity

• To resolve a factor identity through its child factors, by using identity mapping

A factor identity is the actual value of a factor (for example, the IP address for a factor that uses the IP_Address type).

A factor can have several identities depending on its retrieval method or its identity mapping logic. For example, a factor such as Database_Hostname could have multiple identities in an Oracle Real Application Clusters environment; a factor such as Client_IP can have multiple identities in any database environment. The retrieval method for these types of factors may return different values because the retrieval method is based on the database session. Several reports allow you to track the factor identity configuration.

You can configure the assignment of a factor in the following ways:

• Assign the factor at the time a database session is established.

• Configure individual requests to retrieve the identity of the factor.

With the Oracle Label Security integration, you can label identities with an Oracle Label Security label. You can also assign an identity trust levels, which are numbers that indicate the magnitude of trust relative to other identities for the same factor. In general, the higher the trust level number is set, the greater the trust. Negative trust levels are not trusted.

Within a database session, a factor assigned identity is available to Oracle Database Vault and any application with a publicly accessible PL/SQL function that exists in the DVF schema (which contains functions that retrieve factor values) as follows:

dvf.f$factor_name

This allows the identifier for a factor to be accessed globally from within the Oracle database (using PL/SQL, SQL, Oracle Virtual Private Database, triggers, and so on). For example, in SQL*Plus:

CONNECT leo_dvowner
Enter password: password	

SELECT DVF.F$DATABASE_IP FROM DUAL;

Output similar to the following appears:

SELECT DVF.F$DATABASE_IP FROM DUAL;

F$DATABASE_IP
-------------------------------------------------------------
192.0.2.1

You can also use the GET_FACTOR function to find the identity of a factor that is made available for public access. For example:

SELECT GET_FACTOR('DATABASE_IP') FROM DUAL;

The following output appears:

GET_FACTOR('DATABASE_IP')
-------------------------------------------------------------
192.0.2.1

Trust levels enable you to assign a numeric value to indicate the measure of trust allowed.

A trust value of 1 signifies some trust. A higher value indicates a higher level of trust. A negative value or zero indicates distrust. When the factor identity returned from a factor retrieval method is not defined in the identity, Oracle Database Vault automatically assigns the identity a negative trust level.

To determine the trust level of a factor identity at run time, you can use the GET_TRUST_LEVEL and GET_TRUST_LEVEL_FOR_IDENTITY functions in the DVSYS schema.

For example, suppose you have created a factor named Network. You can create the following identities for the Network factor:

• Intranet, with a trust level of 10

• VPN (virtual private network), with a trust level of 5

• Public, with a trust level of 1

You then can create rule expressions (or custom application code) that base policy decisions on the trust level. For example, you can use the GET_TRUST_LEVEL function to find trust levels greater than 5:

GET_TRUST_LEVEL('Network') > 5

Or, you can use a SELECT statement on the DBA_DV_IDENTITY data dictionary view to find trust levels for the Network factor greater than or equal to 5:

SELECT VALUE, TRUST_LEVEL FROM DBA_DV_IDENTITY 
   WHERE TRUST_LEVEL >= 5 
   AND FACTOR_NAME='Network'

Output similar to the following appears:

F$NETWORK GET_TRUST_LEVEL('NETWORK')
------------------------------------
VPN                                5
INTRANET                          10

In the preceding example, the Network factor identity for VPN is trusted (value equals 5), and the identity for the INTRANET domain is 10, which implies a greater trust.

You can assign You Oracle Label Security (OLS) labels to factor identities.

In brief, a label acts as an identifier for a database table row to assign privileges to the row. In the DBMS_MACADM.CREATE_FACTOR or DBMS_MACADM.UPDATE_FACTOR procedure, the labeled_by parameter setting determines whether a factor is labeled DBMS_MACUTL.G_LABELED_BY_SELF or DBMS_MACUTL.G_LABELED_BY_FACTORS. If you set labeled_by to DBMS_MACUTL.G_LABELED_BY_SELF, then you can associate OLS labels with the factor identities. If you set labeled_by to DBMS_MACUTL.G_LABELED_BY_FACTORS, then Oracle Database Vault derives the factor identity labels from the labeling of child factor identities. When there are multiple child factor identities with labels, Oracle Database Vault merges the labels using the OLS algorithm associated with the applicable factor Oracle Label Security policy.

You can create and configure a factor identity for an existing factor.

1. Connect to the PDB as a user who has been granted the DV_OWNER or DV_ADMIN role.
   For example:

   CONNECT c##sec_admin_owen@pdb_name
   Enter password: password

   To find the available PDBs, query the PDB_NAME column of the DBA_PDBS data dictionary view. To check the current container, run the show con_name command.

2. Execute the DBMS_MACADM.CREATE_IDENTITY procedure.
   For example:

   BEGIN
    DBMS_MACADM.CREATE_IDENTITY(
     factor_name  => 'Sector2_ClientID', 
     value        => 'intranet', 
     trust_level  => 5); 
   END;
   /

   In this specification:

   • factor_name is the name of the existing factor. The DBA_DV_FACTOR data dictionary view lists factors.
   • value is the value of the factor, up to 1024 characters in mixed-case. For example, the identity of an IP_Address factor could be the IP address of 192.0.2.12.
   • trust_level indicates the magnitude of trust relative to other identities for the same factor. In general, the higher the trust level number is set, the greater the trust. A trust level of 10 indicates "very trusted." Negative trust levels are not trusted.
     • 10 is very trusted.
     • 5 is trusted.
     • 1 is somewhat trusted.
     • -1 is untrusted.
     • NULL is for a trust level that is not defined (default)

You can use identity mapping to use a group of factors to manage identity values.

• About Identity Mapping
  While you are creating a factory identity, you can map it.
• Mapping an Identity to a Factor
  You can map an identity to a factor by creating a parent-child relationship with two factors.
• Deleting an Identity Map
  To remove the parent-child relationship between two factors, you must delete the identity map.

You can use the DBMS_MACADM.UPDATE_IDENTITY procedure to modify a factor identity.

1. Connect to the PDB as a user who has been granted the DV_OWNER or DV_ADMIN role.
   For example:

   CONNECT c##sec_admin_owen@pdb_name
   Enter password: password

   To find the available PDBs, query the PDB_NAME column of the DBA_PDBS data dictionary view. To check the current container, run the show con_name command.

2. Find the factor identity and check its definition.
   For example:

   SELECT * FROM DBA_DV_IDENTITY ORDER BY FACTOR_NAME; 

3. Execute the DBMS_MACADM.UPDATE_IDENTITY statement.
   For example:

   BEGIN
    DBMS_MACADM.UPDATE_IDENTITY(
     factor_name  => 'Sector2_ClientID', 
     value        => 'intranet', 
     trust_level  => 7); 
   END;
   /

Before delete a factor identity, you must remove references to it.

1. Connect to the PDB as a user who has been granted the DV_OWNER or DV_ADMIN role.
   For example:

   CONNECT c##sec_admin_owen@pdb_name
   Enter password: password

   To find the available PDBs, query the PDB_NAME column of the DBA_PDBS data dictionary view. To check the current container, run the show con_name command.

2. Query the DBA_DV_IDENTITY data dictionary view to find the factor identity to remove.
   For example:

   SELECT * FROM DBA_DV_IDENTITY ORDER BY FACTOR_NAME;

3. Execute the DBMS_MACADM.DELETE_IDENTITY procedure.
   You must include the factor_name and value parameters. For example:

   BEGIN
    DBMS_MACADM.DELETE_IDENTITY(
     factor_name => 'Sector2_ClientID', 
     value       => 'intranet'); 
   END;
   /

Oracle Database Vault evaluates the factors based on when a session begins.

When a database session is established, the following actions occur:

1. At the start of each database session, Oracle Database Vault begins to evaluate all default and user-created factors in the database instance.

   This evaluation occurs after the normal database authentication of the session and the initialization of the Oracle Label Security session information, if applicable.

2. In the factor evaluation stage, the factor initialization process executes the retrieval method for all factors that are identified by methods or constants, to resolve the factor identity for the session.

   The factor error options setting has no effect on the factor initialization process.

3. If a factor has a validation method defined, Oracle Database Vault validates the identity (value) of the factor by executing this validation method. If the validation method fails or returns false, the identity of the factor is undefined (NULL).

4. If a factor has any identities defined for it, Oracle Database Vault resolves the trust level of the factor based on the identities defined. If an identity of the factor is defined in this list of defined identities, then Oracle Database Vault assigns the trust level as configured; otherwise it sets it to -1. If there are no identities defined for the factor, the trust level is undefined (NULL).

5. Depending on the outcome of this factor evaluation, factor validation, and trust level resolution, Database Vault audits the details of the evaluation as dictated by the factor audit configuration.

6. When the evaluation of all factors that are identified by method or constant completes, Oracle Database Vault resolves the factors that are identified by other factors by using the identity maps that are defined for the factor configured identities.

   The evaluation order of the factor-configured identities is by ASCII sort on the identity values: Oracle Database Vault uses the first alphabetically sorted identity mapping that it evaluates. For example, suppose factor TEST has identities X and Y. Furthermore, identities X and Y have identity maps that are dependent on identities for factors A, B, and C. The following mapping occurs:

   • X is mapped when A=1 and B=1.

   • Y is mapped when A=1, B=1, and C=2.

   In this case, the first one evaluated is X. Y is not evaluated, but what if its C mapping meets the criteria that is needed for the TEST factor's success? You would need to reverse the mapping, that is, map Y before X so that A, B, and C can be evaluated first. To reverse the mapping, rename Y to V (or some alphabetic value that sorts before X) so that it can be correctly resolved.

   This algorithm works if the ASCII sort ordering is correct and the identities map the same number factors at some level.

7. When the factor initialization completes, the Oracle Database Vault integration with Oracle Label Security occurs.

After this process completes, Oracle Database Vault checks to see if a command rule is associated with the CONNECT event. If a rule set associated with the CONNECT event, then Oracle Database Vault evaluates the rule set. If the rule set evaluates to false or results in an error, then the session is terminated. Oracle Database Vault executes any auditing or call handlers associated with the rule set before the session is terminated.

The Retrieval Method identifies factors where the factor identification is by method or constant.

If the factor identification is by factors, Oracle Database Vault identifies it by its identity mappings. You can create your own PL/SQL retrieval methods, or use the functions supplied with Oracle Database Vault. Oracle Database Vault provides factor-specific and general utility functions that you can use to build the retrieval method.

See also the default factors provided with Oracle Database Vault for examples of retrieval methods.

The get_expr parameter is mandatory if you have selected the following DBMS_MACADM.CREATE_FACTOR or DBMS_MACADM.CREATE_UPDATE settings for the identify_by parameter:

• DBMS_MACUTL.G_IDENTIFY_BY_METHOD: Enter a method for the get_expr parameter.

• DBMS_MACUTL.G_IDENTIFY_BY_CONSTANT: Enter a constant for the get_expr parameter.

The value returned as the factor identity must be a VARCHAR2 string or otherwise convertible to one.

You can include any package function or standalone function in the expression. Ensure that the expression is a fully qualified function, such as schema.function_name. Do not include complete SQL statements. If you are using application packages or functions, you must provide DVSYS with the EXECUTE privilege on the object.

Write the function signature using the following format:

FUNCTION GET_FACTOR RETURN VARCHAR2

You can retrieve a factor in a database session at any time by using the DVF factor function or the GET_FACTOR function.

To find a listing of available factors, query the DBA_DV_FACTOR data dictionary view, described in .

Example 7-1 shows an example of using the GET_FACTOR function.

SELECT GET_FACTOR('client_ip') FROM DUAL;

You can assign a factor identity at any time during a database session, but only if the factor assignment rule set evaluates to true.

You can do this in the application code by using the SET_FACTOR function. In Java code, you can use the JDBC class java.sql.CallableStatement to set this value. For example:

java.sql.Connection connection ; 
...
java.sql.CallableStatement statement = 
   connection.prepareCall("{call SET_FACTOR('FACTOR_X', ?)}");
statement.setString(1, "MyValue");
boolean result = statement.execute();
...

Applications that can execute Oracle PL/SQL functions can use this procedure (for example, applications written using Oracle Data Provider for .NET (ODP.NET)).

This concept is similar to the standard Oracle DBMS_SESSION.SET_IDENTIFIER procedure with an added feature that a rule set controls when a factor value can be set. If the rule set evaluates to true, Steps 2 through 5 under How Factors Are Processed When a Session Is Established occur.

If you have not associated a assignment rule set for the factor or if the rule set returns false (or returns errors), then Oracle Database Vault sends an error message if you attempt to set the factor using the SET_FACTOR function.

Whether you have unified auditing enabled affects how auditing is handled for factors.

In a traditional, non-unified auditing environment, Oracle Database Vault writes the audit trail to the DVSYS.AUDIT_TRAIL$ table. Be aware that traditional auditing is deprecated starting with Oracle Database release 21c.

If you have enabled unified auditing, then this setting does not capture audit records. Instead, you can create unified audit policies to capture this information.

You can use the Factor Audit Report to display the generated audit records. In addition, you can select multiple audit options at a time. Each option is converted to a bit mask and added to determine the aggregate behavior. Note that there is little performance impact in auditing, unless the factor has errors.

Many database applications contain features to explicitly control the actions of a user.

However, an ad hoc query tool, such as SQL*Plus, may not have these controls. As a result, a user could use an ad hoc tool to perform actions in the database that he or she would normally be prevented from performing in a database application. You can use a combination of Oracle Database Vault factors, rule sets, and command rules to prevent unauthorized access to the database by ad hoc query tools.

In the following tutorial, you prevent users HR and OE from using SQL*Plus. To accomplish this, you must create a factor to find the applications on your system and a rule and rule set to limit SQL*Plus to these four users. Then you create a command rule for the CONNECT SQL statement, which is associated with the rule set. This factor, Client_Prog_Name, uses the CLIENT_PROGRAM_NAME attribute of the SYS_CONTEXT SQL function USERENV namespace to find the names of the applications that are used to access the current instance of Oracle Database. The SYS_CONTEXT SQL function provides many useful methods for finding the state of a user session. SYS_CONTEXT is a valuable tool for creating custom factors.

You must use the HR and OE accounts later on when you test the Oracle Database Vault components for this tutorial.

1. Log into the PDB as a user who has been granted the DV_ACCTMGR role.

   For example:

   sqlplus bea_dvacctmgr@pdb_name
   Enter password: password
   

   To find the available PDBs, query the PDB_NAME column of the DBA_PDBS data dictionary view. To check the current container, run the show con_name command.

2. Check the status of the HR account.

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

3. If the HR account is expired and locked, then enter the following statement to make it active:

   ALTER USER HR ACCOUNT UNLOCK IDENTIFIED BY password;
   

   Replace password with a password that is secure.

4. Repeat these steps for the OE account.

After you have ensured that the HR and OE accounts are active, you can create a factor.

1. Connect to the PDB as a user who has been granted the DV_OWNER or DV_ADMIN role.

   For example:

   CONNECT leo_dvowner@pdb_name
   Enter password: password
   

2. Create the factor.

   BEGIN
    DBMS_MACADM.CREATE_FACTOR(
     factor_name       => 'Client_Prog_Name',
     factor_type_name  => 'Application',
     description       => 'Stores client program name that connects to database',
     rule_set_name     => NULL,
     validate_expr     => NULL,
     get_expr          => 'UPPER(SYS_CONTEXT(''USERENV'',''CLIENT_PROGRAM_NAME''))',
     identify_by       => DBMS_MACUTL.G_IDENTIFY_BY_METHOD,
     labeled_by        => DBMS_MACUTL.G_LABELED_BY_SELF,
     eval_options      => DBMS_MACUTL.G_EVAL_ON_SESSION,
     audit_options     => DBMS_MACUTL.G_AUDIT_OFF,
     fail_options      => DBMS_MACUTL.G_FAIL_SILENTLY);
   END;
   /
   

   In this specification:

   • factor_type_name specifies that this is an application-based factor.

   • get_expr defines the expression for the factor. This expression calls the SYS_CONTEXT function, using the USERENV namespace and CLIENT_PROGRAM_NAME attribute, to find the programs that are logged into the Oracle database.

   • identify_by identifies the factor by method.

   • labeled_by labels the identities for the factor directly from the labels associated with an Oracle Label Security policy (default).

   • eval_options evaluates the factor when the database session is created.

   • audit_options audits if get_expr returns an error.

   • fail_silently does not show any error messages for the factor.

After you have created the factor, you can create a rule set and rules to work with the factor.

1. Create the Limit SQL*Plus Access rule set as follows:

   BEGIN
    DBMS_MACADM.CREATE_RULE_SET(
     rule_set_name    => 'Limit SQL*Plus Access',
     description      => 'Limits access to SQL*Plus for Apps Schemas',
     enabled          => DBMS_MACUTL.G_YES,
     eval_options     => DBMS_MACUTL.G_RULESET_EVAL_ANY,
     audit_options    => DBMS_MACUTL.G_RULESET_AUDIT_OFF,
     fail_options     => DBMS_MACUTL.G_RULESET_FAIL_SHOW,
     fail_message     => 'SQL*Plus access not allowed for Apps Schemas',
     fail_code        => 20461,
     handler_options  => DBMS_MACUTL.G_RULESET_HANDLER_OFF,
     handler          => NULL,
     is_static        => FALSE);
   END;
   /
   

   In this specification:

   • fail_options enables an error message, set by fail_message, and error code, set by fail_code, to appear if there are errors.

   • is_static evaluates the rule set once during the user session. After that, the value is re-used.

2. Find the exact settings for the computer on which you want to apply the policy, based on what the CLIENT_PROGRAM_NAME attribute will return.

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

   The output should be similar to the following:

   SYS_CONTEXT('USERENV','CLIENT_PROGRAM_NAME')
   ---------------------------------------------------------------
   sqlplus@nemosity (TNS V1-V3)
   

   For this tutorial, the name of the computer is nemosity. The (TN V1-V3) output refers to the version of the TNS connector.

3. Create the following rules.

   BEGIN
    DBMS_MACADM.CREATE_RULE(
     rule_name  => 'Prevent Apps Schemas Access to SQL*Plus',
     rule_expr  =>'UPPER (DVF.F$CLIENT_PROG_NAME) != ''SQLPLUS@NEMOSITY (TNS V1-V3)'' AND DVF.F$SESSION_USER IN (''HR'', ''OE'')');
   END;
   /
   BEGIN
    DBMS_MACADM.CREATE_RULE(
     rule_name  => 'Allow Non-Apps Schemas Access to SQL*Plus',
     rule_expr  =>'DVF.F$SESSION_USER NOT IN (''HR'', ''OE'')');
   END;
   /
   

   The rules translate to the following: "Prevent users HR and OE from logging into SQL*Plus, but allow other users access."

4. Add the rules to the Limit SQL*Plus Access rule set.

   BEGIN
    DBMS_MACADM.ADD_RULE_TO_RULE_SET(
     rule_set_name => 'Limit SQL*Plus Access',
     rule_name     => 'Prevent Apps Schemas Access to SQL*Plus',
     rule_order    => 1);
   END;
   /
   BEGIN
    DBMS_MACADM.ADD_RULE_TO_RULE_SET(
     rule_set_name => 'Limit SQL*Plus Access',
     rule_name     => 'Allow Non-Apps Schemas Access to SQL*Plus',
     rule_order    => 1);
   END;
   /
   

   The rule_order setting is required to enable the procedure to work.

The CONNECT command rule controls the CONNECT SQL statement.

You do not need to restart your SQL*Plus session for the Oracle Database Vault changes to take effect.

1. Log in to the database instance as a user who has been granted the DV_OWNER or DV_ADMIN role.

   For example:

   CONNECT sec_admin_owen@pdb_name
   Enter password: password
   

2. Enter the following statement to drop the CONNECT command rule.

   EXEC DBMS_MACADM.DELETE_COMMAND_RULE ('CONNECT', '%', '%');
   

   Even though you have disabled Oracle Database Vault, you still can use its PL/SQL packages and Database Vault Administrator.

3. Check the policy components for any errors and then correct them. Recreate the CONNECT command rule, and then test it.

You can remove the components that you created for this tutorial if you no longer need them.

1. Remove the CONNECT command rule.

   EXEC DBMS_MACADM.DELETE_COMMAND_RULE ('CONNECT', '%', '%');
   

2. Remove the Client_Prog_Name factor.

   EXEC DBMS_MACADM.DELETE_FACTOR('Client_Prog_Name');
   

3. Remove the Limit SQL*Plus Access rule set.

   EXEC DBMS_MACADM.DELETE_RULE_SET('Limit SQL*Plus Access');
   

4. Remove the rules.

   EXEC DBMS_MACADM.DELETE_RULE('Prevent Apps Schemas Access to SQL*Plus');
   EXEC DBMS_MACADM.DELETE_RULE('Allow Non-Apps Schemas Access to SQL*Plus');
   

5. If necessary, as a user who has been granted the DBV_ACCTMGR role, lock the HR and OE accounts.

   CONNECT bea_dvacctmgr@pdb_name
   Enter password: password
   
   ALTER USER HR ACCOUNT LOCK;
   ALTER USER OE ACCOUNT LOCK;