Content Management Guide

CHAPTER 4

Securing Content

This chapter describes how to use ACL-based security to authorize access to Content Management (CM) subsystem elements. It has these sections:

NOTE: Most of the security tasks described in this chapter can also be accomplished using the CMS Administration Console.

For more information, see Managing Content Security.

About access control

The CM subsystem supports ACL-based security, as described in ACL-based security. You can specify access restrictions based on user ID or group membership on most objects in the CM subsystem. You can use access restrictions to:

Prevent changes after your infrastructure of document types, folders, and categories has been set up
Prevent inadvertent deletion of objects
Protect documents or other objects from being seen by unauthorized users

CM user groups

A comprehensive security policy must set different permissions for different user roles. Typical roles in the CM subsystem are:

Role	Description
Author	Has read and write access for documents; has read, write, and list access for folders and categories.
Publisher	Has publish access for documents; has list access for folders and categories.
Administrator	Has all access rights to all objects. Users are considered administrators when the ACL assigned to the EbiContentAdmin interface gives them at least one of the permissions. See ContentAdmin group.

When setting up users and groups for exteNd Director, you will want to consider how your users fall into these roles and create appropriate groups. You can use those user IDs and groups to create ACLs that implement your security. You might create a master ACL that you can get and reuse throughout the CM subsystem.

You can set up users and groups using the Director Administration Console (DAC).

For more information, see the chapter on using the Directory section of the DAC in the User Management Guide.

ACL-based security

You specify access restrictions on CM objects by using an access control list (ACL). To provide support for ACLs, exteNd Director implements the java.security.acl.Acl interface. Each of the securable elements has a set of supported access right types, or permissions. The supported permissions are defined as String constants in each object's interface.

This section describes using ACLs to specify access restrictions on CM objects.

For more information For general information about using ACLs in exteNd Director applications, see the chapter on ACL-based security in the User Management Guide

Permissions

The permissions defined for the CM subsystem include:

Permission	Description
PROTECT	Allows the users and groups in the ACL to change permissions on the object.
READ	Allows the users and groups in the ACL to view the object or get the metadata for an object.
WRITE	Allows the users and groups in the ACL to make changes to the object, by updating the object programmatically or by checking in a new version of a document. A user who has been denied WRITE access cannot check out a document.
LIST	Allows the users and groups in the ACL to view a list of the objects that this object contains. This includes the documents and subfolders of a folder, the documents and subcategories of a category, and the documents associated with a document type.
PUBLISH	For documents, allows the users and groups in the ACL to change the published status of the document. They can publish it and remove it from the published area.

Element types and associated permissions

The table that follows lists the subsystem securable element types (not including some securable superinterfaces) and permissions they support:

Object	Access right types
EbiContentAdmin	PROTECT, READ, WRITE
EbiDocType	PROTECT, READ, WRITE, LIST
EbiDocField	PROTECT, READ, WRITE
EbiDocCategory	PROTECT, READ, WRITE, LIST
EbiDocFolder	PROTECT, READ, WRITE, LIST
EbiDocument	PROTECT, READ, WRITE, PUBLISH
EbiDocLayoutStyle	PROTECT, READ, WRITE
EbiLayoutDocDescriptor	PROTECT, READ, WRITE

ContentAdmin group

The EbiContentAdmin interface represents the built-in content administrator group. Users added to this group have specified access to subsystem management and administration. Here are the available permissions:

Permission	Description
PROTECT	Set ACLs for the ContentAdmin type.
READ	Get subsystem elements (folders, categories and documents) in the CM subsystem
WRITE	Add subsystem elements to the CM subsystem

Methods for managing access control

The EbiContentMgmtDelegate interface provides access to most of the security-related methods in the CM subsystem.

Accessing ACLs for existing elements

These methods of EbiContentMgmtDelegate let you set security for objects:

Method	Returns	Description
getAcl()	java.security.acl.-Acl	Gets the ACL for a securable element: category, field, folder, layout style, layout document descriptor, document type, or document.
setAcl()	void	Assigns an ACL to a securable element.
removeAcl()	boolean for success	Removes the ACL currently set for an element.
isAuthorized()	boolean	Checks whether the user identified in the context object is authorized for the specified type of access for an object.
getAllAccessible()	Collection	From a list of securable elements, filters out the ones that are accessible to the user whose context is passed in.
getAdminElement()	EbiContentAdmin	Gets the Content Admin element holding the ACL that identifies the users and groups that have administrator access to content objects. See Accessing ACLs for ContentAdmin.
hasAdminAccess()	boolean	This is a shortcut for isAuthorized() and is invoked with a reference to the Content Admin element.

Specifying ACLs for new elements

For securable elements, you can specify an ACL when you create the object. It is an argument of the object's add method on the EbiContentMgmtDelegate — addDocument(), addFolder(), and so on.

For more information For a code example, see Examples of adding ACLs.

Inheriting ACLs

For the following objects: if you don't specify an ACL when you create them, the settings of their containers are copied to the new object:

New	Copy the ACL of their
Folders	Parent folder
Documents	Folder
Layout descriptors	Layout style

