Documentum Access Control Lists

Introduction

Access Control Lists (ACLs) are Documentum’s method of restricting access to important documents. ACLs control Documentum’s security layer, one of the most flexible and powerful security schemes around.

Major Benefits

Some of the major benefits of Documentum ACLs are:

• You can assign seven different levels of access to your documents
• You can assign access to individual users or to groups of users
• Users can create their own private ACLs that only they can use
• System Admins can create System-Wide ACLs that can be used by everyone
• Extended Permissions let you really tweak what a user can do to an object

Every sysobject in a docbase has an ACL assigned to it. The ACL contains information about which users and groups have access to the document, and what level of access each has. When a user attempts to access an object, the Documentum Server looks in the ACL to determine which groups have access. It then looks in these groups to determine if the user is in any of the groups. It determines the user’s access level by awarding the user the highest level of access taking into account all the groups that the user is a member of.

Note: Even if you explicitly assign NONE access to a user, if they are also in a group that has READ access, the user will have READ access to the object.

What are the Attributes of the ACL object?

An ACL object has four important attributes:

• object_name: The name of the ACL. This must be unique for all ALCs with the same owner_name.
• owner_name: The owner of the ACL. System ACLs are owned by the docbase owner, while User ACLs are owned by normal docbase users.
• r_accessor_name: A repeating attribute that lists all of the users and groups that have access.
• r_accessor_permit: A repeating attribute that lists the level of access for each user and group defined in the accessor_name attribute.
• r_accessor_xpermit: A repeating attribute that specifies the extended permissions for each user and group defined in the accessor_name attribute. Extended permissions are only available in Documentum 4i and later servers.

How do Documentum ACLs Differ from NT’s ACLs?

There are two main differences between an ACL in Documentum and an ACL in Windows NT. The first is that they are much more powerful - NT lets you assign fewer levels of access. The second difference is that NT uses a one-to-one relationship between files and ACLs, while Documentum uses a one-to-many relationship. In NT, if you change the permissions on a file and want other files to have the same changes, you must either change each file individually or tell NT to apply the permission to all the files in the subdirectory. In Documentum, an ACL can be shared by many documents. Instead of changing the permissions on a file, you change the ACL; all of the files that are using that ACL will be instantly updated. This is a very flexible approach.

What are the Different Levels of Access that are Available?

• NONE (1): A user with NONE access will never know that the document exists. They won’t see it in a folder, and if they query for it, it will not be returned in the result list. This is one of the most unique and powerful features of Documentum’s security sub-system.
• BROWSE (2): A user with BROWSE access will be able to see the attributes of a document, but can not view the content. The user will see the document within the folder in which it lives, and the user can query for it.
• READ (3): A user with READ access can view the attributes and content of a document, but can not annotate it, version it or edit it.
• RELATE (4): A user with RELATE access can view the attributes and content and can annotate the content.
• VERSION (5): A user with VERSION access can read, annotate, and create new versions of a document, but can not overwrite the current version of the document. If a user with VERSION access wants to modify the attributes of a document, he must check it out, modify the attributes, then check it in.
• WRITE (6): A user with WRITE access can read, annotate, version, and overwrite the current document, but can not delete it. A user with WRITE access can modify the attributes of a document without checking it out.
• DELETE (7): A user with DELETE permission can do all these things, plus delete the document. DELETE permission is the highest level of permission that a user can have on a document.

How are dm_owner and dm_world used?

There are two special aliases that Documentum uses within its ACLs. They are dm_owner and dm_world. These aliases are used to make ACLs more flexible and easier to administer.

