Masking will customize the display of a field, when the full value cannot be shown to the user of a lookup, inquiry, or document. When masking occurs on a document, the document authorizer is consulted so both the user and the state of the document may be taken into account.
When masking a value in a lookup, inquiry or maintenance document via the data dictionary, there is a tag to specify the mask with three value options:
- Literal String.
E.g., 'Not Displayed', or '***********', or ''...
- Preset tag for masking up to a certain number of characters. This would mask the first 6 characters of the string, with the actual characters of the remaining string displayed as is.
- Specify maskFormatter class. This class must implement the MaskFormatter interface. The framework will send in the actual value, and the implementation can implement any masking needed.
Lookups & Inquiries
The lookup and inquiry frameworks check the authorization tag of a field before it is displayed in a result table or inquiry page. If the user is not in the required workgroup, the mask string will be displayed. In addition, no sub-inquiry links will be rendered on the field (if applicable).
To mask a value in lookups and inquiries, simply specify a workgroup and mask in the attribute definition in the data dictionary. For example...
What if a masked fields is part of the key for another inquiry? Because the URL for a given inquiry page is generated by KFS, KFS uses the encrypted value in the URL itself, therefore protecting that data from being viewed.
A secure field is displayed without restrictions if specified as a lookup search field in the data dictionary xml file. If the need occurs to not display the field later on, we will add an attribute to the lookupField tag to specify the authorization. The need for a different workgroup on the search field could also be needed. If the user does not have permissions on the field, it will still show masked in the result set.
Maintenance documents use the maintenance document data dictionary definition to specify that fields on a document should be masked. When a
<maintainableField> is defined for a sensitive field, it is associated with an edit mode. Note: multiple sensitive fields may be associated with the same edit mode, but each sensitive field must be associated with exactly one edit mode.
For example, the following code defines the taxIdNumber field of the Payee BO as a secure field.
The above XML snippet may be interpreted as follows: There is a field named taxIdNumber on the document. This field is only viewable (and editable, if appropriate) if the "taxEntry" edit mode is in the map returned by the document authorizer's getEditMode(). If the edit mode is not in the map, then the "*********" masking string will be used to hide the sensitive value.
The Disbursement Voucher Payee maintenance document uses org.kuali.module.financial.document.authorization.PayeeDocumentAuthorizer as its implementation of DocumentAuthorizer; it's override of getEditMode() shows how the "taxEntry" edit mode is exported:
In line 3, the method checks if the current user is a member of whichever workgroup is specified by KFSConstants.FinancialApcParms.DV_TAX_WORKGROUP for the DisbursementVoucherDocument class; if the current user is a member of that workgroup, then on line 4, the "taxEntry" edit mode is added to acceptable edit modes, and therefore the field will not be masked/encrypted. Users not within the specified DV_TAX_WORKGROUP will see the max and have an encrypted variable.
For documents other than maintenance, the edit mode in which to display and the mask should be given as attributes to the htmlControlAttribute.
The Document Authorizer would then have to return a correct edit mode for the field to be unmasked.