PermissionService

Name Permission
Version
Included Services  
Java Package org.kuali.rice.kim.api.permission

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

Operations
Main Message Structures

Method createPermission
Description This will create a {@link org.kuali.rice.kim.api.permission.Permission} exactly like the permission passed in.
Parameters Permission permission the permission to create
Return Permission the newly created object. will never be null.
Errors RiceIllegalArgumentException if the permission is null
RiceIllegalStateException if the permission is already existing in the system

Back to Operations

Method updatePermission
Description This will update a {@link Permission}.
Parameters Permission permission the permission to update
Return Permission the updated object. will never be null
Errors RiceIllegalArgumentException if the permission is null
RiceIllegalStateException if the permission does not exist in the system

Back to Operations

Method hasPermission
Description Checks in a given principal id has a permission using the passed in permission information.
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.
Parameters String principalId the principal id to check. cannot be null or blank.
String namespaceCode the namespace code. cannot be null or blank.
String permissionName the permission name. cannot be null or blank.
Return boolean true is principal has permission
Errors RiceIllegalArgumentException if the principalId, namespaceCode, permissionName is null or blank

Back to Operations

Method isAuthorized
Description 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 {@link #hasPermission(String, String, String)}.

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.
Parameters String principalId the principal id to check. cannot be null or blank.
String namespaceCode the namespace code. cannot be null or blank.
String permissionName the permission name. cannot be null or blank.
Map qualification the qualifications to test against.
Return boolean true is principal has permission
Errors RiceIllegalArgumentException if the principalId, namespaceCode, permissionName is null or blank

Back to Operations

Method hasPermissionByTemplate
Description 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.
Parameters String principalId the principal id to check. cannot be null or blank.
String namespaceCode the namespace code. cannot be null or blank.
String permissionTemplateName the permission name. cannot be null or blank.
Map permissionDetails the permission details
Return boolean true is principal has permission
Errors RiceIllegalArgumentException if the principalId, namespaceCode, permissionName is null or blank

Back to Operations

Method isAuthorizedByTemplate
Description 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 {@link #hasPermission(String, String, String)}.

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.
Parameters String principalId the principal id to check. cannot be null or blank.
String namespaceCode the namespace code. cannot be null or blank.
String permissionTemplateName the permission name. cannot be null or blank.
Map permissionDetails the permission details
Map qualification the permission qualifications
Return boolean true is principal has permission
Errors RiceIllegalArgumentException if the principalId, namespaceCode, permissionName is null or blank

Back to Operations

Method getPermissionAssignees
Description 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.
Parameters String namespaceCode the namespace code. cannot be null or blank.
String permissionName the permission name. cannot be null or blank.
Map qualification the permission qualifications
Return AssigneeList list of assignees that have been assigned the permissions
Errors RiceIllegalArgumentException if the principalId, namespaceCode, permissionName is null or blank

Back to Operations

Method getPermissionAssigneesByTemplate
Description 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.
Parameters String namespaceCode the namespace code. cannot be null or blank.
String permissionTemplateName the permission name. cannot be null or blank.
Map permissionDetails the permission details.
Map qualification the permission qualifications
Return AssigneeList list of assignees that have been assigned the permissions by template
Errors RiceIllegalArgumentException if the principalId, namespaceCode, permissionName is null or blank

Back to Operations

Method isPermissionDefined
Description Returns true if the given permission is defined on any Roles.
Parameters String namespaceCode the namespace code. cannot be null or blank.
String permissionName the permission name. cannot be null or blank.
Return boolean true if given permission is defined on any Roles
Errors RiceIllegalArgumentException if the namespaceCode or permissionName is null or blank

Back to Operations

Method isPermissionDefinedByTemplate
Description Returns true if the given permission template is defined on any Roles.
Parameters String namespaceCode the namespace code. cannot be null or blank.
String permissionTemplateName the permission name. cannot be null or blank.
Map permissionDetails the permission template details
Return boolean true if given permission template is defined on any Roles
Errors RiceIllegalArgumentException if the namespaceCode or permissionName is null or blank

Back to Operations

Method getAuthorizedPermissions
Description 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.

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.
Parameters String principalId the principal Id. cannot be null or blank.
String namespaceCode the namespace code. cannot be null or blank.
String permissionName the permission name. cannot be null or blank.
Map qualification the permission qualifications
Return PermissionList list of permissions that are authorized with the given parameters
Errors RiceIllegalArgumentException if the principalId, namespaceCode or permissionName is null or blank

Back to Operations

Method getAuthorizedPermissionsByTemplate
Description 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.
Parameters String principalId the principal Id. cannot be null or blank.
String namespaceCode the namespace code. cannot be null or blank.
String permissionTemplateName the permission name. cannot be null or blank.
Map permissionDetails the permission template details.
Map qualification the permission qualifications
Return PermissionList list of permissions that are authorized with the given parameters
Errors RiceIllegalArgumentException if the principalId, namespaceCode or permissionTemplateName is null or blank

Back to Operations

Method getPermission
Description Gets a {@link org.kuali.rice.kim.api.permission.Permission} from an id.


This method will return null if the permission does not exist.
Parameters String id the unique id to retrieve the permission by. cannot be null or blank.
Return Permission a {@link org.kuali.rice.kim.api.permission.Permission} or null
Errors NONE No Errors

Back to Operations

Method findPermByNamespaceCodeAndName
Description Gets a {@link org.kuali.rice.kim.api.permission.Permission} with the unique combination of namespace and name.


This method will return null if the permission does not exist.
Parameters String namespaceCode namespace code for permission. cannot be null or blank.
String name name of permission. cannot be null or blank.
Return Permission a {@link org.kuali.rice.kim.api.permission.Permission} or null
Errors RiceIllegalArgumentException if the namespaceCode or name is null or blank

Back to Operations

Method findPermissionsByTemplate
Description Return the permissions for the given unique combination of namespace,
component and permission template name.
Parameters String namespaceCode namespace code for permission. cannot be null or blank.
String templateName name of permission template. cannot be null or blank.
Return PermissionList a list of {@link org.kuali.rice.kim.api.permission.Permission} or null
Errors RiceIllegalArgumentException if the namespaceCode or name is null or blank

Back to Operations

Method getPermissionTemplate
Description Gets a {@link Template} from an id.


This method will return null if the template does not exist.
Parameters String id the unique id to retrieve the template by. cannot be null or blank.
Return Template a {@link Template} or null
Errors RiceIllegalArgumentException if the id is null or blank

Back to Operations

Method findPermTemplateByNamespaceCodeAndName
Description Finds a {@link Template} for namespaceCode and name.
Parameters String namespaceCode the namespace code. cannot be null or blank.
String name the template name. cannot be null or blank.
Return Template a {@link Template} or null
Errors RiceIllegalArgumentException if the id or namespaceCode is null or blank

Back to Operations

Method getAllTemplates
Description Finds a {@link Template} for namespaceCode and name.
Parameters None None No Parameters
Return TemplateList a list of {@link Template} or an empty list if none found
Errors NONE No Errors

Back to Operations

Method getRoleIdsForPermission
Description Get the role IDs for the given permission.
Parameters String namespaceCode the permission namespace code. cannot be null or blank.
String permissionName the permission name. cannot be null or blank.
Return StringList a list of role Ids, or an empty list if none found
Errors RiceIllegalArgumentException if the namespaceCode or permissionName is null or blank

Back to Operations

Method findPermissions
Description This method find Permissions based on a query criteria. The criteria cannot be null.
Parameters QueryByCriteria queryByCriteria the criteria. Cannot be null.
Return PermissionQueryResults query results. will never return null.
Errors RiceIllegalArgumentException if the queryByCriteria is null

Back to Operations

Method findPermissionTemplates
Description This method find Permission Templates based on a query criteria. The criteria cannot be null.
Parameters QueryByCriteria queryByCriteria the criteria. Cannot be null.
Return TemplateQueryResults query results. will never return null.
Errors RiceIllegalArgumentException if the queryByCriteria is null

Back to Operations