Customizing Target Systems

A target system usually contains groups and accounts; this is the default for most of the systems.But you also may use target systems without accounts, or you may need to use another attribute instead of the common name to reference the account from the group.

Use the following attributes of the target system object to configure these situations:

Assignment States: Set to true if the account-group memberships are synchronized with a target system.In this case, the synchronization workflows need the state information in order to know which members to add or delete in the target system.

Member property: This attribute is only evaluated when no assignment states are stored; that is, Assignment States is set to false.In this case, it specifies the group attribute where the group members are stored.By default, DirX Identity uses dxrGroupMemberOK.

Referenced Object Type: This attribute specifies the object type that is to be stored as a group member.This attribute is usually the account; in this case, you select SvcTSAccount.Otherwise, users are the group members and you select dxrUser.

Referenced property: The attribute specified here is entered into the group Member property. It must be a valid attribute of the Referenced Object Type.

The following subsections provide some examples.

For each target system, you can define a set of default values that DirX Identity uses when it automatically creates accounts.Open the "Options" pane of the target system object and examine the pre-defined attributes.Enter appropriate values for each of them.

Each target system type offers its individual set of attribute types, which are described in the individual target system topics in this section.The following two attributes are used for all target system types:

These attributes are set by the Initial Load workflow and updated by the validation workflows.

To define new default values for the target system, you must change the object description of the target system object and add a line for the new attribute.Navigate to the Object Descriptions subfolder of your target system’s Configuration folder and open the TS.xml entry.You will find a list of property definitions like this one:

Enter a new line for your new attribute.For more information about the property definition, see the section "Property Sheet and Property Page Elements".Your new attribute will appear in the target system object after you log out and log in again, or after you reload your object descriptions.

This section provides information about customizing the following default target systems supplied with DirX Identity.

In some cases, access rights in a target system are not expressed by a mere group membership, but instead by appropriate settings of account attributes. An example of this is the Active Directory account, which is mailbox-enabled by setting the attributes mail address, home MTA, home MDB, and so on.In DirX Identity, on the other hand, an access right in a target system is modeled only by a group membership.Obligations help to keep group memberships and appropriate attribute settings synchronized.

Obligations are attached to target system groups in DirX Identity. They comprise operations to be performed when an account becomes a member of the group (OnAssignment) and when it is removed from the group again (OnRevocation). To discover existing attribute-based access rights, you need to define a validation filter that is applied to the account attributes. For details, see the section "Understanding Rule Types" in chapter "Managing Policies" in the DirX Identity Provisioning Administration Guide. If you have complex rules requiring JavaScript programming, see the section "Using JavaScript in Obligations" in this guide.

You can either use an existing group or create a new "virtual group", which only lives in DirX Identity and is not synchronized with the target system. Use existing groups if they fit with the intended privilege. Specify the OnAssignment and the OnRevocation operations and the validation filter for the group. Use a separate obligation object if several groups share the same operations and filters.Enter the common operations and filter parts into the obligation and the specific parts into each group. Don’t forget to link the groups to the obligation. Ensure that there is a validation rule for this target system that includes the modified groups in its group filter.

If your rules for the attribute values to be set in the OnAssignment/OnRevocation actions are too complex to be described with standard naming rules, you can use JavaScript to calculate the values.

In this case, the OnAssignment/OnRevocation operations are merely used to trigger the invocation of a JavaScript program.

Example:

Let’s assume you want to set multiple values of a multi-value attribute sampleattribute.Multi-value attributes are not handled with naming rules in obligations, so you use a trigger attribute - for example, $obligationtrigger - to initiate the invocation of a JavaScript program setSampleAttribute.For this purpose, the JavaScript program is connected to a second pseudo attribute - for example, $scripttrigger - that depends on the $obligationtrigger attribute.

Then, in the OnAssignment action, define $obligationtrigger with the value assign.In the revocation action, define $obligationtrigger with the value revoke.These definitions allow distinguishing between assignment and revocation of the group.

The account’s object description contains the following property descriptions:

The JavaScript program writes multiple values v1, v2, v3 into sampleattribute on assignment and removes the values on revocation. Change this script according to your needs:

