Security policies

A security policy serves as a collection of security templates, each of which contains a predefined list of permissions, or Access Control Entries (ACEs), that can be configured to apply to a document, custom object, or folder.

Except where specifically mentioned, this topic describes the association of security policies with documents and document classes. To fully understand this topic, you should be familiar with document versioning and the versioning states Released, In Process, Reservation, and Superseded.

REMINDER Security policies are just one way to apply ACEs to an object's ACL. The other sources are the object's class, a security parent, direct edits to the object's security, and by programmatically setting the object's access rights.

About security policies

Security policies allow system administrators to apply access control to large numbers of documents without directly editing the ACL on each document.

Security policies, in conjunction with versioning states, allow a system administrator to configure the system to automatically modify ACLs on documents when their versioning state changes. For example, the administrator can configure the system to automatically grant access to a document to a wide audience when it is released.

Sequence tables detail the versioning states through which documents proceed following check in, check out, and other versioning actions.

To create a security policy, you run one of the security policy wizards provided by Enterprise Manager and by Workplace and Workplace XT. The wizard creates a security policy that the system administrator can then customize by adding security templates. Once created, the security policy can be associated with documents, folders or custom objects. Alternatively, the administrator can make the security policy the default value for the security policy property for one or more classes. Making a specific security policy the default for a class ensures that all instances of the class are associated with that security policy unless the value is explicitly overridden.

The security policy class can have subclasses, just like the other classes in Enterprise Manager's "Other Classes" node. The security policy wizard lets you create a security policy using a subclass, whereas Enterprise Manager's wizard supports only the base class. You could also use one of the supported P8 APIs to create a security policy using a subclass.

About templates

There are two kinds of security templates:

A security template applies to a document version if (1) the document version has an associated security policy, and (2) the associated security policy has a template for the document's version state. For example, if the document goes into the Released versioning state, and the security policy has a Released template, then the permissions listed in the Released template apply.

Templates cannot be shared between security policies and cannot be independently loaded or saved apart from their security policy. Permissions on an object that originate from a security policy will appear on the object's ACL with a Source type of "Template." As such they cannot be directly edited using Enterprise Manager's Access Control Editor or by using the P8 API.

Newly created security templates contain no default permissions placed on them by the Content Engine. Administrators can add permissions at creation time while running the security policy wizard, or at any later time. Applying a template that contains no permissions to an object will have the effect of removing any existing permissions on that object that were previously applied by a security policy.

Assigning security policies

Security policies can become associated with documents in two ways:

By assigning it as the default security policy for a document class. In this case, the default security policy is automatically associated with the object instance at the time of creation unless the default is explicitly overridden. The default security policy will continue to be associated with all versions in the document's version series, unless you do something to change the association. By having the same security policy for all documents in a class, you have a simple, easily understandable and manageable security scheme. If, on the other hand, you change a single document version's class, the new class's default security policy (provided there is one) would be immediately applied to that document version and the old security policy (if there was one) would be removed. However, changing a version's class does not override a security policy that was directly assigned to that version by a user, nor does it change any earlier versions of the same document.

By assigning it to a specific document version. Each document version in a version series could, theoretically, have a different security policy assigned to it. The document class's default security policy will be placed on each instance of the class, but you can override the default with a different security policy. You would do this manually, using Enterprise Manager to open the document version's property sheet and changing the security policy. This would be cumbersome and difficult to manage from a system administrator's point of view, and should be done only as an exception to the normal application by the document class.

Preserve Direct ACEs

In addition to the list of security templates associated with it, each security policy has an important property called Preserve Direct ACEs (also called Preserve Direct Permissions). This property, which can be set to either True or False, governs whether or not direct permissions are preserved in the target object's ACL when a security template is applied to it. The value of this property applies to all the templates contained by the security policy.

By default, this property is set to True, because this is likely to be the most common use case. In fact, the security policy wizard does not ask you to set a value and just sets it to True. After you have created the security policy, you can open its property sheet's General tab to view or change the Preserve Direct ACEs setting.

Effects of changes

Documents get their security policy from the default security policy of their class, if the class has one. Therefore, if you change a document's class to a class that has a different default security policy, the document will immediately take on that new security policy. This also means that if you change a document's class to one that has a security policy that is not the class' default (that is, the new class has a security policy associated with it that was not its original default policy), the document will not take on that new policy but will keep its association with the former security policy.

These scenarios describe the security behavior of changing a document's class, and assume that the security policies in question have appropriate templates.

If you change a document version's class, and both the new class and the old class have different default security policies, the permissions applied by the old security policy are immediately removed and the permissions of the new security policy are immediately applied to the version. The permissions already applied by the old document class' Default Instance ACL are not changed. In other words, the new document class does not apply its Default Instance permissions to the document.

If you change a document version's class, and the version has a policy that does not match the previous class, the software assumes that the version has a security policy that was applied by a user and leaves it as is.

If you change a document's class, and the old class has a security policy and the new class does not, the permissions applied by the old security policy are immediately removed. Since the new class has no security policy, the permissions on the document would come from the other usual sources: from being directly applied, from the Default Instance ACL of the new document class, and from a security parent, if there is one.

Rules of association

Here are the rules of association for security policies:

Changes to an existing security policy do not propagate to existing documents until the version state changes or the next version is created. If, however, you change the document's current policy to some other security policy by directly changing the document version's property sheet, then these changes are immediately applied to the version and the permissions applied by the former security policy are immediately removed.

Support in Workplace and Workplace XT

Workplace and Workplace XT fully support the effects that security policies have on document security. Advanced users of these applications with authorship permissions can run the application's security policy wizard and create security policies. The user can then assign the security policy to individual documents wherever the security page is presented (providing the user has Modify Permissions access) and on multiple documents at one time using the My Search page results list.

Because the applications do not permit editing classes, you must use Enterprise Manager to assign a security policy as the default for a document class. As explained above, the usual way to use a security policy is to assign it as the default of a document class, and then let the class apply the policy to new instances. This ensures that all documents in that class will be associated with a single security policy.

Importing and exporting security policies

Security policies can be exported and imported between object stores.

Custom objects and folders use application security templates only

The custom object class and the folder class can also be assigned a default security policy that will be associated with instances of those classes, just like they are for documents. There is an important difference: custom objects and folders can only receive permissions from application security templates, since versioning security templates can only be applied to documents. The relationship between a custom object or folder and an application security template is done using a GUID assigned to the template. The GUID is called by the application whenever the program's logic requires the security state described by the template. Associations can only be made by customized applications created using a P8 API.

Enterprise Manager's security policy wizard lets you create application security templates as part of defining a security policy. It can also automatically assign a GUID to the new template or use a 32-bit GUID that your own program generates.