Skip Headers
Oracle® XML DB Developer's Guide
11g Release 1 (11.1)

B28369-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

27 Access Control Lists and Security Classes

Oracle Database provides classic database security such as row-level and column-level secure access by database users. It also provides fine-grained access control for table data and for resources in Oracle XML DB Repository, for secure access by Oracle Fusion users (who are not necessarily database users). This chapter describes the access control lists and security classes that allow such fine-grained access control. It includes how to create, set, and modify ACLs and how ACL security interacts with other Oracle Database security mechanisms.

This chapter contains these topics:

See Also:

Access Control Concepts

This section describes several access control terms and concepts. Each of the entities described here, user, role, principal, privilege, security class, access control list (ACL), and access control entry (ACE), is implemented declaratively as an XML document or fragment.

Secure authorization requires defining which users, applications, or functions can have access to which data, to perform which kinds of operations. There are thus three dimensions: (1) which users can (2) perform which operations (3) on which data. We speak of (1) principals, (2) privileges, and (3) objects, corresponding to these three dimensions, respectively. Principals are users or roles.

Principals and privileges (dimensions 1 and 2) are related in a declarative way by defining access control lists. These are then related to the third dimension, data, in various ways, either declaratively or procedurally. For example, you can protect an Oracle XML DB Repository resource or table data by using PL/SQL procedure DBMS_XDB.setACL to set its controlling ACL.

Principals: Users and Roles

In the context of fine-grained database access control, a principal is a user or a role. A user can be any person or application that accesses information in the database. A role is composed of users and possibly other roles, but this recursion cannot be circular. Ultimately, each role, and thus each principal, corresponds to a set of users.

A user is represented for access control purposes by an XML fragment with element user; role is represented by a fragment with element role.

Oracle Database supports the following as principals:

  • Database users and database roles. A database user is also sometimes referred to as a database schema or a user account. When a person or application logs onto the database, it uses a database user (schema) and password. A database role corresponds to a set of database privileges that can be granted to database users, applications, or other database roles — see "Database Roles Map Database Privileges to Users".

  • Oracle Fusion users and Oracle Fusion roles. These are sometimes referred to as "lightweight" users and roles. They are defined by an application, and they need not be related in any way to database users or database roles.

    Although they can be users of database information, Oracle Fusion users are distinguished from database users (schemas). Oracle Fusion roles correspond to sets of Oracle Fusion users.

  • LDAP users and groups of LDAP users. For details on using LDAP principals see "Integrating Oracle XML DB with LDAP".

When a term such as "user" or "role" is used here without qualification, it applies to each type of user or role; when it is important to distinguish the type, the qualifier "database" or "Oracle Fusion" is used.

Database Roles Map Database Privileges to Users

A database role is traditionally thought of as a named set of database privileges, not as a set of database users, so the concept of role here is not exactly parallel to the case of an Oracle Fusion role.

In fact, a database role is granted privileges, just as a database user can be granted privileges. A database role serves as an intermediary for mapping database privileges to database users (and applications): a role is granted privileges, and the role is then granted to users (giving them the privileges). The line between a group of users and a group of privileges that are granted to those users is blurred a bit in the concept of database role: the role can serve to group the privileges that are mapped to the users and to group the users to which the privileges are mapped. The mapping is done by defining the role and granting it to users, and traditional terminology considers the role to be the same thing as the set of privileges that are granted to it.

In the context of fine-grained access control, a different mechanism, an access control list (ACL), is used as the intermediary that maps privileges to users. An Oracle Fusion role is simply a set of users, and a named set of privileges takes the form of a security class. In this context, the act of associating privileges with users and with roles is not a database grant; it is a declarative ACL entry, together with a runtime evaluation of ACLs and resolution of ACL conflicts.

Please keep this terminology difference in mind, to avoid confusion. As a means of mapping privileges to users, a database role combines some of the functionality that in the Oracle Fusion context is divided into (1) principals, (2) privileges and security classes, and (3) ACLs. In access control terminology, roles are classified with users as principals; in traditional database terminology, roles are instead classified as sets of privileges.

Role Sets

A role set is a set of roles, at most one of which can be active at a time: when you make one role in a role set active, the other roles in the same set become inactive. You can think of a role set as a set of radio buttons: only one button stays depressed at a time. (However, there is no requirement than any role in a role set be active; they can all be inactive at the same time.) Oracle Database enforces this behavior automatically, which can simplify the logic of your application.

A role can belong to any number of role sets, and a role set can contain any number of roles. All role sets apply all of the time. This implies that when a role that belongs to more than one role set is active, all of the other roles in those same role sets are inactive. For example, if role set A contains roles r1, r2, and r3, and role set B contains roles r2, r4, and r5, then, whenever role r2 is active, roles r1, r3, r4, and r5 are inactive.

Principal DAV::owner

You can use the DAV::owner principal in connection with a given Oracle XML DB Repository resource to refer to the resource owner. The owner of a resource is one of the properties of the resource. You can use principal DAV::owner to facilitate ACL sharing among principals, because the owner of a resource often has special rights.

Privileges

A privilege is a particular right or permission that can be granted or denied to a principal. Oracle Database has a set of system-defined privileges (such as READ or UPDATE). Applications can define additional, custom privileges.

A privilege is one of the following:

  • Aggregate privilege – a privilege that includes other privileges.

  • Atomic privilege – a privilege that cannot be subdivided: it does not include other privileges.

Aggregate privileges simplify usability when the number of privileges becomes large, and they promote interoperability between ACL clients. See "System Security Classes" for information about the predefined atomic and aggregate system privileges.

Aggregate privileges retain their identity: they are not decomposed into the corresponding atomic (leaf) privileges; in WebDAV terms, Oracle Database aggregate privileges are not abstract. This implies that an aggregate privilege acts as a set of pointers to its component privileges, rather than a copy of those components. Thus, an aggregate privilege is always up to date, even if the definition of a component changes.

