
	User Management Guide

CHAPTER 3 ACL-Based Authorization

This chapter discusses ACL-based authorization, including how it is used in Director software and how it can be used in Web applications. It also provides examples of how to use the Director Security API. This chapter includes the following sections:

For more information For a brief overview of ACL-based authorization, see ACL-based authorization.

About ACL-based authorization

In Director, ACL-based authorization protects subsystem administrative functions and application resource objects that persist across multiple deployments, such as documents, folders, group pages, user pages, and profiles.

The following terms are used in this guide to define Director's ACL-based authorization:

Term	Definition
ACL	Access Control List. A list of entries that restricts access to a specific element or element type. Each ACL entry associates a principal with a set of permissions. If no ACL is associated with an element or with the element type to which it belongs, access is unrestricted.
Element	A uniquely identified resource object that is managed by an ACL subsystem and is associated with an element type.
Element type	A string used to define a group of objects with similar behavior (framework elements such as EbiFolder, EbiDocument, and so on).
Principal	An authenticated user or group.
Permission	A type of access to an element, such as READ or WRITE.
ACL subsystem	A logical unit of security administration. This term can be confusing and is defined in ACLs in the Security subsystem.

How ACLs are implemented

ACLs as provided in the Director Security subsystem are an implementation of the standard Java 1.1 Security interface (java.security.acl.Acl). A quote from the specification is shown below with information regarding negative permissions removed:

An ACL can be thought of as a data structure with multiple ACL entries. Each ACL entry, of interface type AclEntry, contains a set of permissions associated with a particular principal. (A principal represents an entity such as an individual user or a group).

The ACL Entries in each ACL observe the following rules:

If there is no entry for a particular principal, then the principal is considered to have a null (empty) permission set.

Individual permissions always override permissions of the group(s) to which the individual belongs.

In Director, ACLs are stored in a database table.

When a principal tries to access an element, the security manager looks in the ACL associated with the element (or element type) and compares the principal for the session context with the list of authorized principals for the necessary permission.

If there is no ACL entry for a particular permission, the permission is open to all authenticated users. However, if there is at least one ACL entry for a particular permission, the security manager looks for an entry for the principal. If there is no such entry, the security manager denies access to the resource.

ACLs in the Director software

This section discusses how ACLs are used in the Director software.

For more information For information about using ACL-based security in other subsystems, including custom subsystems, see ACLs in your Director applications.

ACLs in the Security subsystem

The Security subsystem uses ACLs to define administrative access to the Security service and to each other ACL subsystem. The PAC provides the means to interactively control ACL subsystem administrators.

The Director architecture defines a subsystem as a set of services and APIs that provide some subset of application functionality. However, in the context of ACL-based authorization, the term subsystem has a different meaning. It refers to a method of partitioning ACL-based authorization so that individual subsets of the application resources can be protected separately from the others.

NOTE: To avoid confusion, this chapter refers to subsystems in the context of ACL-based authorization as ACL subsystems.

Some of the default ACL subsystems correspond to Director services, and some do not:

Corresponding	Not corresponding
ContentMgmtService	General
PortalService	Locksmith
SearchService	PortalGroupPages
SecurityService	User-defined
UserService	—

ACL subsystem administrators

Director includes a set of built-in groups that define administrative access to each ACL subsystem. Here is a general description of access rights for each subsystem administrator group:

Admin type	Permission	Authorizes users to
ContentAdmin	READ	Get subsystem elements (folders, categories and documents) in the Content Management subsystem
	WRITE	Add subsystem elements to the Content Management subsystem
	PROTECT	Set ACLs for the ContentAdmin type
