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 example 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 about 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);
 

NOTE: deletePrincipal(java.lang.String) is the only method which implicitly triggers cluster-wide cache invalidation. Therefore all changes done via other methods of IAclManager need to be followed by IAcl.commit() on the affected IAcl objects to get the changes also reflected on other cluster nodes.

Field Summary

static int	MAX_OBJECT_ID_LENGTH Max. length of object ID (incl. an optional service name / object type)
static int	MAX_PERMISSION_NAME_LENGTH Max. length of permission name
static String	OWNER_PERMISSION Permission that an owner of an ACL gets automatically

Method Summary

boolean	addPermission(String permission, List members) Adds a permission to the list of available permissions.
boolean	addPermissionMember(String permission, String member) Adds a member (permission) to an existing permission.
IAcl	createAcl(IPrincipal caller, 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(String principalID) This method deletes all data (owner, ACE) concerning a principal
IAcl	getAcl(String objectId) This method reads the existing ACL object for a portal object.
IAcl[]	getAcls(String[] objectIds) This method reads the existing ACL object for an array of object Ids.
List	getAllAcls() This method returns a List of all available ACL ids (String objects)
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.
List	getPermissionMembers(String permission) Returns the permission members from the given permission.
List	getPermissions(String objectType) Gets a list of permissions which are available for the specific object type
PermissionStatus	getPermissionStatus(String objectId, IPrincipal principal, String permission) This method returns the PermissionStatus for an action, a portal object and a user (principal).
boolean	hasPermission(String objectId, IPrincipal principal, 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(String[] objectIds, IPrincipal principal, String permission) This method checks if a principal is authorized for a number of permissions on an object.
boolean	isAllowed(String objectId, IPrincipal principal, String permission) This method checks if a principal is authorized for a permission on an object.
void	logAclInfo(String objectID, String objectName, String comment) This method logs the passed information directly into the security audit log file.
boolean	removeAcl(IPrincipal caller, IAcl acl) This method removes the existing ACL object for a given acl.
boolean	removeAcl(IPrincipal caller, String objectId) This method removes the existing ACL object for a given object Id.
boolean	removeAcls(IPrincipal caller, String[] objectIds) This method removes the existing ACL object for a number of given object Ids.
boolean	removePermission(String permission) Removes a permission from the list of available permissions.
boolean	removePermissionMember(String permission, String member) Removes a permission member from the given permission.
List	searchAcls(String principalID) This method returns a List of ACL object ids (String objects), which fit the search criteria
void	setAclServiceUser(String serviceUserId) This methods sets the service user for the current ACL manager.

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

initialize

Field Detail

MAX_OBJECT_ID_LENGTH

static final int MAX_OBJECT_ID_LENGTH

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

See Also:

Constant Field Values

MAX_PERMISSION_NAME_LENGTH

static final int MAX_PERMISSION_NAME_LENGTH

Max. length of permission name

See Also:

Constant Field Values

OWNER_PERMISSION

static final String OWNER_PERMISSION

Permission that an owner of an ACL gets automatically

See Also:

Constant Field Values

Method Detail

getMaxObjectIdLength

int getMaxObjectIdLength()

This method returns the maximum length of the object id.

Returns:

the maximum length of object id.

getMaxPermissionNameLength

int getMaxPermissionNameLength()

This method returns the maximum length of the permission name.

Returns:

the maximum length of permission name.

setAclServiceUser

void setAclServiceUser(String serviceUserId)
                       throws UMException

This methods sets the service user for the current ACL manager. This service user has all ACL permissions on objects managed by this ACL manager.

Parameters:

serviceUserId - The uniqueID of the service user.

Throws:

UMException - if the ACL service user can't be set.

createAcl

IAcl createAcl(IPrincipal caller,
               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

IAcl getAcl(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

IAcl[] getAcls(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

boolean removeAcl(IPrincipal caller,
                  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

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

boolean removeAcls(IPrincipal caller,
                   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

boolean isAllowed(String objectId,
                  IPrincipal principal,
                  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

boolean isAllowed(String[] objectIds,
                  IPrincipal principal,
                  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

boolean hasPermission(String objectId,
                      IPrincipal principal,
                      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

boolean addPermission(String permission,
                      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

boolean addPermissionMember(String permission,
                            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

boolean removePermission(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

boolean removePermissionMember(String permission,
                               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

List getPermissionMembers(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

List getPermissions(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

List getAllPermissions()
                       throws UMException

Gets a list of all available permissions

Returns:

the permissions

Throws:

UMException

getPermissionStatus

PermissionStatus getPermissionStatus(String objectId,
                                     IPrincipal principal,
                                     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

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

void deletePrincipal(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

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

List searchAcls(String principalID)
                throws UMException

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

Parameters:

principalID - 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.

logAclInfo

void logAclInfo(String objectID,
                String objectName,
                String comment)

This method logs the passed information directly into the security audit log file.

Parameters:

objectID - a string which defines the object.

objectName - complete readable object name

comment - should contain information about the cause of (a group of) following ACL modifications

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGINEAPI	[sap.com] com.sap.security.api.sda
[sap.com] ENGFACADE	[sap.com] tc/je/usermanagement/api
[sap.com] CORE-TOOLS	[sap.com] com.sap.engine.client.lib