The set of privileges granted to a principal controls whether that principal can perform a given operation on the data that it protects. For example, if the principal (database user) HR wants to perform the read operation on a given resource, then read privileges must be granted to principal HR prior to the read operation.

Security Classes

A security class is a named set of privileges. It includes privileges that it inherits from other security classes, and it can include privileges that it defines. Privileges defined in a security class that you create are called custom privileges. Privileges that are predefined by Oracle Database are called system privileges.

Protected Objects

Nearly any database data can be protected using the fine-grained access control described in this chapter. This chapter describes protection of Oracle XML DB Repository resources.

Access Control Entry (ACE)

An access control entry (ACE) is an XML element (ace) that is an entry in an access control list (ACL). An ACE either grants or denies access to some repository resource or other database data by a particular principal (user or role). The ACE does not, itself, specify which data to protect; that is done outside the ACE and the ACL, by associating the ACL with target data. One way to make that association is by using PL/SQL procedure DBMS_XDB.setACL.

See "ACL and ACE Evaluation".

An Oracle XML DB ACE either grants or denies privileges for a principal. An ace element has the following:

  • Operation: Either grant or deny.

  • Principal: A valid principal (element principal).

  • Privileges: A set of privileges to be granted or denied for a particular principal (element privilege).

  • Principal format (optional): The format of the principal. An LDAP distinguished name (DN), a short name (database user/role or LDAP nickname), or an LDAP GUID. The default value is short name. If the principal name matches both a database user and an LDAP nickname, it is assumed to refer to the LDAP nickname.

  • Collection (optional): A BOOLEAN attribute that specifies whether the principal is a collection of users (LDAP group or database role) or a single user (LDAP or database user).

Example 27-1 shows a simple ACE that grants privilege DAV::all to principal DAV::owner. This means that it grants all privileges to the owner of the resource to which its ACL applies.

Example 27-1 Simple Access Control Entry (ACE) that Grants a System Privilege

<ace>
  <grant>true</grant>
  <principal>DAV::owner</principal>
  <privilege>
    <DAV::all/>
  </privilege>
</ace>

Access Control List (ACL)

An access control list (ACL) is a list of access control entries (ACEs). By default, order in the list is relevant (see "ACL and ACE Evaluation"). Example 27-2 shows a simple ACL that contains only the ACE of Example 27-1.

Example 27-2 Simple Access Control List (ACL) that Grants a System Privilege

<acl description="myacl"
     xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
     xmlns:dav="DAV:"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                         http://xmlns.oracle.com/xdb/acl.xsd">
  <ace>
    <grant>true</grant>
    <principal>dav:owner</principal>
    <privilege>
      <dav:all/>
    </privilege>
  </ace>
</acl>

Database Privileges for Repository Operations

Table 27-1 shows the database privileges required for some common operations on resources in Oracle XML DB Repository. In addition to the privileges listed in column Privileges Required you must have the resolve privilege for the folder containing the resource and for all of its parent folders, up to the root folder.

Table 27-1 Database Privileges Needed for Operations on Oracle XML DB Resources

Operation Description Privileges Required

CREATE

Create a new resource in folder F

update and link on folder F

DELETE

Delete resource R from folder F

update and unlink-from on R, update and unlink on folder F

UPDATE

Update the contents or properties of resources R

update on R

GET

An FTP or HTTP(S) retrieval of resource R

read-properties, read-contents on R

SET_ACL

Set the ACL of a resource R

DAV::write-acl on R

LIST

List the resources in folder F

read-properties on folder F, read-properties on resources in folder F. Only those resources on which the user has read-properties privilege are listed.


See Also:

"Upgrading an Existing Oracle XML DB Installation" for information about treatment of database access privileges when upgrading

Security Classes

A security class defines a set of custom privileges, that is, privileges that are not system privileges. To facilitate reusability, a security class can inherit privileges from one or more other security classes. Inheritance cycles are not permitted, so a security class cannot inherit privileges, directly or indirectly, from itself.

Example 27-3 shows the XML document that defines a simple security class named iStorePurchaseOrder.

Example 27-3 Simple Security Class

<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd"
               xmlns:is="xmlns.oracle.com/iStore"
               xmlns:oa="xmlns.oracle.com/OracleApps"
               targetNamespace="xmlns.oracle.com/iStore">
               name="iStorePurchaseOrder">
  <title xml:lang="en" xdb:srclang="true">
Security Class Example
  </title>
  <inherits-from>oa:PurchaseOrder</inherits-from>
  <privilege name="privilege1"/>
  <aggregatePrivilege name="iStorePOApprover">
    <title xml:lang="en">
iStore Purchase Order Approver
    </title>
    <privilegeRef name="is:privilege1"/>
    <privilegeRef name="oa:submitPO"/>
    <privilegeRef name="oa:privilege3"/>
  </aggregatePrivilege>
  <privilege name="privilege2">
    <title xml:lang="en" xdb:srclang="true">
Secondary Privilege
    </title>
    <title xml:lang="fr">
Deuxieme Privilège
    </title>
  </privilege>
</securityClass>

The privileges that defined by security class iStorePurchaseOrder are iStorePOApprover, privilege1, and privilege2; they are the only privileges that it makes available. These privileges are all in the target XML namespace for iStorePurchaseOrder, which has prefix is.

Security class iStorePurchaseOrder inherits from security class oa:PurchaseOrder, which means that it can include privileges from oa:PurchaseOrder.

Privileges privilege1 and privilege2 are atomic privileges (they are defined with element privilege). Privilege iStorePOApprover is an aggregate privilege (it is defined with element aggregatePrivilege). The privileges that compose iStorePOApprover are is:privilege1, oa:submitPO, and oa:privilege3.

Privileges oa:submitPO, and oa:privilege3 are in the namespace that uses prefix oa; they are inherited from security class oa:PurchaseOrder. Privilege privilege1 is in the target namespace, is.

The title elements in the security class definition define screen names for the security class (Security Class Example) and two of the privileges it contains (iStore Purchase Order Approver for privilege iStorePOApprover and Secondary Privilege for privilege privilege2). No title is defined for privilege privilege1. Privilege privilege2 actually has two different titles, for two different languages: Secondary Privilege is the title for the default language, English (xml:lang="en"), and Deuxieme Privilege is the title for French (xml:lang="fr").

See Also:

"XML Translations" for information about translation and use of natural languages(xml:lang) in XML data

Security Class as ACL Type

An access control list (ACL) has a single security class as its type. An ACL grants privileges to principals, to control access to protected data or functionalities; it can grant only the privileges that are defined in its security class. An ACL declares its security class with element security-class (see Example 27-6). If no such element is present in an ACL, then its type is the default security class, DAV::dav, which defines system privileges. Different ACLs can have as their type the same security class.

System Security Classes

This section describes the predefined, or system, security classes that are provided with Oracle Database. The privileges that these security classes define are system privileges. Privilege names are used as XML element names.

Security Class DAV::dav

Security class dav is itself in XML namespace DAV:.Foot 1  It includes privileges that are in two XML namespaces:

  • The WebDAV namespace, DAV:

  • The Oracle XML DB ACL namespace, http://xmlns.oracle.com/xdb/acl.xsd, which has the predefined prefix xdb

Security class DAV::dav includes all privileges defined by the WebDAV standard.

See Also:

RFC 3744: "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", IETF Network Working Group Request For Comments #3744, May 2004

Atomic Privileges in Security Class DAV::dav

Table 27-2 lists the atomic privileges made available by security class DAV::dav..

Table 27-2 Atomic Privileges in Security Class DAV::dav

Atomic Privilege Description Database Counterpart

DAV::lock

Lock a resource using WebDAV locks.

UPDATE

DAV::read-current-user-privilege-set

Access the DAV::current-user-privilege-set property of a resource.

N/A

DAV::take-ownership

Take ownership of a resource.

N/A

DAV::unlock

Unlock a resource locked using a WebDAV lock.

UPDATE

DAV::write-content

Modify the content of a resource.

UPDATE

DAV::write-properties

Modify the properties of a resource; lock or unlock a resource. Modifiable properties include Author, DisplayName, Language, CharacterSet, ContentType, SBResExtra, Owner, OwnerID, CreationDate, Modification Date, ACL, ACLOID, Lock, and Locktoken.

UPDATE

xdb:link

Allow creation of links from a resource.

INSERT

xdb:link-to

Allow creation of links to a resource.

N/A

xdb:read-acl

Read the ACL of a resource.

SELECT

xdb:read-contents

Read the contents of a resource.

SELECT

xdb:read-properties

Read the properties of a resource.

SELECT

xdb:resolve

Traverse a folder (for folders only).

SELECT

xdb:unlink

Allow deletion of links from a resource.

DELETE

xdb:unlink-from

Allow deletion of links to a resource.

N/A

xdb:update-acl

Change the contents of the resource ACL.

UPDATE

xdb:write-acl-ref

Change the ACLOID of a resource.

UPDATE


Aggregate Privileges in Security Class DAV::dav

Table 27-3 lists the aggregate privileges made available by security class DAV:dav, along with the atomic privileges of which they are composed.

Table 27-3 Aggregate Privileges Defined by Security Class DAV::dav

Aggregate Privilege Component Atomic System Privileges

DAV:all

All atomic privileges defined by security class except xdb:linkto.

xdb:all

All atomic privileges defined by security class DAV::dav (including xdb:link-to)

DAV::bind

xdb:link

DAV::unbind

xdb:unlink

DAV::read

xdb:read-properties, xdb:read-contents, xdb:resolve

DAV::read-acl

xdb:read-acl

DAV::write

DAV::write-contents, DAV::write-properties, xdb:link, xdb:unlink, xdb:unlink-from

DAV::write-acl

xdb:write-acl-ref, xdb:update-acl

DAV::update

DAV::write-contents, DAV::write-properties

xdb:update

DAV::write-properties, DAV::write-content


Security Class PrincipalSecurityClass

Security class PrincipalSecurityClass defines privileges in the Extensible Security namespace, http://xmlns.oracle.com/xs. It inherits from security class DAV::dav.

Atomic Privileges Defined by Security Class PrincipalSecurityClass

Table 27-4 lists the atomic privileges defined by security class PrincipalSecurityClass.

Table 27-4 Atomic Privileges Defined by Security Class PrincipalSecurityClass

Atomic Privilege Description

proxyTo

Change the proxyUserType element in a user document. This element identifies which users can proxy on behalf of another user whose document is being changed.

enable

Change the enable attribute in a role document. This attribute determines whether a role is enabled by default.

addtoSet

Add the current role to a role set.

createSession

Create an Oracle Fusion session

termSession

Terminate an Oracle Fusion session

attachToSession

Attach to an Oracle Fusion session

modifySession

Modify the contents of an Oracle Fusion session

switchUser

Switch the user of an Oracle Fusion session

assignUser

Assign a user to an anonymous Oracle Fusion session

changeUserPassword

Change the passwords for Oracle Fusion users

administerNamespace

Create, delete or modify namespace properties

setAttribute

Set an Oracle Fusion session attribute

readAttribute

Read the value of an Oracle Fusion session attribute


Aggregate Privileges Defined by Security Class PrincipalSecurityClass

Table 27-5 lists the aggregate privileges defined by security class PrincipalSecurityClass, along with the atomic privileges of which they are composed. Privileges listed without a namespace prefix are in the Extensible Security namespace, http://xmlns.oracle.com/xs.

Table 27-5 Aggregate Privileges Defined by Security Class PrincipalSecurityClass

Aggregate Privilege Component Atomic System Privileges

viewUser

xdb:read-contents, xdb:resolve

grant

xdb:link-to, xdb:unlink-from, xdb:read-contents, xdb:resolve

grantTo

xdb:link, xdb:unlink, xdb:update, xdb:read-contents

viewRole