• dm_owner: This is an alias for the current owner of the document. Use this special user to give the owner of the document special access. For example, you may create an ACL for the Marketing department, and you want the owner of the document to be able to delete it, but other members of the Marketing department to only have version access. To accomplish this, set up the ACL so that one of the r_accessor_names is “dm_owner” and the corresponding r_accessor_permit is “7″. This way, whenever anyone in the Marketing department uses this ACL if they are the owner, they will have delete permission. Without this shortcut, you would have to create a separate ACL for each member of the Marketing department (one where Bob has Delete, one where Jane has delete, etc.).
• dm_world: This is an alias for all of the users in a docbase. If you want to give everyone READ access to the corporate policies document in your docbase, set up the ACL so that one of the r_accessor_names is “dm_world” and the corresponding r_accessor_permit is “3″. If you want to hide a document from the general user-base, set up the ACL so that one of the r_accessor_names is “dm_world” and the corresponding r_accessor_permit is “0″.

What are the Extended Permissions?

Extended permissions are a feature only available in version 4i and later. They greatly enhance the security capabilities of the server by letting certain users access admin functions on a per-document basis. For example, in pre-4i docbases, only two types of users could change the permissions on a document: the owner of that document and a superuser. In 4i, you can use the extended permissions to allow certain normal users to change the permissions. For example, an ACL for the Marketing department might allow the marketing_managers group to change the permissions on the document.

The extended permissions are described below:

• execute_proc: Allows the user to execute the procedure (if it is a procedure)
• change_location: Allows the user to change the location of the document
• change_state: Allows the user to change the state of the document using the document lifecycle
• change_permit: Allows the user to change the object’s permissions
• change_owner: Allows the user to change the owner of the object

What is a System ACL vs. a User ACL?

A System ACL is an ACL that is created by a system administrator and is available for all users to use. The only thing that makes it a “system” ACL is that the owner of the ACL is the same as the docbase owner. Most ACLs in a docbase should be System ACLs.

A User ACL is an ACL that is owned by a user in the docbase. It can only be used by that user. Bob can not create a document and set its permissions to one of Fred’s User ACLs. Bob can only use his own User ACLs or a System ACL.

How do I Create an ACL?

The easiest way to create an ACL is to manually create it using the ACL Editor in Workspace or the Desktop Client. These dialogs are designed with end-users in mind, so they default to User ACL as the type of ACL you are creating. If you are a System Administrator creating a System ACL, be sure to change the ACL Type picklist to “System”.

If you are creating ACLs that you want to roll out in several docbases, it’s best to create them using a query or script, or to use the Documentum Developer Studio so that you can create them once and deploy them many times.

Using the API Create an ACL

You create an ACL just like you create any other object, using the create, set, and save APIs. However, since the r_accessor_name and r_accessor_permit attributes are read_only, you can not set them directly. You must use the grant and revoke APIs. Below is the syntax for creating an example System ACL called World Write that lets all users have write access to the document, the owner have delete access, and members of a group named “system_admins” have delete access. Note that we are using the alias “dm_dbo” to represent the docbase owner.

                create,c,dm_acl
set,c,l,object_name	World Write
set,c,l,owner_name dm_dbo
set,c,l,description All Users have Write Access
grant,c,l,dm_world,6 
grant,c,l,dm_owner,7
grant,c,l,system_admins,7
save,c,l
            

Using a Docbasic Procedure to Create an ACL

Personally, I always use installation scripts to create the fundamental components of a docbase, including ACLs. To simplify this process, I have written a utility function in docbasic that will create a System ACL. It takes as its arguments the name of the ACL and a two column array of accessor names and accessor permits. It creates the ACL and returns a success code. I have made this utility procedure available with an example of how it is used. You can download it below.

Figure 2: Create ACL Docbasic Code

How do I Tell a Document Which ACL to Use?

The easiest way to set a document’s ACL is to use the Permissions dialog in Workspace or the Desktop Client. Simply choose the ACL that you wish to use from the list given. If you want to use a System ACL, be sure to select the type of ACL as “System” from the ACL Owner pick list.

Sometimes, you will need to set a document’s ACL programmatically or from an update query. To do this, you only need to set two attributes of the document, acl_name and acl_domain. The acl_name attribute is the name of the ACL you wish to use, and the acl_domain is the owner of the ACL you wish to use. You have to specify the acl_domain because different users might have created User ACLs with the same name.

