Skip to content

Propagating Role Changes

The Propagate Role Changes task manages updates to identities' entitlements when changes occur in the role model. Specifically, this task is necessary to manage removal of entitlements which are removed from role definitions, although it will propagate additions to role definitions as well.

Follow these steps to configure and use this task:

  1. Click gear > Global Settings > IdentityIQ Configuration and click the Roles tab. Select Allow propagation of role changes. This turns on the creation of RoleChangeEvents, which record changes to the composition of any role. Be sure to save your changes.

  2. Navigate to Setup > Tasks and choose New Task > Propagate Role Changes. This task can be configured to run policy checking as it updates identities' role and entitlement data to match the role changes. It can also be configured to run for limited time durations; when a number of minutes is specified, it will not start processing a new event when that number of minutes is reached, but it will process the current event to completion before terminating, even if that extends past the time limit.

  3. Schedule the task to run on a regular basis, as appropriate for the installation's role model change volumes and role management preferences. Role changes are captured and propagated for the role on which the change occurred and for any role which inherits from or requires the changed role.

For more information, see Propagate Role Changes.

Automated Propagation of Role Changes to Role Members

The role propagation feature in IdentityIQ allows any changes made to a role, including new and removed roles, changes in hierarchy, and changes in entitlements, to be propagated to all identities that are assigned that role. This allows you to use the role model as an authoritative source for requested access.

Note

Entitlements that were detected are not removed from an identity during role propagation, unless they are also part of an assignment.. Only those entitlements that were assigned, individually or as part of a role assignment, are removed during propagation.

Examples of role changes include:

  • Role requirements changes, such as adding or removing an entitlement

  • Role Inheritance changes, such as disabling or enabling role

  • Changes to the list of required roles are needed

Globally Enabling Role Propagation

To use role propagation, the feature must be enabled globally. This is done in the gear menu > Global Settings > Configuration > Roles tab.

To enable role propagation, select the Allow propagation of role changes option on the Roles tab.

How Roles Are Propagated

Once role propagation is enabled, role changes can be automatically provisioned when the role propagation task is run. Changes are provisioned to all identities that are assigned the role that is being propagated.

When a role is changed, the change is saved as a RoleChangeEvent. The Propagate Role Changes task processes these events, provisioning the role changes to the identities that have that role assigned directly or indirectly.

Changes are saved and provisioned in the order they were created; in other words, in a "first in, first out" sequence. Consider this example of role changes, made in this sequence:

  1. Add entitlement A

  2. Remove entitlement A

In this example, the end result is that the identities with this role should not have entitlement A. If the sequence were reversed, the end result would be that the identities would have entitlement A. Understanding the sequential nature of role changes is important for error handling and troubleshooting.

The provisioning plan for all role change events is calculated before the task starts, when the role change occurs, and only role change events created before the Role Propagation task runs are processed by the task during that run. This means that changes to roles that are made after a role propagation task has begun will not be included in that run of the task.

To learn more, see Propagate Role Changes.

Troubleshooting and Managing Errors in Role Propagation

There are several ways you can manage errors and troubleshoot role propagation activity.

Duration limits

A role propagation task can be configured with a "Number of minutes task should run" setting, which is the maximum number of minutes the task should run before terminating. After each event is processed, IdentityIQcompares the actual task duration to the specified maximum; if the task has run out of time, the task is terminated without proceeding to the next event. Note that the duration is not checked in the middle of an event, so an event will not be cut off without having a chance to finish.

Retrying failed identities

When an error occurs that causes an identity to failing on a given role change event, IdentityIQ does not delete the role change event. It keeps track of any identity that failed for the event, and on a second run of the task, can process the role change event only for those identities that failed in an earlier run.

Pruning "stuck" events

If a failure occurs that can't be resolved with a retry, the role change event can potentially stay "stuck" in the processing queue indefinitely. The Role Change Propagation Task includes a parameter that allow the pruning of stuck events: Maximum failures before event pruning. This parameter sets the number of times a role change event can fail to progress before it is pruned. A failure to progress is defined as zero successes on the event during the task. Events that are blocked by other pending events are not counted as failing to progress. If this value is left blank, the event will never be pruned until it has been fully processed.

Setting a task failure threshold

The task also includes a Maximum failure threshold parameter that limits how many identities can fail to be provisioned by a single role change event, expressed as a percentage of the total number of identities affected by the event. All partitions for a role change event are allowed to run to completion, and once finished, the transition request computes the actual failure percentage and compares it to the maximum failure threshold. If the percentage is exceeded, the propagation terminates. Note that this does not mean that a single role change event will stop as soon as it hits the maximum; it means that if an event exceeds the maximum, no more subsequent events will be processed.

Evaluating results

Once the task has run, the Task Result UI shows various statistics, including errors. For role propagation, the Number of identities failed/pending and Number of stale events pruned statistics can be useful in troubleshooting errors. In the Debug pages, the TaskResult and RoleChangeEvent objects can also be reviewed for troubleshooting purposes.

Role Changes on Disconnected Systems

By default, neither the Identity Refresh task nor the Role Propagation task will push entitlement changes to target systems when a manual work item is required to support provisioning. To do so could result in an overwhelming number of manual work items from even a single role definition change.

With the Identity Refresh task, there is a task option that allows you to request generation of manual work items for provisioning requests. It is called Enable the generation of work items for unmanaged parts of the provisioning plan.

This option does not exist in the Role Propagation task. Instead, in the Role Propagation task, there is an option to have the task run a business process in which you can do whatever you choose (including forcing the creation of manual work items). That business process must be named in the systemConfiguration Configuration object, in an entry called workflowLCMRolePropagation.

Keep in mind that provisioning of these un-propagated changes can also be handled on a user-by-user basis, as they will be visible in certifications. Un-propagated role content additions will appear as "missing required roles" in a certification, and un-propagated role content removals will result in the "extra" entitlements or IT roles appearing individually in the certification details. The certification can then trigger manual provisioning work items to process additions, or an informed certifier could revoke the no-longer-required extra access.

Role Change Propagation on Import

If you need to import role changes or new role definitions without creating role change events and initiationg role propagation, you can set an option on the import to suppress role change event creation. In the iiq console this option is -noroleevents.

For example, to import roles specified in a file called roles.xml without creating role events for role propagation, specify this command in the iiq console:

import -noroleevents roles.xml

In the Import from File page (gear menu > Global Settings > Import from File), you can suppress role change event creation by selecting the option No role events generated for role propagation.

For more information see IdentityIQ Console and Import From File.