org.kuali.rice.kim.api.permission
Interface PermissionService

public interface PermissionService

This service provides operations for evaluating permissions and querying for permission data.

A permission is the ability to perform an action. All permissions have a permission template. Both permissions and permission templates are uniquely identified by a namespace code plus a name. The permission template defines the course-grained permission and specifies what additional permission details need to be collected on permissions that use that template. For example, a permission template might have a name of "Initiate Document" which requires a permission detail specifying the document type that can be initiated. A permission created from the "Initiate Document" template would define the name of the specific Document Type that can be initiated as a permission detail.

The isAuthorized and isAuthorizedByTemplateName operations on this service are used to execute authorization checks for a principal against a permission. Permissions are always assigned to roles (never directly to a principal or group). A particular principal will be authorized for a given permission if the permission evaluates to true (according to the permission evaluation logic and based on any supplied permission details) and that principal is assigned to a role which has been granted the permission.

The actual logic for how permission evaluation logic is defined and executed is dependent upon the permission service implementation. However, it will typically be associated with the permission template used on the permission.

This service provides read-only operations. For write operations, see PermissionUpdateService.

Author:

Kuali Rice Team (rice.collab@kuali.org)

See Also:

PermissionUpdateService

Method Summary

List<PermissionTemplate>	getAllTemplates() Return all Permission Templates.
List<Permission>	getAuthorizedPermissions(String principalId, String namespaceCode, String permissionName, AttributeSet permissionDetails, AttributeSet qualification) Returns permissions (with their details) that are granted to the principal given the passed qualification.
List<Permission>	getAuthorizedPermissionsByTemplateName(String principalId, String namespaceCode, String permissionTemplateName, AttributeSet permissionDetails, AttributeSet qualification) Returns permissions (with their details) that are granted to the principal given the passed qualification.
Permission	getPermission(String permissionId) Get the permission object with the given ID.
List<PermissionAssigneeInfo>	getPermissionAssignees(String namespaceCode, String permissionName, AttributeSet permissionDetails, AttributeSet qualification) Get the list of principals/groups who have a given permission.
List<PermissionAssigneeInfo>	getPermissionAssigneesForTemplateName(String namespaceCode, String permissionTemplateName, AttributeSet permissionDetails, AttributeSet qualification) Get the list of principals/groups who have a given permission that match the given permission template and permission details.
String	getPermissionDetailLabel(String permissionId, String kimTypeId, String attributeName) Returns the label of the permission detail for the given permissionId, kimType and attributeName.
List<Permission>	getPermissionsByName(String namespaceCode, String permissionName) Return the permission object for the given unique combination of namespace, component and permission name.
List<Permission>	getPermissionsByNameIncludingInactive(String namespaceCode, String permissionName) Return the permission object for the given unique combination of namespace, component and permission name.
List<Permission>	getPermissionsByTemplateName(String namespaceCode, String permissionTemplateName) Return the permission object for the given unique combination of namespace, component and permission template name.
PermissionTemplate	getPermissionTemplate(String permissionTemplateId) Return the Permission Template given the Template ID.
PermissionTemplate	getPermissionTemplateByName(String namespaceCode, String permissionTemplateName) Return the Permission Template given the Template Name and Namespace Code.
List<String>	getRoleIdsForPermission(String namespaceCode, String permissionName, AttributeSet permissionDetails) Get the role IDs for the given permission.
List<String>	getRoleIdsForPermissionId(String permissionId) Get the role IDs for the given permission.
List<String>	getRoleIdsForPermissions(List<KimPermissionInfo> permissions) Get the role IDs for the given list of permissions.
boolean	hasPermission(String principalId, String namespaceCode, String permissionName, AttributeSet permissionDetails) Checks whether the principal has been granted a permission matching the given details without taking role qualifiers into account.
boolean	hasPermissionByTemplateName(String principalId, String namespaceCode, String permissionTemplateName, AttributeSet permissionDetails) Checks whether the principal has been granted a permission matching the given details without taking role qualifiers into account.
boolean	isAuthorized(String principalId, String namespaceCode, String permissionName, AttributeSet permissionDetails, AttributeSet qualification) Checks whether the given qualified permission is granted to the principal given the passed roleQualification.
boolean	isAuthorizedByTemplateName(String principalId, String namespaceCode, String permissionTemplateName, AttributeSet permissionDetails, AttributeSet qualification) Checks whether the given qualified permission is granted to the principal given the passed roleQualification.
boolean	isPermissionDefined(String namespaceCode, String permissionName, AttributeSet permissionDetails) Returns true if the given permission is defined on any Roles.
boolean	isPermissionDefinedForTemplateName(String namespaceCode, String permissionTemplateName, AttributeSet permissionDetails) Returns true if the given permission template is defined on any Roles.
List<Permission>	lookupPermissions(Map<String,String> searchCriteria, boolean unbounded) Search for permissions using arbitrary search criteria.

