$maskedAccess() - Masked Fields

This keyword is used to display, inside the current instance, values that are stored in a separate, access-controlled definition, without ever duplicating those values in the current definition. Unlike $restricted(), which hides a field of the current instance from users outside a given group, $maskedAccess() keeps the sensitive data in a definition of its own — with its own permissions governing direct access to it — and pulls it in, masked, only where it is needed.

$maskedAccess() is applied to a group field. The fields inside that group use $maskedInfo() to choose which fields of the secured definition are shown.

Install

cob-cli customize masked-access

Usage: ​

$maskedAccess(definition_name,reference_field)

Options:

• definition_name: the name of the secured definition that holds the sensitive fields
• reference_field: the name of the reference field in the secured definition that points back to the current definition. RecordM uses it to find which instance of the secured definition belongs to the instance being shown

Parameter	Description
definition_name	The secured definition where the sensitive values are stored. Its own field keywords ($restricted(), $editForGroup(), …) and permissions continue to apply.
reference_field	The reference field declared in the secured definition, pointing at the current definition. The secured instance is the one whose reference_field matches the current instance.

WARNING

$maskedAccess() must be used on a field that is also declared as $group. The keyword has no effect on a regular field. It is normally combined with $expanded so the masked block is open when the instance is displayed.

$maskedInfo() - Showing a masked field ​

Each field inside a $maskedAccess() group declares which field of the secured definition it displays.

$maskedInfo(remote_field)

Options:

• remote_field: the name of the field in the secured definition whose value is shown in the current instance

WARNING

$maskedInfo() is only valid on a direct child field of a group configured with $maskedAccess(). It is not resolved on fields placed outside that group, nor on fields nested one level deeper inside a subgroup of it — the masked values must be listed immediately under the $maskedAccess() group.

How the values are displayed ​

A $maskedAccess() group is rendered as a highlighted block, visually separated from the rest of the instance, with a reveal button (the crossed-out eye) that switches the values between their masked form and their real value.

INFO

The values inside the group are always masked when the instance is displayed — each one is shown as ************ — and are only revealed when the user deliberately clicks the eye button. Opening, printing or sharing an instance on screen never exposes the sensitive data on its own; it takes an explicit action by the user every time. The values are never stored in the current definition: they are read from the secured definition each time the instance is displayed.

$maskedAccess() is a masking and auditing mechanism, not an access barrier on the displaying instance. Any user with the privilege to see the instance that wraps the sensitive information will be able to reveal it: the crossed-out eye is there so the values are not exposed by accident when the instance is opened, printed or shared on screen, and so that each reveal is registered. Restricting who can reach the values at all is done the usual way by the permissions of the secured definition, which govern direct access to it, and by the field keywords declared on the group, not by $maskedAccess() itself.

Creating and updating the secured instance ​

The $maskedAccess() group can also take the user straight to the secured definition, so the sensitive values can be maintained without searching for the right instance there. Which link is shown depends on whether a secured instance exists and on the user's permissions in the secured definition:

Situation	What the user sees
A secured instance exists and the user has update privileges on it	A Click here to update link next to the group title, which opens that instance in the secured definition.
No secured instance exists yet and the user can create instances in the secured definition	A Click here to create new link inside the group, which lets the user create an instance in the secured definition.
The user has neither privilege	No link. The masked values (if any) are shown as usual.

INFO

These links do not grant any additional access: they only appear when the user already holds the corresponding privilege in the secured definition, and the create or update itself happens in the secured definition, under its own permissions and field keywords.

Examples ​

1. Device credentials kept out of the equipment inventory ​

The Devices definition is the operation's equipment inventory: everyone in support consults it to find a device's vendor, model and management address. The access credentials of those devices are needed in the same place — an operator troubleshooting a device should not have to go looking for them elsewhere — but they should not sit in plain sight in the inventory, they should exist in a single place instead of being copied into every device record, and each time someone reads them that should be traceable.

The credentials are therefore stored in their own definition, Device Credentials, which has a reference field Device pointing at Devices:

Device              $ref(Devices)
Admin Password
Enable Password
SNMP Community

Devices then shows them through a masked group:

Name                $instanceLabel
Management IP
Credentials         $group $expanded $maskedAccess(Device Credentials,Device)
  Admin Password        $maskedInfo(Admin Password)
  Enable Password       $maskedInfo(Enable Password)
  SNMP Community        $maskedInfo(SNMP Community)

In this example:

• Credentials is the group that carries the masked access. $expanded keeps it open when the instance is displayed.
• Device Credentials is the definition holding the passwords. It is the single place where they live, and the only one whose permissions need to be reviewed for direct access.
• Device is the reference field inside Device Credentials that points at Devices. The credentials shown are the ones whose Device is the device being displayed.
• Each child field displays one field of that secured instance.

WARNING

This keeps the credentials masked and their reveals traceable, but it does not stop a support user from revealing them: whoever can open the Devices instance can click the eye. If the credentials must not be reachable at all by users outside the network team, restrict the Credentials group itself so the block is only rendered for that group.

The instance then shows a Credentials block with the three values masked, ready to be revealed when a user clicks the eye icon:

Each time a user reveals the values, RecordM registers the access as an instance of the Masked Access Audit definition:

The record contains:

• Access Date: when the values were revealed.
• User: who revealed them.
• Source Instance: the instance where the values were revealed, here the Devices instance core-sw-lis-01.
• Referred Instance: the secured instance the values were read from, here the Device Credentials instance for that device.
• Information Accessed: the names of the fields that were revealed (Admin Password, Enable Password, SNMP Community).

INFO

The audit record lists which fields were revealed, never their values, so the sensitive data is not copied into the audit trail.