xdb:read-contents, xdb:resolve

viewRoleset

xdb:read-contents

admin

xdb:read-properties, xdb:read-contents, xdb:update, xdb:link, xdb:unlink, xdb:link-to, xdb:unlink-from, xdb:read-acl, xdb:write-acl-ref, xdb:update-acl, xdb:resolve

createTermSession

createSession, termSession

administerSession

createTermSession, attachToSession, modifySession, switchUser, assignUser, administerNamespace

administerPrivilege

setAttribute, readAttribute


ACLs and ACEs

An access control list (ACL) is a standard security mechanism that is used in some languages, such as Java, and some operating systems, such as Microsoft Windows. ACLs are also a part of the WebDAV standard. ACLs are used to protect resources, which in the case of Oracle Database can be either resources (files and folders) in Oracle XML DB Repository or database table data.

Repository resources can be accessed using WebDAV, and their protecting ACLs act as WebDAV ACLs. Each repository resource is protected by some ACL. ACLs that protect a resource are enforced no matter how the resource is accessed, whether by WebDAV, SQL, or any other way.

When a new resource is created in Oracle XML DB Repository, by default the ACL on its parent folder is used to protect the resource. After the resource is created, a new ACL can be set on it.

ACLs in Oracle Database are XML documents that are validated against the Oracle Database ACL XML schema, which is located in Oracle XML DB Repository at /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/acl.xsd. ACLs are themselves stored and managed as resources in the repository.

Before a principal performs an operation on a ACL-protected data, the user privileges on the protected data are checked. The set of privileges checked depends on the operation to be performed.

Aggregate privileges are composed of other privileges. When an ACL is stored, the aggregate privileges it refers to act as sets of pointers to their component privileges. This implies that if a custom aggregate privilege is later updated to include additional child privileges, no change is needed to any ACL that references it; the ACL is always up-to-date with respect to privileges it references.

All ACLs are stored in table XDB$ACL, which is owned by database user XDB. This is an XML schema-based XMLType table. Each row in this table (and therefore each ACL) has a system-generated object identifier (OID) that can be accessed as a column named OBJECT_ID.

Each Oracle XML DB Repository resource has a property named ACLOID. The ACLOID stores the OID of the ACL that protects the resource. An ACL is itself a resource, and the XMLRef property of an ACL, for example, /sys/acls/all_all_acl.xml, is a REF to the row in table XDB$ACL that contains the content of the ACL. These two properties form the link between table XDB$RESOURCE, which stores Oracle XML DB resources, and table XDB$ACL.

See Also:

System ACLs

Some ACLs are predefined and supplied with Oracle Database; they are referred to as system ACLs.

There is only one ACL that is self-protected, that is, protected by its own contents. It is the bootstrap ACL, a system ACL that is located in Oracle XML DB Repository at /sys/acls/bootstrap_acl.xml. The bootstrap ACL grants READ privilege to all users. It also grants FULL ACCESS to database roles XDBADMIN (the Oracle XML DB ADMIN) and DBA. Database role XDBADMIN is particularly useful for users who must register global XML schemas.

Other system ACLs include the following. Each is protected by the bootstrap ACL.

  • all_all_acl.xml – Grants all privileges to all users.

  • all_owner_acl.xml – Grants all privileges to the owner of the resource.

  • ro_all_acl.xml – Grants read privileges to all users.

System ACLs use the file-naming convention <privilege>_<users>_acl.xml, where <privilege> represents the privilege granted, and <users> represents the users that are granted access to the resource. When you define your own ACLs, you can use any names you like.

ACL and ACE Evaluation

Privileges are checked before a principal is allowed to access a database object, such as a repository resource, that is protected by one or more ACLs. This check is done by evaluating protecting ACLs for that principal, in order. For each such ACL, the ACEs in it that apply to the principal are examined, in order.

If one ACE grants a certain privilege to the current user and another ACE denies that privilege to the user, then a conflict arises. There are two possible ways to manage conflicts among ACEs for the same principal.

  • The default behavior, termed ace-order, is to use only the first ACE that occurs for a given principal; additional ACEs for that principal have no effect. In this case, ACE order is relevant.

  • You can, however, configure the database to use an alternate behavior, deny-trumps-grant. In this case, any ACE with child deny for a given principal denies permission to that principal, whether or not there are other ACEs for that principal that have a grant child. In this case, deny always takes precedence over grant, and ACE order is irrelevant.

You can configure ACL evaluation behavior by setting configuration parameter acl-evaluation-method, in configuration file xdbconfig.xml, to either ace-order or deny-trumps-grant. The default configuration file specifies ace-method, but the default value for element acl-evaluation-method, used when no method is given, is deny-trumps-grant.

Note:

In releases prior to Oracle Database 11g Release 1, only one ACL evaluation behavior was available: deny-trumps-grant (though it was not specified in the configuration file).

The change to use ace-order as the default behavior has important consequences for upgrading and downgrading between database versions. See "Upgrading an Existing Oracle XML DB Installation".

ACL Validation

When an ACL is created, it is validated against the XML schema for ACLs, and some correctness tests are run, such as ensuring that start and end dates for ACEs are in chronological order. There is no complete check at ACL creation time of relations among ACLs or relations between ACLs and security classes. For example, no check is made at creation for the existence and correctness of a parent ACL and security class, and no check is made for unresolved or invalid custom privileges, such as privileges that are not defined in the security class.

Such a complete check of ACL correctness is called ACL validity checking, but it is not to be confused with its XML schema validity. For an ACL to be valid (as an ACL), it must also be XML schema valid, but the converse does not hold.

A full ACL validity check is made at runtime, whenever an ACL is evaluated to check whether a principal has the proper privileges for some operation. If this check finds that the ACL is invalid, then all privileges that the ACL would grant are denied to the specified principals.

ACL validity can also be checked independently of its runtime use to check privileges, by invoking PL/SQL procedure DBMS_XDBZ.validateACL. You can do this ahead of time, to avoid runtime errors or privilege denial due to ACL invalidity.

ACL Inheritance

An ACL can inherit ACEs, that is, associations of principals with privileges, from another ACL. Inheritance provides flexibility of definition and promotes reuse of access control policies.

Unlike security-class inheritance, this is not multiple inheritance: an ACL inherits from at most one other ACL. Cycles are not permitted in an inheritance chain: an ACL that inherits directly or indirectly from itself is invalid. An ACL that inherits from an ACL that does not exist is also invalid.

There are two kinds of ACL inheritance, extending inheritance and constraining inheritance, specified using element extends-from or element constrained-with, respectively. Both elements reference the ACL being inherited from. An ACL can have at most one extends-from or constrained-with element. Example 27-4 shows an extends-from element; Example 27-5 shows a constrained-with element.

Example 27-4 Element extends-from

<extends-from type="simple" href="/sys/acls/extend_acl.xml"/>

Example 27-5 Element constrained-with

<constrained-with type="simple" href="/sys/acls/constrain_acl.xml"/>

Extending inheritance extends the grants that are explicitly declared in the inheriting ACL (the child ACL) by some grants that are defined by the ACL it is inheriting from (the parent ACL). For example, if ACL A1 declares that it extends from ACL A2, then A1 can include ACEs from A2.

Constraining inheritance restricts the grants that are explicitly declared in the inheriting ACL to grants that are also defined by the ACL it is inheriting from. For example, if ACL A1 declares that it inherits from ACL A2 by constraining, then all ACEs in A1 must also be defined by A2.

Extending inheritance is a set union operation, and constraining inheritance is a set intersection operation. When ACL A1 extends from ACL A2, the ACEs in both can be combined to determine whether a given principal is granted a given privilege. When ACL A1 is constrained with ACL A2, only the ACEs that are common to both A1 and A2 are used to determine a grant.

More precisely, when ACL A1 inherits from ACL A2, and A1 is checked to see if a given principal has been granted a given set of privileges, determination proceeds as follows:

  • A1 extends from A2 – The ACEs that are explicitly declared in A1 are examined first. If they do not grant all or deny any of the privileges in question to the principal, then the ACEs defined in the extending-from parent of A1 are examined. This in turn means that if the ACEs that are explicitly declared in A2 do not grant all or deny any of the privileges in question to the principal, and if A2 extends from A3, then A3 is examined; and so on.

  • A1 is constrained by A2 – The ACEs that are explicitly declared in A1 and those defined for A2 are each examined separately to ensure that they both grant all of the privileges in question to the specified principal. The check for A2 proceeds the same way if it is constrained by ACL A3, and so on.

Put another way, extending inheritance accumulates granted privileges and constraining inheritance accumulates denied privileges. In extending inheritance, if either the child or the parent ACL grants a privilege to the principal, then the privilege is granted. In constraining inheritance, if either the child or the parent ACL denies a privilege, then it is denied.

See Also:

Example 27-6 for an ACL that uses extending inheritance

Complementing the Principals in an ACE: Element invert

It is sometimes more convenient to define a set of principals by complementing another set of principals — that is the purpose of ACE element invert. Instead of listing each of the principals you want to include, enclose the list of principals you want to exclude with invert.

In Example 27-6, the first ACE denies privilege privilege1 to all principals except IntranetUsers. Because (by default) ACEs are considered in the order they appear, all subsequent ACEs are overridden by the first ACE, so principal NonIntraNetUser is denied privilege privilege1 in spite of the explicit grant.

Example 27-6 Complementing a Set of Principals with Element invert

<acl description="iStore ACL" 
     xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
     xmlns:is="xmlns.oracle.com/iStore" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
     xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd       
                         http://xmlns.oracle.com/xdb/acl.xsd">
  <security-class>is:iStorePurchaseOrder</security-class>
  <extends-from type="simple" href="/sys/acls/parent_acl.xml"/>
  <ace>
    <grant>false</grant>
    <invert><principal>IntranetUsers</principal></invert>
    <privilege><is:privilege1/></privilege>
  </ace>
  <ace>
    <grant>true</grant>
    <principal>NonIntraNetUser</principal>
    <privilege><is:privilege1/></privilege>
  </ace>
</acl>

ACE Validity Time Period

You can use optional attributes start_date and end_date (of XML Schema type dateTime) to define the time period over which an ACE is valid. If start_date is specified, then the ACE is valid on and after that date. If end_date is specified, then the ACS is invalid after that date. The end_date value must follow the start_date chronologically or else be the same value; otherwise, the ACE and its ACL are invalid. If no time zone is specified in an XML Schema dateTime value, then GMT (UTC) is assumed. Example 27-7 shows an ACE with start and end dates.

Example 27-7 ACE with Start and End Dates

<ace start_date="2008-02-12T00:00:00Z" end_date="2008-12-31T00:00:00Z">
  <grant>true</grant>
  <principal>geronimo</principal>
  <privilege><is:storePOApprover/></privilege>
</ace>

Working with Access Control Lists (ACLs)

Oracle Database access control lists (ACLs) are themselves (file) resources in Oracle XML DB Repository, so all of the methods that operate on repository resources also apply to ACLs. In addition, there are several APIs specific to ACLs in package DBMS_XDB. Those procedures and functions let you use PL/SQL to access Oracle XML DB security mechanisms, check user privileges based on a particular ACL, and list the set of privileges the current user has for a particular ACL and resource.

Creating an ACL Using DBMS_XDB.createResource

Example 27-8 creates an ACL as file resource /TESTUSER/acl1.xml. If applied to a resource, this ACL grants all privileges to the owner of a resource.

Example 27-8 Creating an ACL Using DBMS_XDB.createResource

DECLARE
  b BOOLEAN;
BEGIN
  b := DBMS_XDB.createFolder('/TESTUSER');
  b := DBMS_XDB.createResource(
         '/TESTUSER/acl1.xml', 
         '<acl description="myacl"
               xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
               xmlns:dav="DAV:"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                   http://xmlns.oracle.com/xdb/acl.xsd">
            <ace>
              <grant>true</grant>
              <principal>dav:owner</principal>
              <privilege>
                <dav:all/>
              </privilege>
            </ace>
          </acl>');
END;

Note:

Before performing any operation that uses an ACL file resource that was created during the current transaction, you must perform a COMMIT operation. Until you do that, an ORA-22881 "dangling REF" error will be raised whenever you use the ACL file.

Retrieving an ACL Document, Given its Repository Path

Example 27-9 shows how to retrieve an ACL document, given its location in Oracle XML DB Repository.

Example 27-9 Retrieving an ACL Document, Given its Repository Path

SELECT a.OBJECT_VALUE FROM RESOURCE_VIEW r, XDB.XDB$ACL a
  WHERE ref(a) = extractValue(r.RES, '/Resource/XMLRef')
    AND equals_path(r.RES, '/TESTUSER/acl1.xml') = 1;

OBJECT_VALUE
--------------------------------------------------------------------------------
<acl description="myacl" xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="
DAV:" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://xmlns.oracle.com/xdb/acl.xsd                                    http://xm
lns.oracle.com/xdb/acl.xsd" shared="true">
  <ace>
    <grant>true</grant>
    <principal>dav:owner</principal>
    <privilege>
      <dav:all/>
    </privilege>
  </ace>
</acl>
 
1 row selected.

Setting the ACL of a Resource

Example 27-10 Setting the ACL of a Resource

This example creates resource /TESTUSER/po1.xml and sets its ACL to /TESTUSER/acl1.xml using PL/SQL procedure DBMS_XDB.setACL.

DECLARE
  b BOOLEAN;
BEGIN
  b := DBMS_XDB.createResource('/TESTUSER/po1.xml', 'Hello');
END;
/
 
CALL DBMS_XDB.setACL('/TESTUSER/po1.xml', '/TESTUSER/acl1.xml');

Deleting an ACL

Example 27-11 illustrates how to delete an ACL using procedure DBMS_XDB.deleteResource.

Example 27-11 Deleting an ACL

This example deletes the ACL created in Example 27-8.

CALL DBMS_XDB.deleteResource('/TESTUSER/acl1.xml');

If a resource is being protected by an ACL that you will delete, first change the ACL of that resource before deleting the ACL.

Updating an ACL

This can be done using standard methods for updating resources. In particular, since an ACL is an XML document, SQL function updateXML and related XML-updating functions can be used to manipulate ACLs. Oracle XML DB ACLs are cached, for fast evaluation. When a transaction that updates an ACL is committed, the modified ACL is picked up by existing database sessions, after the timeout specified in the Oracle XML DB configuration file, /xdbconfig.xml. The XPath location for this timeout parameter is /xdbconfig/sysconfig/acl-max-age; the value is expressed in seconds. Sessions initiated after the ACL is modified use the new ACL without any delay.If an ACL resource is updated with non-ACL content, the same rules apply as for deletion. Thus, if any resource is being protected by an ACL that is being updated, you must first change the ACL.

See Also:

"Updating XML Instances and XML Data in Tables" for information about the SQL functions used here to update XML data

You can use FTP or WebDAV to update an ACL. For more details on how to use these protocols, see Chapter 28, "Using Protocols to Access the Repository". You can update an ACL or an access control entry (ACE) using RESOURCE_VIEW.

Example 27-12 Updating (Replacing) an Access Control List

This example uses SQL function updateXML to update the ACL /TESTUSER/acl1.xml by replacing it entirely. The effect is to replace the principal value DAV::owner by TESTUSER, because the rest of the replacement ACL is the same as it was before.

UPDATE RESOURCE_VIEW r
  SET r.RES =
        updateXML(
          r.RES,
          '/r:Resource/r:Contents/a:acl',
          '<acl description="myacl"
                xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
                xmlns:dav="DAV:"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                    http://xmlns.oracle.com/xdb/acl.xsd">
             <ace>
               <grant>true</grant>
               <principal>TESTUSER</principal>
               <privilege>
                 <dav:all/>
               </privilege>
             </ace>
           </acl>',
          'xmlns:r="http://xmlns.oracle.com/xdb/XDBResource.xsd"
           xmlns:a="http://xmlns.oracle.com/xdb/acl.xsd"')
  WHERE equals_path(r.RES, '/TESTUSER/acl1.xml') = 1;

Example 27-13 Appending ACEs to an Access Control List

This example uses SQL function appendChildXML to append an ACE to an existing ACL. The ACE gives privileges read-properties and read-contents to user hr.

UPDATE RESOURCE_VIEW r
  SET r.RES =
        appendChildXML(
          r.RES,
          '/r:Resource/r:Contents/a:acl',
          XMLType('<ace xmlns="http://xmlns.oracle.com/xdb/acl.xsd">
                     <grant>true</grant>
                     <principal>HR</principal>
                     <privilege>
                       <read-properties/>
                       <read-contents/>
                     </privilege>
                   </ace>'),
                  'xmlns:r="http://xmlns.oracle.com/xdb/XDBResource.xsd"
                   xmlns:a="http://xmlns.oracle.com/xdb/acl.xsd"')
  WHERE equals_path(r.RES, '/TESTUSER/acl1.xml') = 1;

Example 27-14 Deleting an ACE from an Access Control List

This examples uses SQL function deleteXML to delete an ACE from an ACL. The first ACE is deleted here.

UPDATE RESOURCE_VIEW r
  SET r.RES =
        deleteXML(r.RES,
                  '/r:Resource/r:Contents/a:acl/a:ace[1]',
                  'xmlns:r="http://xmlns.oracle.com/xdb/XDBResource.xsd"
                   xmlns:a="http://xmlns.oracle.com/xdb/acl.xsd"')
  WHERE equals_path(r.RES, '/TESTUSER/acl1.xml') = 1;

Retrieving the ACL Document that Protects a Given Resource

Example 26-2 illustrates how to use function DBMS_XDB.getACLDocument to retrieve the ACL document that protects a given resource.

Example 27-15 Retrieving the ACL Document for a Resource

SELECT DBMS_XDB.getACLDocument('/TESTUSER/po1.xml').getCLOBVal() FROM DUAL;
 
DBMS_XDB.GETACLDOCUMENT('/TESTUSER/PO1.XML').GETCLOBVAL()
--------------------------------------------------------------------------------
<acl description="myacl" xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="
DAV:" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://xmlns.oracle.com/xdb/acl.xsd                                     http://x
mlns.oracle.com/xdb/acl.xsd">
  <ace>
    <grant>true</grant>
    <principal>TESTUSER</principal>
    <privilege>
      <dav:all/>
    </privilege>
  </ace>
  <ace xmlns="http://xmlns.oracle.com/xdb/acl.xsd">
    <grant>true</grant>
    <principal>HR</principal>
    <privilege>
      <read-properties/>
      <read-contents/>
    </privilege>
  </ace>
</acl>
 
1 row selected.

Retrieving Privileges Granted to the Current User for a Particular Resource

Example 27-16 illustrates how to retrieve privileges granted to the current user using function DBMS_XDB.getPrivileges.

Example 27-16 Retrieving Privileges Granted to the Current User for a Particular Resource

SELECT DBMS_XDB.getPrivileges('/TESTUSER/po1.xml').getCLOBVal() FROM DUAL;
 
DBMS_XDB.GETPRIVILEGES('/TESTUSER/PO1.XML').GETCLOBVAL()
--------------------------------------------------------------------------------
<privilege xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:xsi="http://www.w3.
org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl
.xsd http://xmlns.oracle.com/xdb/acl.xsd DAV: http://xmlns.oracle.com/xdb/dav.xs
d" xmlns:xdbacl="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="DAV:">
  <dav:take-ownership/>
  <dav:execute/>
  <dav:unlock/>
  <read-properties/>
  <dav:lock/>
  <read-contents/>
  <dav:read-current-user-privilege-set/>
  <write-config/>
  <dav:write-content/>
  <resolve/>
  <dav:write-properties/>
  <unlink-from/>
  <unlink/>
  <read-acl/>
  <write-acl-ref/>
  <update-acl/>
  <link/>
</privilege>

1 row selected.

Checking if the Current User Has Privileges on a Resource

Example 27-17 illustrates how to use function DBMS_XDB.checkPrivileges to check if the current user has a given set of privileges on a resource. This function returns a nonzero value if the user has the privileges.

Example 27-17 Checking If a User Has a Certain Privileges on a Resource

This example checks to see if the access privileges read-contents and read-properties have been granted to the current user on resource /TESTUSER/po1.xml. The positive-integer return value shows that they have.

SELECT DBMS_XDB.checkPrivileges(
         '/TESTUSER/po1.xml',
         XMLType('<privilege
                      xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
                      xmlns:dav="DAV:"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                          http://xmlns.oracle.com/xdb/acl.xsd">
                    <read-contents/>
                    <read-properties/>
                  </privilege>'))
  FROM DUAL;
 
DBMS_XDB.CHECKPRIVILEGES('/TESTUSER/PO1.XML',
---------------------------------------------
                                            1
 
1 row selected.

Checking if the Current User Has Privileges With the ACL and Resource Owner

Function DBMS_XDB.ACLCheckPrivileges is typically used by applications that must perform ACL evaluation on their own, before allowing a user to perform an operation.

Example 27-18 Checking User Privileges using ACLCheckPrivileges

This example checks whether the ACL /TESTUSER/acl1.xml grants the privileges read-contents and read-properties to the current user, sh. The second argument, TESTUSER, is the user that is substituted for DAV::owner in the ACL when checking. Since user sh does not match any of the users granted the specified privileges, the return value is zero.

CONNECT sh
Enter password: <password>

Connected.

SELECT DBMS_XDB.ACLCheckPrivileges(
         '/TESTUSER/acl1.xml',
         'TESTUSER',
         XMLType('<privilege
                      xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
                      xmlns:dav="DAV:"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                          http://xmlns.oracle.com/xdb/acl.xsd">
                    <read-contents/>
                    <read-properties/>
                  </privilege>'))
  FROM DUAL;
 
DBMS_XDB.ACLCHECKPRIVILEGES('/TESTUSER/ACL1.XML','TESTUSER',
------------------------------------------------------------
                                                           0
 
1 row selected.

Retrieving the Path of the ACL that Protects a Given Resource

Example 27-19 retrieves the path of the ACL that protects a given resource, by using a RESOURCE_VIEW query. The query uses the fact that the XMLRef and ACLOID elements of the resource form the link between an ACL and a resource.

Example 27-19 Retrieving the Path of the ACL that Protects a Given Resource

This example retrieves the path to an ACL, given a resource protected by the ACL. The ACLOID of a protected resource (r) stores the OID of the ACL resource (a) that protects it. The REF of the ACL resource is the same as that of the object identified by the protected-resource ACLOID.

The REF of the resource ACLOID can be obtained using SQL function make_ref, which returns a REF to an object-table row with a given OID.

In this example, make_ref returns a REF to the row of table XDB$ACL whose OID is the /Resource/ACLOID for the resource /TESTUSER/po1.xml (r). The inner query returns the ACLOID of the resource. The outer query returns the path to the corresponding ACL.

SELECT a.ANY_PATH
  FROM RESOURCE_VIEW a
  WHERE extractValue(a.RES, '/Resource/XMLRef')
        = make_ref(XDB.XDB$ACL,
                   (SELECT extractValue(r.RES, '/Resource/ACLOID')
                      FROM RESOURCE_VIEW r
                      WHERE equals_path(r.RES, '/TESTUSER/po1.xml') = 1));
 
ANY_PATH
------------------
/TESTUSER/acl1.xml
 
1 row selected.

Retrieving the Paths of All Resources Protected by a Given ACL

Example 27-20 retrieves the paths of all resources protected by a given ACL.

Example 27-20 Retrieving the Paths of All Resources Protected by a Given ACL

This example retrieves the paths to the resources whose ACLOID REF matches the REF of the ACL resource whose path is /TESTUSER/acl1.xml. Function make_ref returns the resource ACLOID REF.

The inner query retrieves the REF of the specified ACL. The outer query selects the paths of the resources whose ACLOID REF matches the REF of the specified ACL.

SELECT r.ANY_PATH
  FROM RESOURCE_VIEW r
  WHERE make_ref(XDB.XDB$ACL, extractValue(r.RES, '/Resource/ACLOID'))
        = (SELECT extractValue(a.RES, '/Resource/XMLRef')
             FROM RESOURCE_VIEW a
             WHERE equals_path(a.RES, '/TESTUSER/acl1.xml') = 1);
 
ANY_PATH
-----------------
/TESTUSER/po1.xml
 
1 row selected.

ACL Caching

Since ACLs are checked for each access to the data they protect, the performance of the ACL check operation is critical to the performance of such data, including Oracle XML DB Repository resources. In Oracle XML DB, the required performance for this repository operation is achieved by employing several caches.

ACLs are saved in a cache that is shared by all sessions in the database instance. When an ACL is updated, its entry in the cache is invalidated, together with all objects dependent on it. The next time the ACL is used, a new copy of it is brought into the cache. Oracle recommends that you share ACLs among resources as much as possible.

There is a session-specific cache of privileges granted to a given user by a given ACL. The entries in this cache have a time out (in seconds) specified by the element <acl-max-age> in the Oracle XML DB configuration file (/xdbconfig.xml). For maximum performance, set this timeout as large as possible. But note that there is a trade-off here: the greater the timeout, the longer it will take for current sessions to pick up an updated ACL.

Oracle XML DB also maintains caches to improve performance when using ACLs that have LDAP principals (LDAP groups or users). The goal of these caches is to minimize network communication with the LDAP server. One is a shared cache that maps LDAP GUIDs to the corresponding LDAP nicknames and Distinguished Names (DNs). This is used when an ACL document is being displayed (or converted to CLOB or VARCHAR2 values from an XMLType instance). To purge this cache, use procedure DBMS_XDBZ.purgeLDAPCache. The other cache is session-specific and maps LDAP groups to their members (nested membership). Note that whenever Oracle XML DB encounters an LDAP group for the first time (in a session) it will get the nested membership of that group from the LDAP server. Hence it is best to use groups with as few members and levels of nesting as possible.

Repository Resources and Database Table Security

Resources in Oracle XML DB Repository are of two types:

Since the content of a REF-based resource can be stored in a table, it is possible to access this data directly using SQL queries on the table. A uniform access control mechanism is one where the privileges needed for access are independent of the method of access (for example, FTP, HTTP, or SQL). To provide a uniform security mechanism using ACLs, the underlying table must first be hierarchy-enabled, before resources that reference the rows in the table are inserted into Oracle XML DB.

The default tables produced by XML schema registration are hierarchy-enabled; that is, enabling hierarchy is the default behavior when you register an XML schema with Oracle XML DB. You can also enable hierarchy after registration, using procedure DBMS_XDBZ.enable_hierarchy.

Enabling hierarchy on a resource table does the following:

See Also:

In any given table, it is possible that only some of the objects are mapped to Oracle XML DB resources. Only those objects that are mapped undergo ACL checking, but all of the objects have table-level security.

Note:

You cannot hide data in XMLType tables from other users if out-of-line storage of is used. Out-of-line data is not protected by ACL security.

Integrating Oracle XML DB with LDAP

This section deals with allowing LDAP users to use the features of Oracle XML DB, including ACLs. The typical scenario is a single, shared database schema (user), to which multiple LDAP users are mapped. This mapping is maintained in the Oracle Internet Directory. End users can log in to the database using their LDAP username and password; they are then automatically mapped to the corresponding shared database schema. (Users can log in using SQL or any of the supported Oracle XML DB protocols.) The implicit ACL resolution is based on the current LDAP user and the corresponding LDAP group membership information.

Before you can use LDAP users and groups as principals in Oracle XML DB ACLs, the following prerequisites must be satisfied:

See Also:

Example 27-21 ACL Referencing an LDAP User

This is an example of an ACL for an LDAP user. Element <principal> contains the full distinguished name of the LDAP user – in this case, cn=user1,ou=Americas,o=oracle,l=redwoodshores,st=CA,c=US.

<acl description="/public/txmlacl1/acl1.xml"
     xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="DAV:"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd 
                         http://xmlns.oracle.com/xdb/acl.xsd">
  <ace principalFormat="DistinguishedName"> 
    <grant>true</grant>
    <principal>cn=user1,ou=Americas,o=oracle,l=redwoodshores,st=CA,c=US
    </principal>
    <privilege>
      <dav:all/>
    </privilege>
  </ace> 
</acl>

See Also:

Oracle Internet Directory Administrator's Guide for the format of an LDAP user distinguished name

Example 27-22 ACL Referencing an LDAP Group

This is an example of an ACL for an LDAP group. Element <principal> contains the full distinguished name of the LDAP group.

<acl xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="DAV:"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd 
                         http://xmlns.oracle.com/xdb/acl.xsd">
  <ace principalFormat="DistinguishedName"> 
    <grant>true</grant>
    <principal>cn=grp1,ou=Americas,o=oracle,l=redwoodshores,st=CA,c=US</principal>
    <privilege>
      <dav:read/>
    </privilege>
  </ace> 
</acl>

See Also:

Oracle Internet Directory Administrator's Guide for the format of an LDAP group distinguished name


Footnote Legend

Footnote 1: DAV: is the namespace itself, not a prefix. Hence, the complete QName of the security class is DAV::dav. A prefix commonly used for namespace DAV: is dav, but this is only conventional; dav is not a predefined prefix for Oracle XML DB.