Mandatory control properties

Mandatory control properties are object type properties that allow for granular access control to the data stored in objects. You can use mandatory control properties to restrict access to all other properties in the same datasource for a given object, making those properties viewable only by users who satisfy the mandatory controls.

Note: Mandatory control properties are only available on Object Storage V2.

How to use mandatory control properties

1. First, create your marking-backed restricted view (RV). Learn more about creating marking-backed restricted views.
2. Navigate to the Ontology Manager.
3. Choose the object type for which you want to restrict property access, then create or select the property you want to set as a mandatory control property.
4. On the property sidebar, ensure the property is mapped to the corresponding marking column on your restricted view.
5. Set the base type of the property type to Mandatory Control.
   1. By default a mandatory control property supports markings and/or organizations to restrict access.
   2. If you have CBAC enabled, you will have the option to choose classification based mandatory controls.
6. Select the Allowed markings and/or Allowed organizations on the datasource. For classifications, select the Max classification.
7. If the object type has multiple datasources, select a mandatory control property for each of the other datasources to secure their properties as well.
8. Save your changes to the ontology and wait for the reindex to be completed.

Types of mandatory control properties

There are three types of mandatory controls that can be set on a property:

• Markings
• Organizations
• Classifications

Markings

Markings are mandatory controls that restrict access by requiring a user to have a particular Marking in order to access data. If a resource has multiple markings, the user must have all of them to access the resource. Learn more about markings.

To use markings, you are required to provide a set of allowed markings. Only markings in this set will be permitted on any mandatory control property on the datasource.

Organizations

Organizations are access requirements that enforce strict silos between groups of users and resources. Every user is a memeber of only one organization, but can be a guest member of multiple Organizations. In order to access data marked with an organization, a user must be a member of that organization. If a resource has multiple organizations, the user must be a member of at least one of the organizations applied to the resource. Learn more about organizations.

To use organizations, you are required to provide a set of allowed organizations. Only organizations in this set will be permitted on any mandatory control property on the datasource.

Markings and organizations can be used together on the same mandatory control property. In this case, a user must satisfy all the markings and at least one of the organizations to access the resource.

Classifications

Classification markings are mandatory controls used to protect sensitive government information. They are used to restricting access to sensitive information where sensitivity of information is defined in a hierarchical way. Every user can only access data that is classified at or below their own classification level.

You can only configure CBAC markings if you have CBAC enabled on your enrollment. Learn more about CBAC (classification based access controls).

To use classifications, you need to provide a max classification. Only markings that satisfy this max classification will be permitted on any classificatoin based mandatory control property on the datasource.

Classifications can not be used together with markings or organizations on the same mandatory control property.

Datasource-level permissioning

A mandatory control property secures all other properties in the same datasource. For object types with a single datasource, this means that a user will only be able to view an object if they satisfy the value in the mandatory control property.

However, for multi-datasource-backed object types (MDOs), each datasource could have its own mandatory control property. Only the properties backed by a specific datasource will be secured by the mandatory control in that datasource.

This means that it is possible for a user to only have permission to see a subset of properties on an object, In this case, the user will only be able to see the properties mapped from those datasources. Other properties will appear as null when displaying an object instance to the user.

To use mandatory control properties effectively, the backing datasources should be structured in such a way that only properties that should share a mandatory control are in the same datasource.

Validations

The following validations are enforced on mandatory control properties:

• Mandatory control properties must be mapped to a marking column on a restricted view. The mandatory controls are enforced by backing the object type with a restricted view which has a policy that requires users to satisfy the markings in the mapped column to be able to view a row. See Restricted Views for more information.
• Mandatory control properties must be required. This ensures that if an object with a mandatory control property is present on a datasource, the mandatory control must be defined to help maintain data consistency and integrity. Learn more about required properties.
• Every datasource that contains a mandatory control property must define a constraint on what values can be added to those properties. These constrains come in the form of a max classification for classification based mandatory controls, or a set of allowed markings and/or allowed organizations. Any edits made to the mandatory control properties, as well as the values gotten from the backing dataset, must adhere to the constraint set on the datasource.
  • This constraint is enforced on the object storage level, so even though you may be able to use Ontology Manager to save an object type that violates this constraint, the object type will fail to index if existing values in the dataset do not satisfy the constraints, or if the values in the dataset are updated to include invalid values for the mandatory controls. Also, any edits made that try to set an invalid value to the mandatory control property will be rejected and the Action will fail to submit.
  • These allowed markings, allowed organizations or max classification will be used to mark any exported dataset that is materialized from this Object type. This ensures that only users who can view all rows on the Object type will be able to view the materialized dataset.

Note that mandatory control properties are set to Hidden by default. This is because mandatory control properties are meant to be used as markings for other fields, so there is usually no need for mandatory control properties to appear in object views or tables. However, mandatory control property visibility can still be enabled if needed.

Mandatory controls in Actions

You can add a mandatory control parameter to your Action type. This can be a marking parameter, or a classificaton parameter if CBAC is enabled. Organization parameters are currently not supported.

Mandatory control parameters are commonly used to set a mandatory control property on an object that the Action creates. In this case, the values provided must adhere to the property's allowed values, if an invalid value is provided, Action submission will fail.

You can also add a max classification at the parameter level, for classification based mandatory control parameters. This is an action type validation, and so will prevent the Action from being submitted if the provided value does not satisfy the max classification, as opposed to relying on the datasource validation which will allow the Action to be submitted but will fail to complete.

Objects created by Actions will be secured by the provided value for the mandatory control property, just like objects derived from a backing datasource.

Marketplace usage

Object types with mandatory control properties and action types with mandatory control parameters can be packaged and installed through Marketplace.

When packaging an object type with mandatory control properties, the allowed markings or max classification are declared as installation inputs for that product.

Similarly, if packaging an action type with a classification based mandatory control parameter with max classification set, the max classification is declared as installation inputs.

When installing the product, you will be prompted to select the allowed markings or max classification for each mandatory control property. The selected values will be set as allowed markings or max classification of the mandatory control properties upon install.

Note that packaging multiple mandatory control properties and/or parameters with the same values would results in only one mandatory control input being declared.