After the object is created, there is no further connection to the container's ACL. Changes to a container's ACL have no effect on the contained objects.

For other object types: if you don't specify an ACL, they have an empty ACL.

Accessing ACLs for ContentAdmin

These methods on EbiContentAdmin allow you to access ACLs for the ContentAdmin group:

Method	Returns	Description
getAcl()	java.security.acl.-Acl	Gets the ACL currently set for the ContentAdmin element.
setAcl()	void	Assigns an ACL to the Content Admin element.
removeAcl()	boolean for success	Removes the ACL currently set for the Content Admin element.
isUserAuthorized()	boolean	Checks if the current user is listed in the Content Admin ACL.

Restricting element access to administrators

You can restrict access for any CM element to Content Admin users using the setRestrictedAccess() method. Specify the permission you want to restrict. For example, if you restrict access to a folder for the WRITE permission, only members of the ContentAdmin group have WRITE access to the element.

NOTE: The restricted access right takes precedence over any other ACL associated with the restricted element.

Here are the related methods on the EbiSecurityManager interface:

Method	Returns	Description
setRestrictedAccess()	boolean for success	Restricts specified access for an element to system administrators
check RestrictedAccess()	boolean	Checks whether an element has restricted access

Examples of adding ACLs

This example presents a method called demonstrateSecurity() that illustrates the following techniques:

Adding READ access to the ContentAdmin element associated with a principal (the identity assigned to a user as a result of authentication)
Adding a folder with an ACL
Adding a folder with no ACL

NOTE: In this case the folder inherits the ACL from its parent.
Adding an ACL to an existing folder

The demonstrateSecurity() method needs to access a content manager (EbiContentMgmtDelegate), the context object (EbiContext), and a principal—all of which are passed in as arguments:

  public void demonstrateSecurity(
          EbiContentMgmtDelegate cmgr, EbiContext context,
          Principal principal)
          throws
              EboUnrecoverableSystemException, EboSecurityException, EboItemExistenceException, EboFactoryException, NotOwnerException
      {
          EboPermission readPerm = EboPermission.getPermission(
              context.getEbiSession(), EboPermission.READ);
          EboPermission writePerm = EboPermission.getPermission(
              context.getEbiSession(), EboPermission.WRITE);
  
          // Add READ access to the Content Admin element to the passed-in principal
          EbiContentAdmin adminElement = cmgr.getAdminElement(context);
          Acl admAcl = cmgr.getAcl(context, adminElement);
          AclEntry aclEntry = com.sssw.fw.factory.EboFactory.getAclEntry();
          aclEntry.setPrincipal(principal);
          aclEntry.addPermission(readPerm);
          admAcl.addEntry(principal, aclEntry);
          cmgr.setAcl(context, adminElement, admAcl);
  
          // Add a folder with an ACL
          Acl acl = com.sssw.fw.factory.EboFactory.getAcl();
          aclEntry = com.sssw.fw.factory.EboFactory.getAclEntry();
          aclEntry.setPrincipal(principal);
          aclEntry.addPermission(readPerm);
          aclEntry.addPermission(writePerm);
          cmgr.addFolder(
              context,
              cmgr.getRootFolder(context),
              "Movie Reviews",
              EbiDocFolder.DIR_TYPE_DEFAULT,
              "Folder for movie reviews",
              acl);
  
          // Add a folder with no ACL -- it will inherit the ACL
          // from its parent folder (if there is an ACL set on the parent)
          EbiDocFolder frFolder = cmgr.addFolder(
              context,
              cmgr.getRootFolder(context),
              "Financial Reports",
              EbiDocFolder.DIR_TYPE_DEFAULT,
              "Folder for financial reports",
              null);
  
          // This code adds an ACL to an existing folder.
          cmgr.setAcl(context, frFolder, acl);
      }

Example of handling a security exception

This example presents a method called demonstrateHandleExceptions() that illustrates how to handle a security exception (and other exceptions as well).

This code publishes version 2 of a document whose ID is assigned to the variable docid. The publishDocumentContentVersion() method will throw an EboSecurityException if the user is not allowed to publish the specified document. This example handles the exception by adding an error message to the context object. The portlet can then include the error message in its generated content so the user knows what went wrong.

The demonstrateHandleExceptions() method needs to access a content manager (EbiContentMgmtDelegate), the context object (EbiContext), and the document of interest—all of which are passed in as arguments.

  public void demonstrateHandleExceptions(
          EbiContentMgmtDelegate cmgr, EbiContext context, String docID)
      {
          try
          {
              cmgr.publishDocumentContentVersion(context, docID, 2, true, true);
          }
          catch (EboSecurityException se)
          {
              se.printStackTrace();
              String msg = "Security violation: " + se.toString();
              context.setValue("error", "User does not have access. " + msg);
          }
          catch (EboUnrecoverableSystemException use)
          {
              use.printStackTrace();
              String msg = "Unrecoverable exception: " + use.toString();
              context.setValue("error", msg);
          }
          catch (EboItemExistenceException iee)
          {
              iee.printStackTrace();
              String msg = "Item existence exception: " + iee.toString();
              context.setValue("error", msg);
          }
      }
  }