GeneralAdmin	PROTECT	A generic Admin type that can be applied to any Director subsystem. (Reserved for custom subsystem implementation)
LocksmithElementType	PROTECT	The Locksmith user has complete access to all Director application and ACL subsystem objects, regardless of specified access to the individual objects. After the locksmith user is authenticated, the Director security subsystem adds the user to the admin ACL for each ACL subsystem. The Locksmith can then add individual users to each subsystem ACL.
PortalAdmin	PROTECT	Access the PAC and portal-related functions. NOTE: This permission by itself does not include access to the User, Directory, and Security functions in the PAC
SearchAdmin	READ	Get existing searchable repositories
	WRITE	Add, remove, clear, reinitialize, and reset searchable repositories
	PROTECT	Set ACLs for the SearchAdmin type
SecurityAdmin	PROTECT	Set ACLs for any Admin type except Locksmith
UserAdmin	CREATE	Add users, groups, and group profiles
	READ	View information about profile users
	DELETE	Remove profile users
	UPDATE	Update profile user records
	PROTECT	Set ACLs for the UserAdmin type

To manage administrative groups interactively

The PAC allows you to manage the users in each administrative group by permission.

Intro pac

For more information, see Using the Security Section of the PAC.

To manage administrative groups programmatically

See the PAC source code in:

  samples\src\com\sssw\portal\pac

under the Director installation directory.

ACLs in the Content Management subsystem

A classic example of how ACLs can be used in Web applications is the Director Content Management subsystem, which uses ACL-based authorization to manage access to directory entries (folders, categories, and documents). The Content Management subsystem interacts with the Security Manager through its own hasAccess method call.

The Content Management subsystem defines five permissions: LIST, PROTECT, READ, WRITE, and PUBLISH but can be modified to use custom ACLs. For example, by subclassing the default Content Manager, you can modify it to call to the Security API, checking for custom permissions such as a CREATE permission that permits or denies the addition of documents to a folder.

The Content Management subsystem allows you to manage its own ACLs through the Portal Management Console (PMC), its Web-based interface. This screen shows ACL-based authorization in the PMC:

Intro ACL

For more information, see the chapter on security for the Content Management subsystem" in the Content Management Guide.

ACLs in the Portal subsystem

The PAC provides the means to interactively control group page element ACLs.

For more information See the section on ACLs for group pages in the Portal Guide.

ACLs in your Director applications

You can define your own ACLs in your Director application, to protect your own persisted elements. This section discusses some of the concepts.

For more information For a classic example of how ACLs can be used in Web applications, see ACLs in the Content Management subsystem.

For more information For examples of how to implement your own ACLs, see Using the Security API.

Elements

An element is a uniquely identified resource artifact that is managed by a Director subsystem. Elements persist across the lifetime of the application server — in other words, they are not affected by redeploying the Director EAR. For example, documents and folders in the Content Management subsystem are elements.

Director applications can set and get permissions for securable elements.

Element types

An element type is a string used to define a group of objects with similar behavior (framework elements such as EbiFolder, EbiDocument, and so on.) You can apply ACLs to element types as well as to individual elements

Element types are defined as constants in subinterfaces of EbiFrameworkElement. For example, a document in the Content Management subsystem is defined in com.sssw.cm.api.EbiDocument.EL_DOCUMENT. You can use similar constants to define element types for custom subsystems.

The Security subsystem provides a set of built-in element types for each ACL subsystem. Each element type has a set of access rights, which is the list of permissions supported by the element type.

Built-in permissions

Director includes a set of built-in permissions: CREATE, DELETE, EXECUTE, LIST, PROTECT, PUBLISH, READ, SELECT, UPDATE, and WRITE.

Built-in permissions are hardcoded and cannot be modified using the Security API.

NOTE: Negative permissions are not supported in Director

Each ACL subsystem uses a subset of these built-in permissions. Each permission can have a different meaning in each subsystem.

Custom permissions

Director allows you to define your own custom permissions using the Security API. See EbiPermissionMeta in Javadoc.

Custom permissions are stored as XML files in the application database. Do not edit the XML files yourself. Use the Security API.

Custom permissions provide a way to use ACL-based authorization on any level of granularity in your application. For example, you can create a set of custom permissions, each of which permits access to a specific method of a component.

Access right meta

An access right meta object is an API object used to define metadata for associating permissions with a specific element type (or admin type).

Using the Security API

This section shows some techniques for using Director's Security API.

Getting Security API delegates

This example shows how to get the delegate objects used in the other Security API examples.

For more information For background information on delegates, see the section on accessing subsystem services in the Core Development Guide.

  import com.sssw.fw.security.api.*;
  
  //
  // Getting delegate objects from a factory must be done within a
  // try block.
  //
  try {
      //
      // Get a metadata delegate.
      //
      EbiSecurityMetaDelegate smd = 
      com.sssw.fw.security.client.EboFactory.getSecurityMetaDelegate();
      //
      // Get an ACL delegate.
      //
      EbiSecurityAclDelegate ad =
      com.sssw.fw.security.client.EboFactory.getSecurityAclDelegate();
      }
      //
      // Use the delegate objects.
      //
  } 
  catch (EboFactoryException e) {
      sb.append( e.getMessage() );
  }

Getting an element type and identifier

This example shows how to get an element type and UUID. It is used in the other examples.

  //
  // Get delegates. See "Getting Security API delegates."
  //
  // Get the element type metadata from the EbiSecurityMetaDelegate.
  //
  EbiElementTypeMeta typeMeta = smd.getElementTypeMeta(context);
  //
  // This example uses the PortalAdmin element.
  //
  String portalSubSystem = EbiSecurityConstants.SUBSYSTEM_PORTAL_SERVICE;
  String adminType = typeMeta.getAdminType(portalSubSystem);
  String adminID = typeMeta.getAdminID(portalSubSystem);

NOTE: Element type names are defined as constants in subinterfaces of EbiFrameworkElement. For example, a document in the Content Management subsystem is defined in com.sssw.cm.api.EbiDocument.EL_DOCUMENT.

Listing the permissions associated with an element

This example shows how to get a list of the permissions that can be granted to an element.

  //
  // Get delegates. See "Getting Security API delegates."
  //
  // Get the element type. See "Getting an element type and id."
  //
  // Get the EbiAccessRightMeta object for the element type.
  //
  EbiAccessRightMeta meta = smd.getAccessRightMeta(context, adminType);
  //
  // Retrieve the list of permissions.
  //
  String[] rights = meta.getPermissionNames();
  for (int i = 0; i < rights.length; i++) {
      sb.append( rights[i] );

ListAccessRights

Listing the principals with permission for an element

This example shows how to get a list of principals that have a specific permission for an element. It gets a list of principals assigned to the PROTECT permission for the PortalAdmin element.

  import java.security.*;
  
  //
  // Get delegates. See "Getting Security API delegates."
  //
  // Get the element type. See "Getting an element type and id."
  //
  // Get the principals for a specific permission type.
  //
  Principal [] prins = null;
  prins = ad.getPrincipalsFromAcl(context, adminID, adminType,
      EbiPermission.PROTECT);
  for (int i = 0; i < prins.length; i++) {
      sb.append( prins[i].toString() );

ListPrincipalsAcl

For more information For other elements, use the appropriate element type field, as described in Using the Security API.

Getting the content of an ACL

This code shows how to get the string representation of an ACL:

  import java.security.*;
  
  //
  // Get delegates. See "Getting Security API delegates."
  //
  // Get the element type. See "Getting an element type and id."
  //
  // Get the contents of the ACL in the form of a string
  //
  Acl adacl = ad.getAcl(context, adminID, adminType);
  String adaclcontent = adacl.toString();
  sb.append( adaclcontent );

GetAclString

Assigning a principal to an ACL

This code shows how to add a principal to an ACL for an Admin element:

  import com.sssw.fw.directory.api.*;
  import java.security.*;
  
  //
  // Get delegates. See "Getting Security API delegates."
  //
  // Get the element type. See "Getting an element type and id."
  //
  // Get a Directory delegate.
  //
  EbiDirectoryDelegate dd =
     com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  //
  // Get a principal. Must be a valid realm user.
  //
  Principal user = dd.getUser(context,"SomeUser");
  //
  // Add the principal to the ACL
  //
  Principal [] prins = new Principal[1];
  prins[0] = user;
  ad.addPrincipalsToAcl(context, adminID, adminType, EbiPermission.PROTECT,
     prins);
  sb.append( "Added " + user.toString() + " PROTECT");

NOTE: This example requires your code to handle the following exceptions in addition to EboFactoryException:

  catch (EboSecurityException e) {
      sb.append( e.getMessage() );
  }
  catch (EboException e) {
      sb.append( e.getMessage() );
  }

AddPrincipalAcl

Runtime ACL validation

When a principal attempts to access an element, the Director security manager looks for a corresponding ACL entry. If none is found, access is unrestricted.

More specifically, for all elements the security manager first checks the Security subsystem ACL for a Locksmith or corresponding admin type entry. After that, validation algorithm varies according to the element or element type.

Item	Validation
Admin elements	No further validation. These require a Locksmith or corresponding Admin type entry.
PAC, PMC, and Portal objects	Each of these has its own authenticator logic.
Profiles and personalization objects	Validation checks the ID of the authenticated user. For example, a user page can be accessed by the Locksmith, a User Admin, or the owner of the page.
All other elements	All other elements cause a check for an element or element type ACL entry. For example, documents managed by the Content Management service that have no element type ACL are open to everyone.

Customizing ACL-based authorization

Customizing the Security service

There are three ways to approach the task:

Write a class that extends the EboSecurityManager class to override the runtime ACL validation logic. For example, you could modify the locksmith ACL metadata to allow additional permissions such as PROTECT, READ, and WRITE.

Completely reimplement EbiSecurityManager. Then change services.xml in:

  XWB/DirectorTemplate/Director/library/SecurityService/SecurityService-conf

The service definition looks like this:

  <service>
    <interface>com.sssw.fw.security.api.EbiSecurityManager
    </interface>
    <impl-class>com.sssw.fw.security.core.EboSecurityManager
    </impl-class>
    <description>Security manager that provides authentication 
                 and permission validation
    </description>
    <max-instances>1</max-instances>
    <startup>M</startup>
  </service>

Replace EboSecurityManager with the name of your own class.

Add a subsystem to provide a different security API, as described below.

Adding ACL-based security to a new subsystem

Adding a new subsystem might be necessary when you are trying to integrate Director with a third party security service.

NOTE: This topic goes beyond the scope of this guide. The procedure is only outlined in this section. For detailed information, contact Novell Technical Support.

Add metadata information for the subsystem into the existing Subsystem/ElementType metadata.
```
  com.sssw.fw.security.api.EbiElementTypeMeta, singleton
```
Call Security Meta Delegate to modify the metadata persistently.
```
  com.sssw.fw.security.api.EbiSecurityMetaDelegate
```
Create a new Access Right Meta for the administrator type and for any element type that is defined in the Subsystem/ElementType metadata.
```
  com.sssw.fw.security.api.EbiAccessRightMeta
```
Call Security Meta Delegate to store the metadata object(s) persistently.
Write Custom UI to allow setting ACLs based on the newly created Subsystem's AdminType and ElementTypes by calling the Security ACL delegate.
```
  com.sssw.fw.security.api.EbiSecurityAclDelegate
```
Add run-time ACL validation logic in your new subsystem by calling the Security delegate.
```
  com.sssw.fw.security.api.EbiSecurityDelegate
```
Check administrator access.
```
  userHasAccessRight(context, right, adminID, adminType)
```
(Notice that Locksmith is checked internally.)

Check element level access (if any)

  userHasAccessRight(context, right, elementUUID, elementType)


	User Management Guide