Document Authorizer

Rules validate after a user has entered data into a document and performed an event on the document. However, there are some actions that we don't want a user to do in the first place. For instance, let's say that a certain user cannot create a transactional document like the Cash Management document. If we wait until the user submits the document to validate that the user had permission to work on the document in the first place, we are bound to end up with some very frustrated users. What we need for this are not validations, but guards, to prevent the wrong action from taking place in the beginning. Thankfully, we have a class of guards, which are called document authorizers. Here, we explore what document authorizers do and how they prevent wrong events from happening.

Document authorizers extensively use KIM IdentityManagementService to check for permissions and other access level control details. Most commonly used methods are implemented and declared final meaning needs no revision since it is configurable through KIM.

Transactional document authorizers will extend from org.kuali.rice.kns.document.authorization.TransactionalDocumentAuthorizerBase. TransactionalDocumentAuthorizerBase in turn extends org.kuali.rice.kns.document.authorization.DocumentAuthorizerBase, which is the default implementation of org.kuali.rice.kns.document.authorization.DocumentAuthorizer and use/inherit some common behaviors from org.kuali.rice.kns.authorization.BusinessObjectAuthorizerBase. Because of this, some of the base implementations may be in TransactionalDocumentAuthorizerBase and some may be in DocumentAuthorizerBase and some in BusinessObjectAuthorizerBase; we'll cover the major methods in this hierachy, so that we know everything we can take advantage of in our own document authorizers. 

Document Authorizer Hierarchy

Document, may I?

DocumentAuthorizer declares following final methods which are commonly used for authorization, one can configure and customize KIM data to specify the right set of roles to perform the actions.

canAddNoteAttachment(Document, String, Person)
canDeleteNoteAttachment(Document, String, String, Person)
canEditDocumentOverview(Document, Person)
canInitiate(String, Person)
canOpen(Document, Person)
canReceiveAdHoc(Document, Person, String)
canSendAdHocRequests(Document, String, Person)
canViewNoteAttachment(Document, String, Person)

A sample piece of code from DocumentAuthorize 

public final boolean canInitiate(String documentTypeName, Person user) {
		String nameSpaceCode = KNSConstants.KUALI_RICE_SYSTEM_NAMESPACE;
		AttributeSet permissionDetails = new AttributeSet();
		permissionDetails.put(KimAttributes.DOCUMENT_TYPE_NAME,
				documentTypeName);
		return getIdentityManagementService().isAuthorizedByTemplateName(
				user.getPrincipalId(), nameSpaceCode,
				KimConstants.PermissionTemplateNames.INITIATE_DOCUMENT,
				permissionDetails, null);
}


//This method works in conjunction with Presentation controller to decide the other actions permitted for a user
public Set<String> getDocumentActions(Document document, Person user,
			Set<String> documentActions) {
//sample
              if (documentActions.contains(KNSConstants.KUALI_ACTION_CAN_EDIT)
				&& !isAuthorizedByTemplate(document,
						KNSConstants.KNS_NAMESPACE,
						KimConstants.PermissionTemplateNames.EDIT_DOCUMENT,
						user.getPrincipalId())) {
			documentActions.remove(KNSConstants.KUALI_ACTION_CAN_EDIT);
		}
}

getDocumentActions()

Another common point of guarding users from doing the wrong actions is to prevent them from saving or submitting a document for routing before the document is "ready." DocumentAuthorizer provides a way to turn on and off buttons and even information areas on a document: getDocumentActions(). The method is passed a document, the current user and all actions allowed as parameters, and it then check using IdentityManagementService to remove the actions that are not available for the current user based on KIM data configuration. This method is not final so each transaction document can provide varied implementation as required by the document.

Let's look at how an actual transactional document uses this, sample here is from OrganizationDocumentAuthorizer:

@Override
    public Set<String> getDocumentActions(Document document, Person user, Set<String> documentActions) {
        Set<String> myDocumentActions = super.getDocumentActions(document, user, documentActions);

        if (checkPlantAttributes(document)) {
            myDocumentActions.remove(KNSConstants.KUALI_ACTION_CAN_BLANKET_APPROVE);
        }

        return myDocumentActions;
    }

Here, we can see that the it is first invoking the super() to get current list of actions. Then it specifically validates the plant account attributes to decide whether user should be able to perform "Blanket Approve" action on the document.

Please refer PresentationController and Data Dictionary Attribute Security Definition to see how field level security can be implemented.