Policy Rules

Introduction

Policy rules are very powerful mechanism that spans a very wide range of use cases. It can be used to define role approval, lifecycle of midPoint objects, policies such as segregation of duties, notifications and other governance and compliance rules.

Policy rules provide a basic mechanism for many identity governance and regulatory compliance features, as policy rules often define high-level business-oriented policies. Governance policies defined by policy rules are applied on top of usual access control policies, such as role-based access control (RBAC).

Structure

Each policy rule has the following parts:

Name and description of the rule are used for configuration management and diagnostics. The rule name will be displayed in the log files when the rule is processed.
Focal object that the rule applies to. This defines the object that is being changed. E.g. this is the user that receives a new assignment, or it is the role that is being created.
Target object (optional). This is used when applying the rule to the assignment. The target object represents the target of the assignment, which is usually a role, org or a service.
Condition (optional) when the rule should be applied. If the condition is not specified it is assumed to be true.
Policy constraints specify when the rule is triggered. E.g. the rule may be triggered when a role is assigned, when the role is changed, when the role is not assigned to any user or when it is assigned to too many persons and so on.
Object mark reference (optional) points to object mark which marks violation of the rule. Affected object is marked in the repository, which can be used for analytic and reporting purposes.
Policy actions specify the actions that are to be taken when the rule is triggered. The actions may range from strong enforcement of the rule (i.e. prohibit the operation) through Approval to a very mild actions such as notifications.

Some of these parts may be implicit. E.g. if the rule is defined as a high-order inducement in the metarole then the focal object or target are implicit and does not need to be explicitly specified.

Application

The policy rules are used to implement wide variety of mechanisms:

Assignment approvals: policy rules may be used to change the default assignment approval schemes in a very flexible and scalable fashion.
Role lifecycle management: policy rules may be used to enforce approvals of new roles before they are used in production. They may be used to approve changed role definitions. And so on.
Compliance reporting: policy rules may be used to set mark in the affected objects. The mark may be used in reports to identify the objects that violate compliance rules, to report the percentage of compliant vs non-compliant objects and so on.
Flexible notifications, ad-hoc recertification and other governance and compliance features that are planned for future midPoint versions.

Rule Content

Policy Constraints

TODO

This section needs to be expanded. However, documentation work is similar to the development work in that it takes time and that it needs funding.

If you are midPoint subscriber, you can request that we complete this section and we will do that as soon as possible. Or you may use the option to sponsor completion of midPoint documentation.

In case that several policy rule constraints are specified at the same time then logical AND is assumed between them. I.e. all the constraints must be satisfied for the rule to get triggered. This is a natural way in which to express overlapping time intervals, modification of several properties at the same time and so on. However, this may be counter-intuitive for some cases, such as exclusion constraints. However, even for exclusion this approach makes complete sense. The logical AND between exclusion may be used to implement "triangular" exclusion and other advanced exclusions schemes. It is just a matter of getting used to.

In case that you need a logical OR between several constraints you just need to re-formulate them into several policy rules. Each of the policy rules is triggered individually, therefore implementing logical OR operation.

Object Marks

Object marks indicate result of policy rule execution. Object mark is set on focal object affected by triggered rule.

Marks can be used to locate objects for which the rule was triggered, which are usually the objects that violate a policy.

See Gradual Enforcement of Policies for example usage of marks with policy rules.

Policy situation

MidPoint 4.8 and earlier used policySituation instead of object marks. Use of policySituation is deprecated and strongly discouraged.

Policy Actions

The action part define what to do when the rule is triggered. There are several options:

enforce: Enforcement means that violation of the rule is not allowed. Any attempt to violate the rule will end with an error. This is an action that strictly enforces the policy.
prune: Pruning means that the conflicting assignments are removed. Any other assignments that are in conflict with the assignment that triggered the rule will be "pruned": they will be removed. The removal of the conflicting assignments is automatic and silent. It will not be subject to approvals or other policy constraints. This mechanism can be used for example to implement set of roles where only one of the roles can be assigned at a time. When a new role is assigned the existing roles that are in conflict with the new role will be unassigned.
approval: Approval means that the request will be subject to an additional approval. The approver may decide whether to allow violation of the rule. If the operation is approved then it proceeds.
record: Violation of the rule will be recorded using a mark. The mark can be used to report violations, and gradually enforce the policy. Except for the mark, the operation will proceed and the rule will not affect it.
certification: The object will be scheduled for a certification campaign after the operation is done. This action works with certification campaign. Therefore, it is ideal for actions that are frequent and can occur on large number of objects. The campaign is an efficient method how to handle mass decisions. However, it mat not be started immediately.
notification: Notifications are sent at the end of the operation.
scriptExecution: Execute script (action). The operation will proceed, script(s) are executed at the end of the operation.
suspendTask: Stop action. This action stops the operation after n executions and results with the error.

Rule Definition

The policy rules can be defined at several places in the system. Each definition method applies to different focal/target objects and have different manageability and scalability properties. However, all the rules are evaluated in the same way regardless of the specific method of their definition.

Global Policy Rules

Policy rules can be defined in system configuration object. In this case the rule is evaluated for every operation, and it applies to all objects that are matched by the rule focus and target selectors. This method of rule specification has a global scope, and therefore the administrator can have high confidence that the rule is applied to all objects to which it should be applied. However, it may have scalability impact if not used properly. Evaluation of the focus and target selectors is usually very fast, therefore a reasonable number of global rules with simple selectors should have only negligible impact on system performance. However, large number of rules with complex selectors and conditions may significantly impact the performance.

The global policy rule is defined in a system configuration like this:

<systemConfiguration>
    ...
    <globalPolicyRule>
        <name>immutable-role</name>
        <policyConstraints>
            <modification>
                <operation>modify</operation>
            </modification>
        </policyConstraints>
        <policyActions>
            <enforcement/>
        </policyActions>
        <focusSelector>
            <type>RoleType</type>
            <filter>
                <q:text>riskLevel = "high"</q:text>
            </filter>
        </focusSelector>
    </globalPolicyRule>
    ...
</systemConfiguration>

This rule applies to all roles that have risk level set to high. The rule enforces the modification constraint, which prohibits any role modification. An attempt to modify such role will result in an error (policy violation).

Direct Rule Definition

The rules may also be defined directly in the objects to which they apply. In this case the rules are defined in the assignments:

<role>
    <name>Immutable role</name>
    <assignment>
        <policyRule>
            <name>immutable-role</name>
            <policyConstraints>
                <modification>
                    <operation>modify</operation>
                </modification>
            </policyConstraints>
            <policyActions>
                <enforcement/>
            </policyActions>
        </policyRule>
    </assignment>
</role>

This is the same rule as in the previous case. The rule prohibits role modification. The focal object is implicit in this case - it is the object that contains the rule. There is no need for an explicit focus selector.

However, this method is not very practical - it is not very manageable. It is difficult to manage large number of roles when the rules are specified in each role separately. Therefore, this approach is not recommended for production use. The metarole-base approach is recommended instead.

Metarole-Based Rule Definition

Policy rules can be defined in the assignments, which means they can be taken to the meta-level using the usual midPoint mechanism of metaroles. If all the sensitive roles have the same meta-role assigned, then the rule can be easily defined in the metarole as (high-order) inducement. Like this:

<policy>
    <name>Untouchable metarole</name>
    <inducement>
        <policyRule>
            <name>untouchable</name>
            <policyConstraints>
                <modification/>
            </policyConstraints>
            <policyActions>
                <enforcement/>
            </policyActions>
        </policyRule>
    </inducement>
</policy>

In this case, policy rule is placed in the inducement, not in the assignment. Therefore, the rule does not apply to the policy object where it is defined, it applies to the roles that have the policy assigned. This is simple and scalable way to define policies that apply to selected roles, organizational hierarchies, services and so on. This approach is often combined with classifications, clearances and other policy objects. Archetypes can also be used as meta-roles for application of policy rules.

See Using Meta-roles for Policy Configuration page for more details about the meta-role mechanism.

Policy Rule Exceptions

They say that there is always an exception to any rule. Whether that is the truth or not, there is often a need to make an exception from a policy rule. Common use case is an exception from Segregation of Duties policy: the policy states that certain roles cannot be combined. However, if the request goes through a special approval, then it might be allowed. This may seem like a straightforward mechanism, but it is not. It is not enough to simply override the policy and allow assignment of conflicting roles. Such conflicting assignment would appear in every review, compliance report, the approver will be asked for re-approval after even a minor change in the assignment and so on. To fully support this scenario, it is necessary to remember the decision to suppress policy rule: to create an exception.

MidPoint has a mechanism to support exceptions from the policy rules. Policy exceptions are stored in the assignment that triggered the policy rule. As long as the exception is stored there, the referenced policy rule is deactivated for that specific user and that specific assignment. The rule will not be subject to re-approvals, it will not be raised as an issue in compliance reports and so on. In the future that information can be used e.g. to report approved rule exceptions, to re-certify then and so on.

History

This feature is available only in midPoint 3.6 and later.

This feature was also available in midPoint 3.5. However even in midPoint 3.5 this feature was considered EXPERIMENTAL except when used for Role Lifecycle and assignment-based approvals. This mechanism was only partially implemented in midPoint 3.5.

Compliance

This feature is related to the following compliance frameworks: