User Management Guide

CHAPTER 4

Using ACL-Based Authorization

This chapter describes how to use ACLs (access control lists) in exteNd Director. It has these sections:

• About the Security subsystem

• ACLs in exteNd Director

• ACL subsystem administrators

• Accessing ACLs for users and groups

• Accessing ACLs for containers

• Customizing ACL-based authorization

About the Security subsystem

The purpose of the Security subsystem is authorization, the process of restricting access to application resources. The Security subsystem is built on top of the standard J2EE security API.

The Security subsystem depends on the Directory subsystem for authentication—in other words, the Security subsystem assumes that requests for protected application resources can only be made by authenticated users.

Authorization is performed by verifying that a user or group (represented by a principal) has sufficient permission to perform the operation requested. Principals can be defined using Access Control Lists (ACLs) or mapped to resources using security roles.

    For information about role-based security, see Using Security Roles.

ACLs in exteNd Director

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

The following terms define exteNd Director's support for ACL-based authorization:

Accessing principals

In exteNd Director, a principal is implemented as a class that extends the Java 2 standard interface java.security.Principal. A principal can be used to represent any entity, such as an individual, a corporation, and a login ID.

There are three types of principals defined in exteNd Director:

• user—Individual users

• group—Groups of users

• container—Organizational units within an LDAP-based directory service such as eDirectory. This principal allows you to set ACLs on user containers for security inheritance. See Accessing ACLs for containers.

Principals are represented in the Directory API as interfaces in the com.sssw.fw.directory.api package:

  public interface EbiRealmUser extends Principal
  public interface EbiRealmGroup extends Group
  public interface EbiRealmContainer extends Principal

You can instantiate the principal interface directly in your code, or use one of the following API methods:

  EboDirectoryHelper.getEbiRealmUser()

  EbiRealmGroup.getUserMembers()

  EbiRealmGroup.getGroup()

  EbiRealmGroup.getChildGroups()

  EbiContainer.getParentContainer()

  EbiContainer.getDescendants()

How ACL processing works

Whenever a user attempts to access an element, the Security subsystem checks whether the user has the permission to perform the specified action. If an element has an ACL, exteNd Director checks whether the user has been granted the specified permission.

Situations   These situations can occur:

Process   The Security subsystem determines in three steps whether the user has permission to access an element:

1. Does the element have an ACL?

   • No—Allow access

   • Yes—Go to Step 2

2. Does the user have permission in the element's ACL?

   • Yes—Allow access

   • No—Go to Step 3

3. Is the user a Locksmith user or a subsystem administrator with the appropriate permission for this subsystem element?

   • Yes—Allow access

   • No—Deny access; throw EboSecurityException

ACL subsystem administrators

exteNd Director includes a set of built-in groups that define administrative access to each subsystem using ACLs. You can add and remove users for each permission using the Director Administration Console (see Using the Security Section of the DAC).

Here is a general description of access rights for each subsystem administrator group:

Restricting access to administrators using the API

You can restrict access to portal and content management elements using the EbiSecurityManager.setRestrictedAccess() method. For example, if you restrict access to a document 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:

Accessing ACLs for users and groups

This section shows some techniques for using exteNd Director's Directory and Security APIs. The main points of access for ACL security objects are the following delegate interfaces:

    For background information on delegates, see the section on accessing subsystem services in Developing exteNd Director Applications.

Accessing ACLs using the DAC   You can also use the Director Administration Console (DAC) to access ACLs.

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

Getting Security API delegates

This example shows how to get the delegate objects used in the other Security API examples that follow:

  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 identifier.
  // 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] );

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 identifier.
  // 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() );

Listing the elements with permissions for a principal

Use this method (available from the EbiSecurityManager) to enumerate all the accessible resources (elements) of a certain type that are accessible to the principal in the session context:

  /**
     * Returns a Collection of elements accessible to the userwhose context is passed in. 
     * @param context context
     * @param elType framework element type, tells the method which    * element type to determine accessibility for 
     * @param rights a list of access right permissions to be    * checked, e.g. EbiPermission.READ, EbiPermission.WRITE,
     * EbiPermission.EXECUTE, etc.; note that if multiple    * rights are specified, the method will treat the list 
     * as a Boolean OR and will attempt to find elements that    * have either READ or WRITE or EXECUTE etc. for the user 
     * @return a Collection of accessible framework elements of the    * specified type; the Collection is empty if no accessible 
     * elements of the type are found
     */
  
  public Collection getAccessibleElements(EbiContext context, String elType, String[] rights)
  throws EboUnrecoverableSystemException

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 identifier.
  // 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 );

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 identifier.
  // 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() );
  }	 	 

Accessing ACLs for containers

The principal type container represents an organizational unit within an LDAP tree. The container principal allows you to set ACLs on an LDAP directory container (or similar tree directory structure) and have the ACLs apply to all users in the specified tree hierarchy. This capability is known as security inheritance. In exteNd Director, security inheritance is available in applications that are configured for a hierarchical LDAP realm—such as Novell eDirectory.

The Directory API allows:

• Traversal of the LDAP hierarchy from the root all the way down to leaf nodes

• Direct navigation to a specific node within the hierarchy

The following interfaces are provided in the com.sssw.fw.directory.api package:

  public interface EbiTreeRealm
  public interface EbiRealmContainerDelegate

NOTE:   You cannot add containers to an LDAP realm from exteNd Director. Use your native LDAP tools for this purpose.

Assigning a container principal to an ACL

This code is based on the preceding example (Assigning a principal to an ACL). It shows how to add a container 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 identifier.
  // Get a new Container delegate.
  EbiRealmContainerDelegate rcd = new EbiRealmContainerDelegate();
  
  // Get Container principal. Must be a valid realm container.
  Principal container = 
     rcd.getEbiRealmContainer(context,"cn=sample,o=users");
  // Add the principal to the ACL.
  Principal [] prins = new Principal[1];
  prins[0] = container;
  ad.addPrincipalsToAcl(context, adminID, adminType, 
        EbiPermission.PROTECT,
     prins);

NOTE:   The container principal object is accessible in the API and in the section of the Director Administration Console (DAC) that controls shared and group pages in the Portal. However, you cannot use the DAC to assign administrative access nor Content Management element access to a container principal.

Customizing ACL-based authorization

Customizing the Security service

There are three ways to customize ACL security:

• 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 next.

Adding ACL-based security to a new subsystem

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

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

• Add metadata information for the subsystem into the existing subsystem element type 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 element type metadata.

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

    com.sssw.fw.security.api.EbiAccessRightMeta
  

• Call security meta delegate to store the metadata object(s) persistently.

• Write a custom UI to allow setting ACLs based on the newly created subsystem's admin type and element types by calling the security ACL delegate:

    com.sssw.fw.security.api.EbiSecurityAclDelegate
  

• Add runtime 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)
  

  (Note that Locksmith is checked internally.)

• Check element level access (if any):

    userHasAccessRight(context, right, elementUUID, elementType)
  

Custom permissions

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

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 in your application code.

Custom permissions are stored as XML files in the application database. Do not edit the XML files directly—use the Security API.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...