Propagating changes with idtrack

This section shows you how to configure idtrack to propagate tracked changes using settings in the Manage the system (PSA) module and a PSLang script.

The idtrack program is part of Bravura Security Fabric ’s automated user administration system that tracks changes to users, user attributes, and user group memberships on target systems and propagates those changes to other target systems.

You must write an idtrack.psl script to propagate changes to accounts, group memberships, or account attributes.

You can propagate profile and request attribute changes to target systems:

Automatically, with no scripting required
By writing an idtrack.psl script to make the changes
This may be required for more complex cases, or for more flexibility.

For automatic profile and request attribute propagation, the idtrack program can operate in:

Execute mode – idtrack is executed to propagate changes whenever auto discovery is executed.
Write mode – idtrack writes changes to a work file, which you can use manually with iddriver to make changes. Use write mode to perform dry runs of user attribute propagation, testing, troubleshooting or for performing one time manual user attribute propagation.

Under normal circumstances, you should set up automatic propagation to run in execute mode to propagate user attribute changes and write an idtrack.psl script to propagate account, group membership, and account attribute changes.

If the idtrack.psl script contains a syntax error, then idtrack.exe returns an error code during auto discovery, and a notification email is sent to the Bravura Security Fabric administrator.

You set up static authorization for automatic or scripted attribute propagation by assigning authorizers at the target system level. You can also determine authorization dynamically with an IDSYNCH AUTH CRITERIA MOD plugin program .

During automated provisioning, the View and update profile (IDR) module and web module plugins are bypassed. The Workflow Manager Service (idwfm) plugins are still called; specifically the ATTR VALIDATION, IDSYNCH AUTH CRITERIA MOD PLUGIN, and IDWFM REQUEST REWRITE PLUGIN.

Diff sets

Before idtrack can take actions based on changes, the changes have to be tracked. This function is performed by iddiscover automatically during auto discovery.

Changes on target systems are tracked using diff sets that are identified by a globally unique identifier (GUID). A new diff set is created every time auto discovery is executed and at least one tracking option is activated.

Set the KEEP DIFF DAYS variable in Maintenance > Options if you want to limit the number of diff sets stored in the database. By default Bravura Security Fabric keeps them forever.

Requirements

Each system on which idtrack operates must be configured as a target system.
At least one tracking option must be enabled.
The idtrack.psl script, if required, must be located in the \<instance>\script\ directory.

Usage

idtrack -difflist <N> |[ -diffset <guid>|latest -threshold <N>]

Option	Description
-difflist	List the <N> newest diff sets. If N= 0 , list all available.
-diffset	Run with specified or latest diff set.
-threshold <N>	Do not submit any request if number of requests to be submitted exceeds <N>. If N= 0 , no threshold. Using this option overrides the ATTR AUTO PROPAGATE THRESHOLD setting.

Examples

To list the five newest diff sets:
```
idtrack -difflist 5
```
To list all available diff sets:
```
idtrack -difflist 0
```
To run idtrack with the latest diff set:
```
idtrack -diffset latest
```
To run idtrack with a specific diff set:
```
idtrack -diffset "<guid>"
```

The following sections describe use cases and script functions for propagating attributes, groups, or accounts.

Writing the idtrack.psl script

The idtrack.psl script is required for propagating changes to user accounts and account association, group memberships, or account attributes. It is optional when tracking changes to profile and request attributes.

A sample script is located in the samples\ directory in the Bravura Security Fabric distribution. The sample script simply prints out all the changes into the idmsuite.log .

With scripted propagation, any tracked change can be a triggering event to perform any provisioning operation allowed via the application programming interface (API).

To perform scripted provisioning, the script needs to make API calls based on decisions made by the script.

The script must include idtrack-types.psl, which is shipped in the \<instance>\script\ directory. This file provides structure definitions that are necessary for the script to query what changes have been tracked.

The script must define a processChange function:

processChange( const $userid, const $isProfile)

This function is called once for every user for which idtrack discovers changes.

If changes were discovered for items that are attached to a user profile, then $userid is set to the profile ID, and $isProfile is 1.

If the changes were discovered for items that are not associated to a user profile, then $userid is the account longid, and $isProfile is 0.

The script can include startup() and shutdown() functions when idtrack starts and finishes. The behavior of the startup() function is based on the return value:

0 (or no return value) – continues to call processChanges on tracked changes
1 – halts without error
-1 – halts with an error

Functions for capturing changes are described in the sections that follow.

See also

The PSLAng Reference Manual(pslang.pdf) for details on writing PSLang scripts.
The Bravura Security Fabric Remote API (api.pdf) for details on the API.

Validate automated requests for feasibility

When designing or troubleshooting workflow automation, keep in mind that:

Auto-discovery or idtrack may collect invalid or incomplete data from target systems
Event actions (exit traps) fire at different times during workflow processing, and for all requests
Scripts are called repeatedly, at different times, in different possible pre-defined requests and contexts

A request should not be triggered before all requirements for it (including a recipient) are available in the current calling context. That means that all request data may not be available to custom scripts,whether stand-alone or deployed via components .

Before triggering any new request, verify that the current calling context contains a valid recipient value, as well as the data, such as attributes, target/hostid, operations, relevant to the request.

Other possible dependencies must be checked by the script if:

The operations to be run as part of the request have such dependencies,
and
The Transaction monitor is not configured to repeat failed operations,
or
The dependency is not likely to be added by another operation triggered before the configured retries end.

Positive failures must also be addressed. Operations may fail because the requested entitlement already exists in the target, account or profile where it's being added. These have a low probability of being for the wrong object, but all such possibilities for each entitlement have to be considered at solution design time. For example, if an account is being added to a group where it's already a member, does that operation have to

Fail, because the account may belong to another user with the same identifier,
or
Succeed, because in the current solution there's no chance that target would have two different accounts with the same identifier?

The workflow manager has a limited number of threads for processing requests, and will process its reqbatch database table "queue" in order. That means that triggering a large number of automated requests at the same time will prevent manual requests from being processed until previously-triggered requests have finished processing.

Propagating profile and request attribute changes

Changes to profile and request attribute values can be tracked. You can configure the idtrack program to execute a variety of provisioning actions automatically. A common use case is to track changes to a profile and request attribute to synchronize attributes on target systems.

To configure idtrack to synchronize profile and request attributes:

Determine which attributes are authoritative and what changes should occur based on changes to authoritative attributes.
Configure profile and request attributes to be tracked and set the Track changes to this attribute option.
Configure attribute propagation by:
- Configuring attribute logic .
  Or
- Writing an idtrack.psl script .

Configuring automatic attribute propagation

To set up profile and request attribute logic settings for automatic propagation:

Click Manage the system > Workflow > Options> Automation .
Enable ATTR AUTO PROPAGATE EXECUTE to automatically execute the propagation of changes to profile and request attributes to account attributes on subordinate systems.
Set the ATTR AUTO PROPAGATE REQUESTER field to a valid Bravura Security Fabric user. This is the user that will submit change requests to the Bravura Security Fabric workflow system.
Enable ATTR AUTO PROPAGATE WRITE to automatically write the propagation of changes to profile and request attributes to a work file. You can set this one alone to make changes manually, or combined with ATTR AUTO PROPAGATE EXECUTE for logging purposes.
Set the ATTR AUTO PROPAGATE THRESHOLD to control the number of requests to be submitted due to changes to profile attributes, unless overridden on the command line. If the threshold is exceeded, no requests will be submitted automatically by idtrack . Bravura Security Fabric sends an email to the product administrator (defined by RECIPIENT EMAIL) who can decide whether to run idtrack manually to submit those requests.

Scripting attribute propagation

Scripted attribute propagation is not as simple to set up as automatic propagation, but is more flexible. A tracked change can be a triggering event to perform any provisioning operation allowed via the API.

Two built-in functions are available to the idtrack.psl script to determine changes to profile and request attributes:

getProfileAttrAdded()
getProfileAttrDeleted()

To prevent a profile and request attribute from automatically being propagated, call the autosyncAttrDisable() function from the startup() function in the idtrack.psl script.

In this example, the profile and request attribute "FIRST_NAME" will not be automatically propagated.

 autosyncAttrDisable( "FIRST_NAME" );

Propagating account attribute changes

Changes to account attribute values can be tracked. You can configure the idtrack program to execute a variety of provisioning actions automatically. To configure the idtrack program to propagate account attribute changes:

Override the account attribute default value.
Select the Track changes option.
Write an idtrack.psl script.

Two built-in functions are available to the idtrack.psl script to determine changes to account attributes:

getAccountAttrAdded()
getAccountAttrDeleted()

Propagating group changes

Changes to groups can be tracked. You can configure the idtrack program to execute a variety of provisioning actions automatically. To configure the idtrack program to propagate group membership changes:

Configure Bravura Security Fabric to manage the group.
Set the Track changes to this group option.
Write an idtrack.psl script.

Two built-in functions are available to the idtrack.psl script to determine changes to group memberships:

getGroupMemberAdded()
getGroupMemberDeleted()

Propagating account changes

Changes to accounts can be tracked. You can configure the idtrack program to execute a variety of provisioning actions automatically. To configure the idtrack program to synchronize accounts on target systems:

Configure the target system in Bravura Security Fabric .
Set the Track changes to accounts on this target option.
Write an idtrack.psl script.

Three built-in functions are available to the idtrack.psl script to determine changes to accounts:

getAccountAdded()
getAccountDeleted()
getAccountAssocChanged()

In this section: