Policy definition structure¶
Policy definition consists of meta data information and other key constructs like policy author(s) and target resources along with the fine-grained actions available on those resources. These important constructs are described below as Subject and Rules.
Subject¶
These are the actors, who are allowed to perform certain actions on certain resources. These actors include individual users (email address), user groups.
User¶
mdsp:core:identitymanagement:< region >:< environment >:user:user@example.com
User Group¶
mdsp:core:identitymanagement:< region >:< environment >:usergroup:administrators
- region
Region where tenant is hosted, for e.g. eu1, eu2 etc. - tenant
Name of the tenant
Rules¶
A rule is just a container that holds tuple of actions and resources. A policy can contain multiple rules, and maximum number of rules per policy is mentioned under limits.
Actions¶
These are the actions, that subjects are allowed to perform on given set of resources. The general syntax for action is:
mdsp:core:< service >:< object >:< action >
Service
Name of the service that has exposed this action, and can perform that action on given object.
Object
Object is the entity, that associated service manages, and exposes certain actions for that object. Object can be same as resource or it can be different from resource. For example, in case of IDL, object and resource are same, i.e. prefix. The same is applicable for Asset Management service as well. But, for Time Series service, Time Series is the object, but the associated resource for which this action is exposed is an asset. So, in other words, it is an action to allow specific operation on Time Series data of a given asset(s).
Action
This is granular action that can be performed on the object, in the context of associated resource. Complete list of such actions are mentioned here An action may depend upon another action, for example, a user can perform any operation on any event of an asset, provided user also has read access for that asset. If such is the case, then both of these actions must be present in same policy.
If read access on an asset and allow access for event are provided in different policies, then dependency would not be considered as fulfilled and policy creation update would fail. Hence, it is important to consider action dependency during policy creation or update.
A dependency matrix is mentioned here
Resources¶
- These are the resources that a subject mentioned in policy is allowed to perform actions mentioned in associated rule.
- The action may not directly be on the mentioned resource, rather the object mentioned in the action, but in the context of given resource, as explained above.
The general syntax for a resource is:
mdsp:core:< service >:< region >:< tenant >:< resource >:< resource path >
Currently, asset and IDL prefix are the only resource types supported. Both of these resource types support hierarchy. And, such hierarchy can be specified in a policy as well. Hierarchy can be specified using a special parameter called propagationDepth, which is set at rule level, and gets applied to all the resources in that rule.
Propagation Depth¶
Propagation depth defines how deep into the hierarchy of resources the defined actions given in the same rule are applicable. This parameter is available only at the rule level, meaning the depth specific in this parameter is applicable for all the resources in the given rule.
It supports 3 values:
- All children or -1: the resource and all its descendants are included in the eligible resources. Use this if you want to grant access to defined subsections of your environment dynamically.
- Only selected or 0: only the resource mentioned is included in the effective list of resources. Its descendants are excluded. This is used to restrict access to a specific selection of resources only.
- Direct children or 1: the resource and its direct descendants (only) are included in the effective list of resources.
To illustrate it further, consider a plant building, its floors, rooms, and machines in those rooms are modelled in asset hierarchy.
| Resource | propagationDepth | Effective Resources |
|---|---|---|
| 2nd-floor | -1 | - 2nd-floor asset - All room assets on 2nd floor - All machine assets in all rooms on 2nd floor |
| 2nd-floor | 0 | 2nd-floor asset ONLY |
| 2nd-floor | 1 | - 2nd-floor asset - All room assets on 2nd floor |
Best Practice
For the scenarios where whole or part of the resources tree structure needs to be given same access privileges (for example: asset hierarchy), then an administrator could specify Propagation Depth value as -1, thereby avoiding a long list of individual resources.