com.sap.security.api.acl
Interface IAclManager

All Superinterfaces:

IConfigurable

public interface IAclManager

extends IConfigurable

ACL Manager Interface

Definition of an Access Control List Manager

The ACL Manager administers the Access Control Lists (ACL).

This interface defines methods which are necessary to administer ACL's and check if a principal has access to an object with a certain permission.

Permissions:

- An permission exists of an object type and an permission name separated by by a point '.' (i.e. "default_type.read" ).

Note: A point is not allowed in the object type, but in the permission name!

- Optional: You can use global permissions (permissions without object type)

- Permissions must be unique within the namespace of the ACL Manager you are using. This means if you use an application specific ACL Manager, the permissions have to be unique within your application. If you use the default ACL Manager, the permission have to be globally unique.

Object Id's:

-They also have to be unique within the namespace of the ACL Manager you are using (see above). Therefore they should have a prefix with the service name and/or the object type.

The following code exsample shows some typical functions:

 // Get default ACL Manager
 IAclMAnager manager = UMFactory.getAclManager();
 // Get specific ACL Manager
 IAclMAnager manager = UMFactory.getAclManager("Workflow");
 
 //Create some Permissions
 manager.addPermission("WorkflowPermission.read", null);
 manager.addPermission("WorkflowPermission.write", null);
 //Create a Permission Container
 List members = new ArrayList(2);
 members.add("WorkflowPermission.read");
 members.add("WorkflowPermission.write");
 manager.addPermission("WorkflowPermission.full_control", members);
 
 //Create an ACL on an objectID
 IUser userA;
 IAcl acl = manager.createAcl(userA, "WorkflowItemABC");
 //Get this ACL again
 IAcl acls = manager.getAcls("WorkflowItemABC");
 //Delete an ACL
 manager.removeAcl(userA, "WorkflowItemABC");
 //Delete all info's abaout a principal (concerning ACL info)
 manager.deletePrincipal(usersA);
 
 //Create an ACE (Access Control Entry) for user B (user A is ACL Owner)
 IAclEntry aclEntry = acl.createAclEntry(userA, userB, "WorkflowPermission.read", false);
 //Get all ACE's for a special principal
 acl.getAclEntries(userB);
 //Get all ACE's		    
 acl.getAclEntries();
 
 //check a permission on IAclManager
 manager.isAllowed("WorkflowItemABC", usersA, "WorkflowPermission.read");
 //check a permission on IAcl
 acl.isAllowed(usersA, "WorkflowPermission.read");
 //check a permission on IAclEntry
 acl.isAllowed("WorkflowPermission.read");
 
 //Delete an ACL Entry
 acl.removeAclEntry(usersA, aclEntries);
 //Reset the hole ACL (only deletion of ACE's)
 acl.resetAcl(usersA);
 

Version:

1.0

Field Summary

static int	MAX_OBJECT_ID_LENGTH Max.
static int	MAX_PERMISSION_NAME_LENGTH Max.
static java.lang.String	OWNER_PERMISSION Permission that an owner of an ACL gets automatically

Method Summary

boolean	addPermission(java.lang.String permission, java.util.List members) Adds a permission to the list of available permissions.
boolean	addPermissionMember(java.lang.String permission, java.lang.String member) Adds a member (permission) to an existing permission.
IAcl	createAcl(IPrincipal caller, java.lang.String objectId) This method creates a new ACL object for an object id.
void	deletePrincipal(IPrincipal principal) Deprecated. please use deletePrincipal(String principalID)
void	deletePrincipal(java.lang.String principalID) This method deletes all data (owner, ACE) concerning a principal
IAcl	getAcl(java.lang.String objectId) This method reads the existing ACL object for a portal object.
IAcl[]	getAcls(java.lang.String[] objectIds) This method reads the existing ACL object for an array of object Ids.
java.util.List	getAllAcls() This method returns a List of all available ACL ids (String objects)
java.util.List	getAllPermissions() Gets a list of all available permissions
int	getMaxObjectIdLength() This method returns the maximum length of the object id.
int	getMaxPermissionNameLength() This method returns the maximum length of the permission name.
java.util.List	getPermissionMembers(java.lang.String permission) Returns the permission members from the given permission.
java.util.List	getPermissions(java.lang.String objectType) Gets a list of permissions which are available for the specific object type
PermissionStatus	getPermissionStatus(java.lang.String objectId, IPrincipal principal, java.lang.String permission) This method returns the PermissionStatus for an action, a portal object and a user (principal).
boolean	hasPermission(java.lang.String objectId, IPrincipal principal, java.lang.String permission) This method checks if a principal is authorized for a permission on an object, but doesn't write an entry in the security audit log.
boolean	isAllowed(java.lang.String[] objectIds, IPrincipal principal, java.lang.String permission) This method checks if a principal is authorized for a number of permissions on an object.
boolean	isAllowed(java.lang.String objectId, IPrincipal principal, java.lang.String permission) This method checks if a principal is authorized for a permission on an object.
boolean	removeAcl(IPrincipal caller, IAcl acl) This method removes the existing ACL object for a given acl.
boolean	removeAcl(IPrincipal caller, java.lang.String objectId) This method removes the existing ACL object for a given object Id.
boolean	removeAcls(IPrincipal caller, java.lang.String[] objectIds) This method removes the existing ACL object for a number of given object Ids.
boolean	removePermission(java.lang.String permission) Removes a permission from the list of available permissions.
boolean	removePermissionMember(java.lang.String permission, java.lang.String member) Removes a permission member from the given permission.
java.util.List	searchAcls(java.lang.String principalID) This method returns a List of ACL object ids (String objects), which fit the search criteria