Note: If you are using a System ACL, set the acl_domain to dm_dbo, Documentum’s internal alias for the current docbase owner.

How does a Document Get its Default ACL?

When you create or import a new document, if you don’t explicitly assign an ACL to it, Documentum will assign an ACL by default. But how does the server know which ACL to assign? Actually, you can configure the server to choose the default ACL based on one of three methods.

• By User: Every document created by a lawyer gets the legal ACL, regardless of what type of document it is or where it’s located. Every user has a default ACL defined in the dm_user object. You can see this by going to the Users dialog in Workspace. If you configure the docbase to assign default ACLs by user, the ACL that is assigned to a new document will be determined by the ACL that is defined in your dm_user object. The default Documentum installation will assign default ACLs based on the user’s default ACL.
• By Object Type: Every contract gets the legal ACL regardless of who created it or where it is located. If you configure Documentum to assign default ACLs based on object type, then whenever an object is created, it will get the ACL that is assigned to the object type that you are creating. If no ACL has been assigned to the object type, the server will traverse up the object hierarchy until it finds an object type that does have an associated ACL.
• By Folder: Every document created in a folder gets that folder’s ACL regardless of the type of document or who created it. This is probably the most meaningful way to assign default ACLs. Whatever ACL is assigned to the folder that the document is created in, this is the ACL that will be assigned to the document.

To configure the server to use one of these methods, set the default_acl attribute of the dm_server_config object. Use 1 to assign default ACLs based on Folder, 2 to assign based on Object Type, and 3 to assign based on User.

What is an Internal ACL?

An internal ACL is an ACL created on-the-fly by the server, rather than being created explicitly by a user or system administrator. An internal ACL is easy to spot because of its name; Internal ACLs are named dm_<object_id> (dm_4500225180000108).

Internal ACLs are created by the server when necessary and cleaned up by the server when they are no longer needed. They are created when you use the grant and revoke APIs to modify the permissions of a document directly.

Using the grant and revoke APIs Directly on an Object

Sometimes, you might want to modify the permissions of a document but don’t want to go through the hassle of creating a new ACL. You can do this by granting and revoking access to the document itself. The grant API lets you give a user or group access to a document. The Documentum server will create an internal ACL as a copy of the existing ACL but with the new r_accessor_name added. Here’s the syntax:

                grant,session_id,object_id,accessor_name,accessor_permit
            

The revoke API lets you set a user or group’s permission to NONE. Its syntax is:

                revoke,session_id,object_id,accessor_name
            

What is Folder Security?

Folder security is an extra level of security that can be turned on or off at the docbase level. It allows you to prevent someone from creating a document into a folder if they don’t have the write level of access to that folder. If folder security is turned on (which it is by default), the user must have WRITE access to a folder in order to create a document within that folder. The user must have VERSION access to the folder in order for them to link an object into that folder. To put it another way, to create an object’s primary link, you must have WRITE permission on the folder. To create a secondary link, you must have VERSION permission on the folder.

To turn folder security on or off, modify the folder_security attribute of the dm_docbase_config object.

ACL Tips and Tricks

Determining a User’s Access Level to a Document

Sometimes you need to check to see if a user has a certain access level to a document. For example, you might want to ensure that a user has delete a\cess to a document before you let them delete it, otherwise they might get an ugly error message from the server.

There is a special computed attribute, _permit, on every sysobject that can tell you what your permission level is for that document. This attribute is computed for you anytime you fetch a document, and the value is different for different users (obviously). The value can be anywhere from 1 to 7, corresponding to the NONE to DELETE levels of access. Unfortunately, since the object must be fetched in order for _permit to be computed, you can not query the docbase for this attribute.

Using the use_acl API

Sometimes you need to re-assign a document’s default ACL. You might have changed the ACL and now want to change it back, or you may have moved the document and want to change the ACL to match the folder in which it now lives. Documentum has an API called use_acl that will let you do this simply and easily. You won’t have to jump through the hoops of determining the user’s default ACL or the folder’s ACL. The server will do this for you.