If you want to set multi-value properties in the OnAssignment/OnRevocation actions, you can use a special syntax for the values:

Examples:

To illustrate this syntax, let’s use the same actions given in the section “Using JavaScript in Obligations”:

OnAssignment: “<clearall><add>v1<add>v2<add>v3”

After OnAssignment, the property contains the three given values. The <clearall> prefix takes care of clearing any values that already exist, so in every case after OnAssignment, we have exactly these three values.

OnRevocation; “<clearall>”

After OnRevocation, the property is empty.

Now let’s suppose that we want to add two specific values during assignment and then remove these values during revocation:

OnAssignment: “<add>v1<add>v2”

The given two values are added to the values of the property that already exist.If a value already exists, the value is ignored.Values that already exist are also present after OnAssignment.

onRevocation: ““<del>v1<del>v2”

The two given values are deleted from the property.The values are ignored if they are not present.After revocation, these two values are no longer present.All other values are still present.

An account entry usually inherits some attributes from the associated user, sometimes just as a default value when the account is created (see the section "Defining Default Values for Account Creation").Sometimes the account attributes change when the corresponding user attribute changes.In other cases, the account attribute has a different name from the user attribute, but has the same or a deferred value.DirX Identity offers some features that help in such situations.

To simply inherit a user attribute with the same name, use the master key.It is used as the default value when the account is created and is updated each time the user attribute changes and DirX Identity either edits the user or the account.Typically, this operation is performed regularly by the RBAM agent when it performs consistency checks.

In the following example, the account inherits the surname from its associated user:

The master="dxrUserLink" instruction directs DirX Identity to get the attribute value of the sn property from the object referenced by the link in the attribute dxrUserLink. This is the corresponding user object. Note that the property must have the same name in both objects.

To inherit a user attribute with another name is a little bit trickier. The dependson key helps here, because it allows you to specify a dependency between one attribute in an entry and another attribute of the same entry. Each time the original attribute value changes, the naming rule of the dependent attribute is executed.

As an example, assume that attribute displayName stores the account’s surname and given name, which in turn should be taken from the corresponding user attributes. The display name is re-calculated whenever the surname or the given name of the user changes.

The following property definition ensures that the attribute is taken

Different target systems usually require their individual name spaces for their accounts and groups.Each target system type has its individual attributes - for example, Active Directory Service (ADS) recognizes a guid, a surname and a given name, while Windows NT does not - and you may want to use specific rules for generating account names, passwords or other attributes.

To manage target system-specific name spaces, DirX Identity supplies object and property page descriptions that are specific to each target system type.When you create a new target system, type-specific defaults are created and located in the Configuration folder for the target system.

When it reads an account or creates a new one, DirX Identity uses the DN of the entry and matches it to the mapping element in each object description to determine which object description to use for the account.Here is an example:

The example mapping element directs DirX Identity to choose this object description if the entry in question contains the dxrTargetSystemAccount object class (which is valid for all accounts) and contains a part of the object description’s DN. This is expressed through the variable $(./../../..), which is to be read analogous to file system notation: $(.) is the DN of the object itself, $(./../) is the DN of its superior, and so on. For an account object description, $(./../../..) is the DN of the target system entry and is replaced by it when the object description is loaded.

Please do not change these mapping elements.

Frequently, DirX Identity must create an account automatically when it detects that a user has received an access right (a group assignment) for a target system where he hasn’t had one before. Then it must create the mandatory attributes (the unique name of the account, and perhaps the surname and a password) without administrator interaction. Therefore, you must provide appropriate default values or naming rules for DirX Identity to use.

Attributes such as "surname", "givenname" or "telephonenumber" usually receive the same value as the associated user. Furthermore, if the user’s attribute value changes, the value in the account must also change. Here you should use the master attribute of the property element in the object description. You’ll find an example for the surname in the section "Properties and Property Elements" in the chapter "Customizing Objects".

For other attributes, the same default value may apply for all accounts; for example, the user profile attribute "dxrPwdNeverExpires". Here you can use the defaultvalue inner element of the property element:

Naming rules must be specified for the generation of the account name and perhaps the password.Naming rules can be simple, in XML notation, or complex, in JavaScript.For more information, see the subsections on naming rules in the section "Customizing Provisioning Object Property Descriptions" in the chapter "Customizing Objects".

Some target systems allow only a limited number of members in their groups.DirX Identity offers features to manage these situations.

The target system object offers an attribute Group Member Limit where you can enter the limit of allowed group members for this target system.DirX Identity then observes this limit.When it needs to enter a new member into a group, which causes it to exceed 90% of the limit, it creates an extension group and enters the new member there.The extension group becomes a member of the "master" group, so that all of its members get the same rights as those in the master group.The naming rule is to extend the name of the master group with a number starting with "0".

The extension groups are not offered for group assignment and thus do not become groups in their own right.In the user views, DirX Identity displays the extension group members as if they were in the master group.So the user administrator does not even notice the extension groups.But they are shown in the group objects, both in the Member and Member of tabs.Their assignment state is displayed as EXTENSION.

Note that this feature is only implemented for target systems where the members in DirX Identity are stored at the groups, not at the accounts.

Some target systems require an attribute value that is unique within all accounts or even unique within all accounts and groups (as RACF does).

With the XML attribute uniqueIn="…​" you specify for a property the root of the subtree at which the property value must be unique.It uses the relative path notation "../.." beginning with the object description entry to navigate to the root.See the object description for the target system type RACF for a sample, which denotes the target system node as the root.

Before storing the new entry, the system checks the uniqueness of the calculated property value.If it is not unique, you need some mechanism to re-calculate the value until it’s unique.DirX Identity provides a retry mechanism using a configurable retry counter, a virtual property, to support this requirement.The retry counter virtual property can be read in Java scripts and naming rules via obj.getTries() in order to calculate unique values.

What do you need to configure?

In the property description of your unique property, you reference the counter using the XML attribute dependson=…​.

Here is a sample snippet of the object description:

This configuration specifies the property racfid to be unique within all accounts and groups of the target system. The retry counter is the virtual property $racfIdCount. The additional option applyDependsOn="save" tells the system to apply the property dependency not on each change, but only before the whole entry is to be stored.

Note that you can define a list of comma-separated properties on which your property depends. Make sure that the counter is the first one in your list.

If storing the entry or the uniqueIn check fails, the system recalculates the property values. It automatically increments the retry counter (in the previous example, $racfIdCount) and invokes the naming rule or JavaScript program again. The script or rule must use the counter property to generate a unique value.

Here is a JavaScript code snippet that shows how to read the property:

It reads the counter property in string format and then transforms the string to an integer value.If a maximum number of retries has been reached, it notifies the system of an error by storing the string JavaScript.Error into the return variable racfid.See the appropriate script for the target system type RACF as a full example.

Sometimes naming rules result in the same value of an account’s naming attribute cn for different users.In this case, you need a mechanism to re-generate the value of the naming attribute until it is unique.

If the system cannot create an account because one already exists with the same naming attribute, it retries it using another retry count.For such scenarios, you need to generate the attribute value using a Java script.The system calls the same script, but the object’s getTries() method returns a higher retry count.

This approach gives a lot of flexibility for generating unique values.

The simplest approach is just to compose the value by including the retry count.See the following sample snippet:

The next snippet shows another alternative, which includes an increasing number of surname characters into the attribute value:

If the number of retries exceeds a given limit, you can cancel the loop.See the following snippet:

The return value JavaScript.Error indicates an error and the system cancels account creation and displays an error message when in interactive mode or raises an exception when in batch mode.

For some target systems, you may want to have new accounts automatically created in a subtree, not directly underneath the accounts' base node.To set this up, you must to specify naming rules for the account’s distinguished name (DN).

The virtual attribute $superior helps here.It denotes the DN of the supposed parent node of the new account.Use a Java script to calculate an appropriate value using other attributes of the user or account.The system tries to create the new account underneath the assumed parent.If this operation fails because the parent does not yet exist, the system automatically creates this parent.If this operation also fails for the same reason, it repeats this until a parent exists.See the sample property description for the default target system.

To define a user or account attribute that holds a binary certificate: