7 Administering User Labels and Privileges

In Oracle Label Security, you can set authorizations for users and grant privileges to users or stored program units by means of the available Oracle Label Security packages, or Oracle Policy Manager.

Introduction to User Label and Privilege Management
Managing User Labels by Component, with SA_USER_ADMIN
Managing User Labels by Label String, with SA_USER_ADMIN
Managing User Privileges with SA_USER_ADMIN.SET_USER_PRIVS
Setting Labels & Privileges with SA_SESSION.SET_ACCESS_PROFILE
Returning User Name with SA_SESSION.SA_USER_NAME
Using Oracle Label Security Views

7.1 Introduction to User Label and Privilege Management

To manage user labels and privileges, you must have the EXECUTE privilege for the SA_USER_ADMIN package, and must have been granted the policy_DBA role.

To perform these functions with Oracle Policy Manager, go to Oracle Label Security Policies, policyname, Authorizations, Users and use the User page.

The SA_USER_ADMIN package provides the functions to manage the Oracle Label Security user security attributes. It contains several procedures to manage user labels by component: that is, specifying user levels, compartments, and groups. For convenience, there are additional procedures that accept character string representations of full labels, rather than components. Note that the level, compartment and group parameters use the short name defined for each component.

All of the label and privilege information is stored in Oracle Label Security data dictionary tables. When a user connects to the database, his session labels are established based on the information stored in the Oracle Label Security data dictionary.

Note that a user can be authorized under multiple policies.

7.2 Managing User Labels by Component, with SA_USER_ADMIN

The following SA_USER_ADMIN procedures enable you to manage user labels by label component:

SA_USER_ADMIN.SET_LEVELS
SA_USER_ADMIN.SET_COMPARTMENTS
SA_USER_ADMIN.SET_GROUPS
SA_USER_ADMIN.ADD_COMPARTMENTS
SA_USER_ADMIN.ALTER_COMPARTMENTS
SA_USER_ADMIN.DROP_COMPARTMENTS
SA_USER_ADMIN.DROP_ALL_COMPARTMENTS
SA_USER_ADMIN.ADD_GROUPS
SA_USER_ADMIN.ALTER_GROUPS
SA_USER_ADMIN.DROP_GROUPS
SA_USER_ADMIN.DROP_ALL_GROUPS

7.2.1 SA_USER_ADMIN.SET_LEVELS

The SET_LEVELS procedure assigns a minimum and maximum level to a user and identifies default values for the user's session label and row label.

If the min_level is NULL, then it is set to the lowest defined level for the policy.
If the def_level is not specified, then it is set to the max_level.
If the row_level is not specified, then it is set to the def_level.

Syntax:

PROCEDURE SET_LEVELS (policy_name IN VARCHAR2,
   user_name        IN VARCHAR2,
   max_level        IN VARCHAR2,
   min_level        IN VARCHAR2 DEFAULT NULL,
   def_level        IN VARCHAR2 DEFAULT NULL,
   row_level        IN VARCHAR2 DEFAULT NULL);

Table 7-1 Parameters for SA_USER_ADMIN.SET_LEVELS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
max_level	The highest level for read and write access
min_level	The lowest level for write access
def_level	Specifies the default level (equal to or greater than the minimum level, and equal to or less than the maximum level)
row_level	Specifies the row level (equal to or greater than the minimum level, and equal to or less than the default level)

7.2.2 SA_USER_ADMIN.SET_COMPARTMENTS

The SET_COMPARTMENTS procedure assigns compartments to a user and identifies default values for the user's session label and row label.

If write_comps are NULL, then they are set to the read_comps.
If the def_comps are NULL, then they are set to the read_comps.
If the row_comps are NULL, then they are set to the components in def_comps that are authorized for write access.

All users must have their levels set before their authorized compartments can be established.

The write compartments, if specified, must be a subset of the read compartments. (The write compartments are those to which the user should have write access.)

Syntax:

PROCEDURE SET_COMPARTMENTS (policy_name IN VARCHAR2,
  user_name     IN VARCHAR2,
  read_comps    IN VARCHAR2,
  write_comps   IN VARCHAR2 DEFAULT NULL,
  def_comps     IN VARCHAR2 DEFAULT NULL,
  row_comps     IN VARCHAR2 DEFAULT NULL);

Table 7-2 Parameters for SA_USER_ADMIN.SET_COMPARTMENTS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
read_comps	A comma-delimited list of compartments authorized for read access
write_comps	A comma-delimited list of compartments authorized for write access (subset of read_comps)
def_comps	Specifies the default compartments. This must be a subset of read_comps.
row_comps	Specifies the row compartments. This must be a subset of write_comps and def_comps.

7.2.3 SA_USER_ADMIN.SET_GROUPS

The SET_GROUPS procedure assigns groups to a user and identifies default values for the user's session label and row label.

If the write_groups are NULL, they are set to the read_groups.
If the def_groups are NULL, they are set to the read_groups.
If the row_groups are NULL, they are set to the groups in def_groups that are authorized for write access.

All users must have their levels set before their authorized groups can be established.

Syntax:

PROCEDURE SET_GROUPS (policy_name IN VARCHAR2,
  user_name        IN VARCHAR2,
  read_groups      IN VARCHAR2,
  write_groups     IN VARCHAR2 DEFAULT NULL,
  def_group        IN VARCHAR2 DEFAULT NULL,
  row_groups       IN VARCHAR2 DEFAULT NULL);

Table 7-3 Parameters for SA_USER_ADMIN.SET_GROUPS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
read_groups	A comma-delimited list of groups authorized for read
write_groups	A comma-delimited list of groups authorized for write. This must be a subset of read_groups.
def_groups	Specifies the default groups. This must be a subset of read_groups
row_groups	Specifies the row groups. This must be a subset of write_groups and def_groups.

7.2.4 SA_USER_ADMIN.ALTER_COMPARTMENTS

The ALTER_COMPARTMENTS procedure changes the write access, the default label indicator, and the row label indicator for each of the compartments in the list.

Syntax:

PROCEDURE ALTER_COMPARTMENTS (policy_name IN VARCHAR2,
  user_name    IN VARCHAR2,
  comps        IN VARCHAR2,
  access_mode  IN VARCHAR2 DEFAULT NULL,
  in_def       IN VARCHAR2 DEFAULT NULL,
  in_row       IN VARCHAR2 DEFAULT NULL);

Table 7-4 Parameters for SA_USER_ADMIN.ALTER_COMPARTMENTS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
comps	A comma-delimited list of compartments to modify
access_mode	One of two public variables that contain string values that can specify the type of access authorized. The variable names, values, and meaning are as follows: SA_UTL.READ_ONLY READ_ONLY Indicates no write access SA_UTL.READ_WRITE READ_WRITE Indicates that write is authorized If access_mode is NULL, then access_mode for the compartment is unaltered.
in_def	Specifies whether these compartments should be in the default compartments (Y/N) If in_def is NULL, then in_def for the compartment is unaltered.
in_row	Specifies whether these compartments should be in the row label (Y/N) If in_row is NULL, then in_row for the compartment is unaltered.

7.2.5 SA_USER_ADMIN.ADD_COMPARTMENTS

This procedure adds compartments to a user's authorizations, indicating whether the compartments are authorized for write as well as read.

Syntax:

PROCEDURE ADD_COMPARTMENTS (policy_name IN VARCHAR2,
user_name      IN VARCHAR2,
comps          IN VARCHAR2,
access_model   IN VARCHAR2 DEFAULT NULL,
in_def         IN VARCHAR2 DEFAULT NULL,
in_row         IN VARCHAR2 DEFAULT NULL);

Table 7-5 Parameters for SA_USER_ADMIN.ADD_COMPARTMENTS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
comps	A comma-delimited list of read compartments to add
access_mode	One of two public variables that contain string values that can specify the type of access authorized. The variable names, values, and meaning are as follows: SA_UTL.READ_ONLY READ_ONLY Indicates no write access SA_UTL.READ_WRITE READ_WRITE Indicates that write is authorized If access_mode is NULL, then it is set to SA_UTL.READ_ONLY.
in_def	Specifies whether these compartments should be in the default compartments (Y/N) If in_def is NULL, then it is set to Y.
in_row	Specifies whether these compartments should be in the row label (Y/N) If in_row is NULL, then it is set to N.

7.2.6 SA_USER_ADMIN.DROP_COMPARTMENTS

The DROP_COMPARTMENTS procedure drops the specified compartments from a user's authorizations.

Syntax:

PROCEDURE DROP_COMPARTMENTS (policy_name IN VARCHAR2,
  user_name       IN VARCHAR2,
  comps           IN VARCHAR2);

Table 7-6 Parameters for SA_USER_ADMIN.DROP_COMPARTMENTS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
comps	A comma-delimited list of compartments to drop

7.2.7 SA_USER_ADMIN.DROP_ALL_COMPARTMENTS

The DROP_ALL_COMPARTMENTS procedure drops all compartments from a user's authorizations.

Syntax:

PROCEDURE DROP_ALL_COMPARTMENTS (policy_name IN VARCHAR2,
     user_name IN VARCHAR2);

Table 7-7 Parameters for SA_USER_ADMIN.DROP_ALL_COMPARTMENTS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name

7.2.8 SA_USER_ADMIN.ADD_GROUPS

The ADD_GROUPS procedure adds groups to a user, indicating whether the groups are authorized for write as well as read.

Syntax:

PROCEDURE ADD_GROUPS (policy_name IN VARCHAR2,
  user_name         IN VARCHAR2,
  groups            IN VARCHAR2,
  access_mode       IN VARCHAR2 DEFAULT NULL,
  in_def            IN VARCHAR2 DEFAULT NULL,
  in_row            IN VARCHAR2 DEFAULT NULL);

Table 7-8 Parameters for SA_USER_ADMIN.ADD_GROUPS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
groups	A comma-delimited list of read groups to add
access_mode	One of two public variables that contain string values that can specify the type of access authorized. The variable names, values, and meaning are as follows: SA_UTL.READ_ONLY READ_ONLY Indicates no write access SA_UTL.READ_WRITE READ_WRITE Indicates that write is authorized If access_mode is NULL, then access_mode is set to SA_UTL.READ_ONLY.
in_def	Specifies whether these groups should be in the default groups (Y/N) If in_def is NULL, then it is set to Y.
in_row	Specifies whether these groups should be in the row label (Y/N) If in_row is NULL, then it is set to N.

7.2.9 SA_USER_ADMIN.ALTER_GROUPS

The ALTER_GROUPS procedure changes the write access, the default label indicator, and the row label indicator for each of the groups in the list.

Syntax:

PROCEDURE ALTER_GROUPS (policy_name IN VARCHAR2,
  user_name        IN VARCHAR2,
  groups           IN VARCHAR2,
  access_mode      IN VARCHAR2 DEFAULT NULL,
  in_def           IN VARCHAR2 DEFAULT NULL,
  in_row           IN VARCHAR2 DEFAULT NULL);

Table 7-9 Parameters for SA_USER_ADMIN.ALTER_GROUPS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
groups	A comma-delimited list of groups to alter
access_mode	Two public variables contain string values that can specify the type of access authorized. The variable names, values, and meaning are as follows: SA_UTL.READ_ONLY READ_ONLY Indicates no write access SA_UTL.READ_WRITE READ_WRITE Indicates that write is authorized If access_mode is NULL, then access_mode for the group is unaltered.
in_def	Specifies whether these groups should be in the default groups (Y/N) If in_def is NULL, then in_def for the group is unaltered.
in_row	Specifies whether these groups should be in the row label (Y/N) If in_row is NULL, then in_row for the group is unaltered.

7.2.10 SA_USER_ADMIN.DROP_GROUPS

The DROP_GROUPS procedure drops the specified groups from a user's authorizations.

Syntax:

PROCEDURE DROP_GROUPS (policy_name IN VARCHAR2,
  user_name   IN VARCHAR2,
  groups      IN VARCHAR2);

Table 7-10 Parameters for SA_USER_ADMIN.DROP_GROUPS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
groups	A comma-delimited list of groups to drop

7.2.11 SA_USER_ADMIN.DROP_ALL_GROUPS

The DROP_ALL_GROUPS procedure drops all groups from a user's authorizations.

Syntax:

PROCEDURE DROP_ALL_GROUPS (policy_name IN VARCHAR2,
  user_name  IN VARCHAR2);

Table 7-11 Parameters for SA_USER_ADMIN.DROP_ALL_GROUPS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name

7.3 Managing User Labels by Label String, with SA_USER_ADMIN

The following SA_USER_ADMIN procedures enable you to manage user labels by specifying the complete character label string:

SA_USER_ADMIN.SET_USER_LABELS
SA_USER_ADMIN.SET_DEFAULT_LABEL
SA_USER_ADMIN.SET_ROW_LABEL
SA_USER_ADMIN.SET_DEFAULT_LABEL

7.3.1 SA_USER_ADMIN.SET_USER_LABELS

The SET_USER_LABELS procedure sets the user's levels, compartments, and groups using a set of labels, instead of the individual components.

Syntax:

PROCEDURE SET_USER_LABELS (
  policy_name      IN VARCHAR2,
  user_name        IN VARCHAR2,
  max_read_label   IN VARCHAR2,
  max_write_label  IN VARCHAR2 DEFAULT NULL,
  min_write_label  IN VARCHAR2 DEFAULT NULL,
  def_label        IN VARCHAR2 DEFAULT NULL,
  row_label        IN VARCHAR2 DEFAULT NULL);

Table 7-12 Parameters for SA_USER_ADMIN.SET_USER_LABELS

Parameter	Meaning
max_read_label	Specifies the label string to be used to initialize the user's maximum authorized read label. Composed of the user's maximum level, compartments authorized for read access, and groups authorized for read access.
max_write_label	Specifies the label string to be used to initialize the user's maximum authorized write label. Composed of the user's maximum level, compartments authorized for write access, and groups authorized for write access. If max_write_label is not specified, then it is set to max_read_label.
min_write_label	Specifies the label string to be used to initialize the user's minimum authorized write label. Contains only the level, with no compartments or groups. If min_write_label is not specified, then it is set to the lowest defined level for the policy, with no compartments or groups.
def_label	Specifies the label string to be used to initialize the user's session label, including level, compartments, and groups (a subset of max_read_label). If default_label is not specified, then it is set to max_read_label.
policy_name	Specifies the policy
user_name	Specifies the user name
row_label	Specifies the label string to be used to initialize the program's row label. Includes level, components, and groups: subsets of max_write_label and def_label. If row_label is not specified, then it is set to def_label, with only the compartments and groups authorized for write access.

7.3.2 SA_USER_ADMIN.SET_DEFAULT_LABEL

The SET_DEFAULT_LABEL procedure sets the user's initial session label to the one specified.

Syntax:

PROCEDURE SET_DEFAULT_LABELS (
  policy_name  IN VARCHAR2,
  user_name    IN VARCHAR2,
  def_label    IN VARCHAR2);

Table 7-13 Parameters for SA_USER_ADMIN.SET_DEFAULT_LABEL

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
def_label	Specifies the label string to be used to initialize the user's default labels. This label may contain any compartments and groups that are authorized for read access.

As long as the row label will still be dominated by the new write label, the user can set the session label to:

Any level equal to or less than his maximum, and equal to or greater than his minimum label
Include any compartments in the authorized compartment list
Include any groups in the authorized group list. (Subgroups of authorized groups are implicitly included in the authorized list.)

The row label must be dominated by the new write label that will result from resetting the session label. If this condition is not true, then the SET_DEFAULT_LABEL procedure will fail.

For example, suppose the current row label is S:A,B, and that you have write access to both compartments. If you attempt to set the new default label to C:A,B, then the SET_LABEL procedure will fail. This is because the new write label would be C:A,B, which does not dominate the current row label.

To successfully reset the session label in this case, you must first lower the row label to a value that will be dominated by the resulting session label.

"Session Labels and Inverse Groups"

7.3.3 SA_USER_ADMIN.SET_ROW_LABEL

Use the SET_ROW_LABEL procedure to set the user's initial row label to the one specified.

Syntax:

PROCEDURE SET_ROW_LABEL (
  policy_name   IN VARCHAR2,
  user_name     IN VARCHAR2,
  row_label     IN VARCHAR2);

Table 7-14 Parameters for SA_USER_ADMIN.SET_ROW_LABEL

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name
row_label	Specifies the label string to be used to initialize the user's row label. The label must contain only those compartments and groups from the default label that are authorized for write access.

The user can set the row label independently, but only to:

A level that is less than or equal to the level of the session label, and greater than or equal to the user's minimum level
Include a subset of the compartments and groups from the session label, for which the user is authorized to have write access

If you try to set the row label to an invalid value, then the operation is disallowed, and the row label value is unchanged.

7.3.4 SA_USER_ADMIN.DROP_USER_ACCESS

Use the DROP_USER_ACCESS procedure to remove all Oracle Label Security authorizations and privileges from the specified user. This procedure must be issued from the command line. It is not available in Oracle Policy Manager.

Syntax:

PROCEDURE DROP_USER_ACCESS (
  policy_name      IN VARCHAR2,
  user_name        IN VARCHAR2);

Table 7-15 Parameters for SA_USER_ADMIN.DROP_USER_ACCESS

Parameter	Meaning
policy_name	Specifies the policy
user_name	Specifies the user name

7.4 Managing User Privileges with SA_USER_ADMIN.SET_USER_PRIVS

The SET_USER_PRIVS procedure sets policy-specific privileges for users. These privileges do not become effective in the current session. However, they become effective the next time the user logs in. The new set of privileges replaces any existing privileges. A NULL value for the privileges parameter removes the user's privileges for the policy.

To assign policy privileges to users, you must have the EXECUTE privilege for the SA_USER_ADMIN package, and must have been granted the policy_DBA role.

To use Oracle Policy Manager to perform these functions, go to the Privileges tab of the User page.

Syntax:

PROCEDURE SET_USER_PRIVS (
  policy_name     IN VARCHAR2,
  user_name       IN VARCHAR2,
  privileges      IN VARCHAR2);

Table 7-16 Parameters for SA_USER_ADMIN.SET_USER_PRIVS

Parameter	Meaning
policy_name	Specifies the policy name of an existing policy
user_name	The name of the user to be granted privileges
privileges	A character string of policy-specific privileges separated by commas

7.5 Setting Labels & Privileges with SA_SESSION.SET_ACCESS_PROFILE

The SET_ACCESS_PROFILE procedure sets the Oracle Label Security authorizations and privileges of the database session to those of the specified user. (Note that the originating user retains the PROFILE_ACCESS privilege.)

The user executing the SA_SESSION.SET_ACCESS_PROFILE procedure must have the PROFILE_ACCESS privilege. Note that the logged-in database user (the Oracle userid) does not change. That user assumes only the authorizations and privileges of the specified user. By contrast, the Oracle Label Security user name is changed.

This administrative procedure is useful for various tasks:

With SET_ACCESS_PROFILE, the administrator can see the result of the authorization and privilege settings for a particular user.
Applications need to have proxy accounts connect as (and assume the identity of) application users, for purposes of accessing labeled data. With the SET_ACCESS_PROFILE privilege, the proxy account can act on behalf of the application users.

Syntax:

PROCEDURE SET_ACCESS_PROFILE (policy_name IN VARCHAR2
  user_name   IN VARCHAR2);

Table 7-17 Parameters for SA_SESSION.SET_ACCESS_PROFILE

Parameter	Meaning
policy_name	The name of an existing policy
user_name	Name of the user whose authorizations and privileges should be assumed

7.6 Returning User Name with SA_SESSION.SA_USER_NAME

The SA_USER_NAME function returns the name of the current Oracle Label Security user, as set by the SET_ACCESS_PROFILE procedure (or as established at login). This is how you can determine the identity of the current user in relation to Oracle Label Security, rather than in relation to your Oracle login name.

Syntax:

FUNCTION SA_USER_NAME (policy_name IN VARCHAR2)
RETURN VARCHAR2;

Table 7-18 Parameters for SA_SESSION.SA_USER_NAME

Parameter	Meaning
policy_name	The name of an existing policy

7.7 Using Oracle Label Security Views

This section describes views you can use to see the user authorization and privilege assignments made by the administrator.

Note that the views are designed to display these values from two different perspectives. The DBA_SA_USERS view is optimized for users of the command-line interface. The component views are optimized for users of the Oracle Policy Manager administrative tool.

View to Display All User Security Attributes: DBA_SA_USERS
Views to Display User Authorizations by Component

7.7.1 View to Display All User Security Attributes: DBA_SA_USERS

The DBA_SA_USERS view displays the values assigned for privileges, levels, compartments, and groups all together, corresponding to how you enter these values through the SA_USER_ADMIN command-line interface. The values include:

USER_PRIVILEGES

MAX_READ_LABEL

MAX_WRITE_LABEL

MIN_WRITE_LABEL

DEFAULT_READ_LABEL

DEFAULT_WRITE_LABEL

DEFAULT_ROW_LABEL

USER_LABELS

MAX_READ_LABEL

MAX_WRITE_LABEL

MIN_WRITE_LABEL

DEFAULT_READ_LABEL

DEFAULT_WRITE_LABEL

DEFAULT_ROW_LABEL

This information is stored in data dictionary tables, and used to establish session and row labels when a user logs in.

Note:

The field USER_LABELS in DBA_SA_USERS is retained solely for backward compatibility and will be removed in the next release.

7.7.2 Views to Display User Authorizations by Component

The following views display individually each component of the label, corresponding to how you enter these values through Oracle Policy Manager.

Table 7-19 Oracle Label Security Views

View	Contents
DBA_SA_USER_LEVELS	Displays the levels assigned to the user: minimum level, maximum level, default level, and level for the row label
DBA_SA_USER_COMPARTMENTS	Displays the compartments assigned to the user
DBA_SA_USER_GROUPS	Displays the groups assigned to the user