Methods inherited from interface com.sap.security.api.IConfigurable

initialize

Field Detail

MAX_OBJECT_ID_LENGTH

public static final int MAX_OBJECT_ID_LENGTH

Max. length of object ID (incl. an optional service name / object type)

MAX_PERMISSION_NAME_LENGTH

public static final int MAX_PERMISSION_NAME_LENGTH

Max. length of permission name

OWNER_PERMISSION

public static final java.lang.String OWNER_PERMISSION

Permission that an owner of an ACL gets automatically

Method Detail

getMaxObjectIdLength

public int getMaxObjectIdLength()

This method returns the maximum length of the object id.

Returns:

the maximum length of object id.

getMaxPermissionNameLength

public int getMaxPermissionNameLength()

This method returns the maximum length of the permission name.

Returns:

the maximum length of permission name.

createAcl

public IAcl createAcl(IPrincipal caller,
                      java.lang.String objectId)
               throws UMException

This method creates a new ACL object for an object id.

Parameters:

caller - an IPrincial which will be registered as owner.

objectId - a string which defines the object.

Returns:

the new ACL object.

Throws:

UMException - if the ACL cannot be created.

getAcl

public IAcl getAcl(java.lang.String objectId)
            throws UMException

This method reads the existing ACL object for a portal object.

Parameters:

objectId - a string which defines the object.

Returns:

the ACL object or null if no object exists.

Throws:

UMException - if the data cannot be read.

getAcls

public IAcl[] getAcls(java.lang.String[] objectIds)
               throws UMException

This method reads the existing ACL object for an array of object Ids.

Parameters:

objectIds - a string array which defines the objects.

Returns:

an array of the ACL objects or null if no object exists.

Throws:

UMException - if the data cannot be read.

removeAcl

public boolean removeAcl(IPrincipal caller,
                         java.lang.String objectId)
                  throws UMException

This method removes the existing ACL object for a given object Id.

Parameters:

caller - a IPrincipal who has to be an owner of the acl.

objectId - a string which defines the corresponding acl to remove.

Returns:

true when the ACL object extsts and if it has been removed successfully; false otherwise

Throws:

UMException - if the data cannot be removed.

removeAcl

public boolean removeAcl(IPrincipal caller,
                         IAcl acl)
                  throws UMException

This method removes the existing ACL object for a given acl.

Parameters:

caller - a IPrincipal who has to be an owner of the acl.

acl - a acl which has to be removed.

Returns:

true when the ACL object was removed successfully; false otherwise.

Throws:

UMException - if the data cannot be removed.

removeAcls

public boolean removeAcls(IPrincipal caller,
                          java.lang.String[] objectIds)
                   throws UMException

This method removes the existing ACL object for a number of given object Ids.

Parameters:

caller - a IPrincipal who has to be an owner of the acls.

objectIds - a string array which defines corresponding acls to remove.

Returns:

true when the ACL objects were removed successfully; false otherwise

Throws:

UMException - if the data cannot be removed.

isAllowed

public boolean isAllowed(java.lang.String objectId,
                         IPrincipal principal,
                         java.lang.String permission)
                  throws UMException

This method checks if a principal is authorized for a permission on an object.

Parameters:

objectId - a string which defines the object.

principal - user, group or role name.

permission - checked action (permission).

Returns:

true when the principal is authorized for the object and permission; false otherwise

Throws:

UMException - if the data cannot be read.

isAllowed

public boolean isAllowed(java.lang.String[] objectIds,
                         IPrincipal principal,
                         java.lang.String permission)
                  throws UMException

This method checks if a principal is authorized for a number of permissions on an object.

Parameters:

objectIds - a string array which defines the objects.

principal - user, group or role name.

permission - checked action (permission).

Returns:

true when the principal is authorized for the object and permissions; false otherwise

Throws:

UMException - if the data cannot be read.

hasPermission

public boolean hasPermission(java.lang.String objectId,
                             IPrincipal principal,
                             java.lang.String permission)
                      throws UMException

This method checks if a principal is authorized for a permission on an object, but doesn't write an entry in the security audit log.

Parameters:

objectId - a string which defines the object.

principal - user, group or role

permission - checked action (permission).

Returns:

true when the principal is authorized for the object and permission; false otherwise

Throws:

UMException - if the data cannot be read.

addPermission

public boolean addPermission(java.lang.String permission,
                             java.util.List members)
                      throws UMException

Adds a permission to the list of available permissions.

Parameters:

permission - the permission to add (see class description)

members - a list of permissions the added permission contains or null if it contains no other permissions

Returns:

true when the permission could be added successfully; false otherwise

Throws:

UMException -

addPermissionMember

public boolean addPermissionMember(java.lang.String permission,
                                   java.lang.String member)
                            throws UMException

Adds a member (permission) to an existing permission.

Parameters:

permission - the permission for which the member should be added

member - a permission that should be a member of the given permission

Returns:

true when the member could be added successfully; false otherwise

Throws:

UMException -

removePermission

public boolean removePermission(java.lang.String permission)
                         throws UMException

Removes a permission from the list of available permissions.

Parameters:

permission - the permission to remove (see class description)

Returns:

true when the permission could be removed successfully; false otherwise

Throws:

UMException -

removePermissionMember

public boolean removePermissionMember(java.lang.String permission,
                                      java.lang.String member)
                               throws UMException

Removes a permission member from the given permission.

Parameters:

permission - the parent permission

member - the permission to remove

Returns:

true when the permission could be removed successfully; false otherwise (when member was not a member of the given permission)

Throws:

UMException -

getPermissionMembers

public java.util.List getPermissionMembers(java.lang.String permission)
                                    throws UMException

Returns the permission members from the given permission.

Parameters:

permission - the parent permission

Returns:

List the member permissions

Throws:

UMException -

getPermissions

public java.util.List getPermissions(java.lang.String objectType)
                              throws UMException

Gets a list of permissions which are available for the specific object type

Parameters:

objectType - the object type

If it's an empty string, all global permissions are delivered.

Returns:

the list of permissions

Throws:

UMException -

getAllPermissions

public java.util.List getAllPermissions()
                                 throws UMException

Gets a list of all available permissions

Returns:

the permissions

Throws:

UMException -

getPermissionStatus

public PermissionStatus getPermissionStatus(java.lang.String objectId,
                                            IPrincipal principal,
                                            java.lang.String permission)
                                     throws UMException

This method returns the PermissionStatus for an action, a portal object and a user (principal).

Parameters:

objectId - a string which define the object.

principal - user, group or role name.

permission - checked action (permission).

Returns:

an object that represents the status, whether the action is allowed, denied or undefined

Throws:

UMException - if the data cannot be read.

deletePrincipal

public void deletePrincipal(IPrincipal principal)
                     throws UMException

Deprecated. please use deletePrincipal(String principalID)

This method deletes all data (owner, ACE) concerning a principal

Parameters:

principal - principal, whose related data should be deleted.

Throws:

UMException - if the data cannot be removed.

deletePrincipal

public void deletePrincipal(java.lang.String principalID)
                     throws UMException

This method deletes all data (owner, ACE) concerning a principal

Parameters:

principalID - uniqueID of principal, whose related data should be deleted.

Throws:

UMException - if the data cannot be removed.

getAllAcls

public java.util.List getAllAcls()
                          throws UMException

This method returns a List of all available ACL ids (String objects)

Returns:

List of ACL ids (String objects)

Throws:

UMException - if the data cannot be read.

searchAcls

public java.util.List searchAcls(java.lang.String principalID)
                          throws UMException

This method returns a List of ACL object ids (String objects), which fit the search criteria

Parameters:

objectId - String of object id, for which a search should be performed. The wildcard character "*" is permitted. If a wildcard is set at begin or end of the object id, a like search will be performed. If no wildcard is set, a search for this exact id will be performed only.

Returns:

List of ACL ids (String objects)

Throws:

UMException - if the data cannot be read.