Method Detail

hasPermission

boolean hasPermission(String principalId,
                      String namespaceCode,
                      String permissionName,
                      AttributeSet permissionDetails)

Checks whether the principal has been granted a permission matching the given details without taking role qualifiers into account. This method should not be used for true authorization checks since a principal may only have this permission within a given context. It could be used to identify that the user would have some permissions within a certain area. Later checks would identify exactly what permissions were granted. It can also be used when the client application KNOWS that this is a role which is never qualified.

isAuthorized

boolean isAuthorized(String principalId,
                     String namespaceCode,
                     String permissionName,
                     AttributeSet permissionDetails,
                     AttributeSet qualification)

Checks whether the given qualified permission is granted to the principal given the passed roleQualification. If no roleQualification is passed (null or empty) then this method behaves the same as hasPermission(String, String, String, AttributeSet). Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined. Each permission is checked against the permissionDetails. The PermissionTypeService is called for each permission with the given permissionName to see if the permissionDetails matches its details.

hasPermissionByTemplateName

boolean hasPermissionByTemplateName(String principalId,
                                    String namespaceCode,
                                    String permissionTemplateName,
                                    AttributeSet permissionDetails)

Checks whether the principal has been granted a permission matching the given details without taking role qualifiers into account. This method should not be used for true authorization checks since a principal may only have this permission within a given context. It could be used to identify that the user would have some permissions within a certain area. Later checks would identify exactly what permissions were granted. It can also be used when the client application KNOWS that this is a role which is never qualified.

isAuthorizedByTemplateName

boolean isAuthorizedByTemplateName(String principalId,
                                   String namespaceCode,
                                   String permissionTemplateName,
                                   AttributeSet permissionDetails,
                                   AttributeSet qualification)

Checks whether the given qualified permission is granted to the principal given the passed roleQualification. If no roleQualification is passed (null or empty) then this method behaves the same as hasPermission(String, String, String, AttributeSet). Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined. Each permission is checked against the permissionDetails. The PermissionTypeService is called for each permission with the given permissionName to see if the permissionDetails matches its details.

getPermissionAssignees

List<PermissionAssigneeInfo> getPermissionAssignees(String namespaceCode,
                                                    String permissionName,
                                                    AttributeSet permissionDetails,
                                                    AttributeSet qualification)

Get the list of principals/groups who have a given permission. This also returns delegates for the given principals/groups who also have this permission given the context in the qualification parameter. Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined.

getPermissionAssigneesForTemplateName

List<PermissionAssigneeInfo> getPermissionAssigneesForTemplateName(String namespaceCode,
                                                                   String permissionTemplateName,
                                                                   AttributeSet permissionDetails,
                                                                   AttributeSet qualification)

Get the list of principals/groups who have a given permission that match the given permission template and permission details. This also returns delegates for the given principals/groups who also have this permission given the context in the qualification parameter. Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined.

isPermissionDefined

boolean isPermissionDefined(String namespaceCode,
                            String permissionName,
                            AttributeSet permissionDetails)

Returns true if the given permission is defined on any Roles.

isPermissionDefinedForTemplateName

boolean isPermissionDefinedForTemplateName(String namespaceCode,
                                           String permissionTemplateName,
                                           AttributeSet permissionDetails)

Returns true if the given permission template is defined on any Roles.

getAuthorizedPermissions

List<Permission> getAuthorizedPermissions(String principalId,
                                          String namespaceCode,
                                          String permissionName,
                                          AttributeSet permissionDetails,
                                          AttributeSet qualification)

Returns permissions (with their details) that are granted to the principal given the passed qualification. If no qualification is passed (null or empty) then this method does not check any qualifications on the roles. All permissions with the given name are checked against the permissionDetails. The PermissionTypeService is called for each permission to see if the permissionDetails matches its details. An asterisk (*) as a value in any permissionDetails key-value pair will match any value. This forms a way to provide a wildcard to obtain multiple permissions in one call. After the permissions are determined, the roles that hold those permissions are determined. Each role that matches between the principal and the permission objects is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked through the role's type service.

getAuthorizedPermissionsByTemplateName

List<Permission> getAuthorizedPermissionsByTemplateName(String principalId,
                                                        String namespaceCode,
                                                        String permissionTemplateName,
                                                        AttributeSet permissionDetails,
                                                        AttributeSet qualification)

Returns permissions (with their details) that are granted to the principal given the passed qualification. If no qualification is passed (null or empty) then this method does not check any qualifications on the roles. All permissions with the given name are checked against the permissionDetails. The PermissionTypeService is called for each permission to see if the permissionDetails matches its details. An asterisk (*) as a value in any permissionDetails key-value pair will match any value. This forms a way to provide a wildcard to obtain multiple permissions in one call. After the permissions are determined, the roles that hold those permissions are determined. Each role that matches between the principal and the permission objects is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked through the role's type service.

getPermission

Permission getPermission(String permissionId)

Get the permission object with the given ID.

getPermissionsByTemplateName

List<Permission> getPermissionsByTemplateName(String namespaceCode,
                                              String permissionTemplateName)

Return the permission object for the given unique combination of namespace, component and permission template name.

getPermissionsByName

List<Permission> getPermissionsByName(String namespaceCode,
                                      String permissionName)

Return the permission object for the given unique combination of namespace, component and permission name.

getPermissionTemplate

PermissionTemplate getPermissionTemplate(String permissionTemplateId)

Return the Permission Template given the Template ID.

Parameters:

permissionTemplateId -

Returns:

PermissionTemplate

getPermissionTemplateByName

PermissionTemplate getPermissionTemplateByName(String namespaceCode,
                                               String permissionTemplateName)

Return the Permission Template given the Template Name and Namespace Code.

Parameters:

namespaceCode, - permissionTemplateName

Returns:

PermissionTemplate

getAllTemplates

List<PermissionTemplate> getAllTemplates()

Return all Permission Templates.

Parameters:

namespaceCode, - permissionTemplateName

Returns:

PermissionTemplate

lookupPermissions

List<Permission> lookupPermissions(Map<String,String> searchCriteria,
                                   boolean unbounded)

Search for permissions using arbitrary search criteria. JavaBeans property syntax should be used to reference the properties. If the searchCriteria parameter is null or empty, an empty list will be returned.

getRoleIdsForPermission

List<String> getRoleIdsForPermission(String namespaceCode,
                                     String permissionName,
                                     AttributeSet permissionDetails)

Get the role IDs for the given permission.

getRoleIdsForPermissions

List<String> getRoleIdsForPermissions(List<KimPermissionInfo> permissions)

Get the role IDs for the given list of permissions.

getPermissionDetailLabel

String getPermissionDetailLabel(String permissionId,
                                String kimTypeId,
                                String attributeName)

Returns the label of the permission detail for the given permissionId, kimType and attributeName.

getRoleIdsForPermissionId

List<String> getRoleIdsForPermissionId(String permissionId)

Get the role IDs for the given permission.

getPermissionsByNameIncludingInactive

List<Permission> getPermissionsByNameIncludingInactive(String namespaceCode,
                                                       String permissionName)

Return the permission object for the given unique combination of namespace, component and permission name. Inactive permissions are also returned