Managing the Provisioning System

Managing the DirX Identity Provisioning System consists of the following tasks:

  • Installing and uninstalling DirX Identity. See the DirX Identity Installation Guide for more information.

  • Configuring DirX Identity Provisioning. See the DirX Identity Installation Guide for more information.

  • Setting LDAP limits

  • Starting the DirX Identity Manager

  • Monitoring the provisioning system

  • Tuning the provisioning system

Logging in To DirX Identity Manager

Perform the following steps to log into DirX Identity Manager (Provisioning).The following steps show how to log into the Sample Domain.If you intend to log into another domain, use your domain name wherever My-Company is displayed in this procedure:

  • Select Start → Programs → DirX Identity Vx.x → Manager.

  • Click the Provisioning view group.

  • In the Server field, click the down arrow and select My-Company from the list.Ensure that User DN is set to cn=DomainAdmin,cn=My-Company.If it is not, click the down arrow and select it from the list.

  • If My-Company does not appear in the Server list, click image1 to open the Manage Server Profiles dialog.Click New to create a new server profile.Enter the following values into the fields in the Server dialog:

    Name = "My-Company with Domain Admin"
    Description = "Profile for My-Company to enter with Domain Admin account"
    Host = "localhost"
    Port = "389"
    BaseDN = "cn=My-Company"
    DefaultUserDN = "cn=DomainAdmin,cn=My-Company"

  • Click OK to store the profile. Click Close to close the profile list window.

  • Select My-Company in the Server field. Be sure that the User DN field is set to cn=DomainAdmin,cn=My-Company. If not, select it from the list.

  • Enter the password dirx, and click OK.

After a few seconds, the DirX Identity Manager displays its views window.

Manager attempts to log in to the directory server shown in the Server field of the login dialog.If the login operation is successful, Manager closes the login dialog and displays its main window.If the login operation fails, Manager displays an error message and places the cursor in the password field.

You can click Cancel to cancel the login procedure.Manager closes the login dialog and opens an empty main window.You can perform a new login sequence if you change the view or by performing 'Login' at the top level node of the current view.

For details how to customize the login dialog, to create or maintain server profiles see the section "Basic Patterns" in the DirX Identity online help (click Help in the login dialog).

Setting LDAP Client Limits

A size limit specifies the maximum number of entries the LDAP server is supposed to return in a search operation.A value of 0 means that the number of entries is unlimited.

A time limit specifies the maximum time (in seconds) the LDAP server is supposed to take for processing a search operation.A value of 0 means that the time is unlimited.

Size and time limits are used with the following operations:

  • Displaying objects in tree

  • Displaying assignable objects (an incomplete result will be indicated)

  • Displaying senior roles (an incomplete result will not be indicated)

The following operations are performed as unlimited operations:

  • Searching for assigned objects (for example, the accounts that are assigned to a user, the groups of which an account is a member).

Warning: Please be aware that the LDAP server may have global size and time restrictions for searches that DirX Identity Manager can’t exceed. This condition could result in severe configuration database inconsistencies.

The agents do not use any size and time limits. If the LDAP directory server supports the controls “paged read” or “virtual list”, they perform paged reading when searching the LDAP directory. Otherwise, they return to standard search requests. Be sure that in this case the size and time limit of the directory server is set correctly, or the DirX Identity agents could encounter severe problems.

You can set LDAP client size and time limits in the bind profile, the DirX Identity Manager INI file, and in DirX Identity Provisioning domain settings. The next sections describe the settings you can make.

Setting Limits in the Bind Profile

You can set size and time limits in each bind profile that you use during start-up of the DirX Identity Manager. You can also access these settings via the Login command on a tree node in one of the DirX Identity Provisioning views or in the Data View. See the online help topics for details.

These settings have the highest priority.

Setting Limits in the DirX Identity Manager INI File

You can set the parameters ldap.maxresults and ldap.servertimelimit in the DirX Identity Manager INI file.See the section "dxi.cfg" in the DirX Identity Connectivity Administration Guide for details.

The settings have the second-highest priority.

Setting Limits in the DirX Identity Provisioning Domain

The DirX Identity Provisioning domain settings are the settings with the lowest priority.See the "Domain Properties" online help topic for details.Modifying size and time limits in the Options tab has immediate effect for the current Manager session.

Managing Consistency

This section explains how to make sure that objects in the Provisioning domain are consistent and that users have the correct access rights according their manually and automatically assigned privileges.These tasks include:

  • Applying consistency rules on all objects

  • Marking users that are affected by changes in the role hierarchy as "to be analyzed"

  • Performing privilege resolution

  • Performing object cleanup

The next sections describe the DirX Identity workflows that perform these tasks and how to configure them.

Using the Consistency Check Workflow

DirX Identity provides a Check Consistency workflow that applies consistency rules and hard-coded consistency checks to the objects of a Provisioning domain.

The workflow’s configuration parameters include:

  • Enabling the checking of users, roles and permissions, accounts and groups.

  • Defining a search base and filter for each set of objects to further limit the set of objects to be checked.

  • Activating the application of consistency rules and specifying a search base and filter to select only a subset of rules.

  • Enabling the check for privileges to be deleted. With this process, the workflow searches for roles, permissions, and groups in state TBDEL. For each detected privilege, the workflow:

    • Removes the incoming assignments from users and/or senior privileges and sets the To Be Analyzed (dxrTBA) flag for the affected senior objects.

    • Deletes roles/permissions or sets their state to DELETED if history is configured.

    • Sets the state of groups to DELETED.

Because checking all objects one after another can take a long time, you can set up several instances of this workflow to process different sets of objects and rules. This setup allows the workflows to run in parallel and on multiple IdS-J Servers on different systems. For example, you can perform hard-coded checks on users, roles/ permissions, and accounts/groups in parallel. It is even possible to run one workflow per target system. If the number of users and accounts is very high and there are enough systems and CPUs, the search base and filter settings allow you to further split up the set of objects and run even more workflows in parallel.

Note that this workflow does not perform user-privilege resolution. If it changes an attribute that might result in the change of assigned groups for a user, the workflow only sets the dxrTBA flag to indicate that the user needs resolution and sends a resolve event to trigger the resolution in the Resolution Adapter. You should check the query folders in Identity Manager regularly to find the problems reported by this workflow.

Using the Mark Affected Users Workflow

When the role hierarchy is changed - for example, a permission is added to a role or group is removed from a permission - or matching rules in roles and permissions are changed, all affected users must be resolved to calculate their updated set of groups. If a DirX Identity component such as the Business User Interface, Web Center, Identity Manager or the Provisioning services performs these changes, they normally set the dxrTBA flag of the changed objects to true.

The task of the Mark Affected Users workflow is to find such privileges with dxrTBA = true, find the users that might be affected by a change and set the dxrTBA = true flag for these users. The User Resolution workflow will then find these so-called “TBA-users” and send the resolve event to the Resolution Adapter. Therefore, it is best to run this workflow before User Resolution.

The Mark Affected Users workflow cannot be split up and run several instances in parallel.

Using the User Resolution Workflow

The User Resolution workflow:

  • Applies provisioning rules to users

  • Enables or removes user-privilege assignments where start or end dates are reached

  • Finds users where the state has to be changed because one of the corresponding start or end dates has been changed

  • Triggers user-privilege resolution for all matching users.

Configuration parameters allow you to limit the set of users and rules to be evaluated.

For all users that match the configured search base and filter, the workflow evaluates the provisioning rules in the given subtree for rules. When needed, it adds or removes automatic privilege assignments according to the rules and the user attributes. It searches for user-privilege assignments that are either outdated (end date in the past) or need to be activated (start date reached). It searches for users where one of the start and end dates is reached and then changes their states accordingly. Finally, it sends a resolution message for each of them so that the Resolution Adapter resolves these users. Note that when the user filter is empty, the workflow sends resolve messages only for the users with dxrTBA = true.

Setting up Object Cleanup

Most of the DirX Identity objects are only flagged for deletion and are not immediately removed. Set up the according services to remove these objects from time to time. We recommend setting up these services to run every week. You are allowed to leave all objects in the directory, but doing this can decrease performance and reduce oversight.

The most important services for deletion are consistency checking, and deletion consistency rules. The next sections provide more detail about these services.

Consistency Checking

The Consistency Check workflow performs the following delete actions for the objects that match its filter:

  • Deletes all users that are in state TBDEL and whose Delete Dates have expired.

  • Deletes all accounts that are marked with Managed in Target System Only that are in state Deleted in the target system.

  • Deletes accounts that are in state DELETED and whose End Dates have expired.

  • Deletes all groups that are marked for Managed in Target System Only that are in state Deleted in the target system.

  • Deletes groups that are in state DELETED or DISABLED and whose End Dates have expired.

  • Deletes all assignment objects whose End Dates have expired.

Mark Affected Users

The Mark Affected Users workflow finds users that might be affected of changed privileges. (See section "Mark Affected Users" for details.)

Object Cleanup with Deletion Consistency Rules

DirX Identity is delivered with pre-configured consistency rules for the deletion of objects. The default workflow CleanupObjects executes these rules:

  • cleanupDeletedObjects
    Handles the deletion of a huge set of object types.You can change the rule or extend it to handle your object type extensions.

  • cleanupOutDatedDelegations
    Removes outdated delegations.

  • cleanupOutDatedRequWflowInstances
    Deletes outdated request workflow instances.

You can set up separate workflows to run any combination of these rules.

Monitoring DirX Identity Provisioning

The topics in this section describe:

  • How to detect and handle inconsistencies in the DirX Identity Provisioning system

  • How to use DirX Identity Provisioning logging to monitor the system

Detecting and Handling Inconsistencies in DirX Identity Provisioning

The Identity Store (Provisioning views group) is a complex matrix of inter-connected objects: users - roles - roles - permissions - groups - accounts - users.These objects are modified by such diverse applications as:

  • One or more DirX Identity Manager installations

  • One or more DirX Identity Web Center installations

  • The regularly scheduled creation workflows

  • Each target system’s provisioning (synchronization and validation) workflows

DirX Identity Provisioning general function relies on the ability of a set of distributed applications to work together. The overall operation of this distributed system can be disrupted by some malfunction of its integral components or by another LDAP application.

As a result, DirX Identity Provisioning supplies the following mechanisms to help DirX Identity Provisioning administrators identify Provisioning Configuration inconsistencies and repair them quickly:

  • Automatic detection of inconsistencies within DirX Identity Provisioning components

  • Status report generation templates and workflows

  • Query folders

How DirX Identity Provisioning Detects Inconsistencies

Inconsistencies are detected by

  • DirX Identity Manager when a Provisioning object is changed

  • The regularly running consistency workflow performed by service agent

  • The validation workflows for each target system

How DirX Identity Manager Detects Inconsistencies

DirX Identity Manager (Provisioning views group) detects inconsistencies when the administrator modifies an object, as follows:

  • When a user is modified, Manager re-calculates the access rights and thereby navigates the chain of references from the user to his assigned roles, permissions, groups and accounts. In case of errors (broken references: the destination of a link is not an existing object or an object of wrong type), Manager informs the administrator in a message box. If the administrator chooses to store the modifications despite the errors, Manager does not store the new – and presumably invalid – access rights, but flags the user as invalid ("dxrIsInconsistent" = true), stores the error message in "dxrError" and sets the "dxrErrorExpDate". The new access rights are at the latest enforced at this expiration date. This is one of the tasks of the consistency workflow. In the meantime, the administrator can repair the reason for the error and resolve the user anew.

  • Manager not only issues error messages, but also warnings. A typical reason for a warning is when the user is granted a permission, but none of the assigned groups, because the match rule fails.

  • When a role, permission or group is edited, Manager performs some local checks, but by default does not re-calculate the access rights of the affected users. This operation is postponed until the next consistency workflow runs. Local checks especially include valid match rules and the links to the next descendants.

How the Domain Consistency Workflow Detects Inconsistencies

The domain service (consistency) workflow especially checks for:

  • Broken references (the destination of a link is not an existing object or an object of wrong type).

  • Error expiration date in user objects. In this case, it performs a privilege resolution and stores the result regardless of whether there are any errors.

  • Start dates of users that have been created but not yet activated (users in the NEW state).

  • End dates of users (the end of the user’s lifetime).

  • Start deactivation dates of users.

  • End deactivation dates of users.

  • End dates of users or accounts to be deleted. The objects are deleted.

  • End dates of disabled accounts: they are marked for deletion (set to state DELETED) and the new end date is calculated according the MaxTimeToDelete domain parameter.

  • Invalid roles or permissions: no descendants (neither junior role, permission or group assigned), invalid match rule.

  • Out-dated user-to-role, user-to-permission or user-to-group assignments, which are de-activated.

  • Modified roles, permissions and groups. The workflow searches for the affected users and performs a privilege resolution for each of them. This task can be very time-consuming and is therefore not performed in the Manager.

  • Accounts without any user assigned that are not marked as "target system local".

How the Consistency and Validation Workflows Detect Inconsistencies

When the consistency workflow recognizes inconsistencies it cannot repair, it stores appropriate instructions for the administrator in the dxrToDo attribute of the affected object.

The validation workflows automatically check for:

  • Accounts or groups that have been deleted in the target system

  • Accounts or groups that have been added to the target system

  • Group-account memberships that have been added or deleted in the target system

Like the consistency workflow, the validation workflows store such deviations with appropriate messages in the dxrToDo attribute of the affected account or group object.

Using Status Reports to Detect Inconsistencies

DirX Identity Provisioning provides a set of standard status report templates and a set of status report generation workflows that domain administrators and target system administrators use to generate periodic status reports about the Provisioning objects that they are responsible for managing. The topic "Setting up the Status Report Templates" describes the DirX Identity Provisioning-provided report types. Administrators can also create their own status report types; see the DirX Identity Customization Guide for further details.

Administrators should generate status reports on a regular basis. These reports can help them to detect strange combinations because they offer an overview across a number of objects at a glance. Administrators can fine-tune the status report templates so that they extract only those objects in a specified state or with specified attribute value combinations; see the DirX Identity Customization Guide for further details

Using Query Folders to Detect Inconsistencies

DirX Identity Provisioning provides a default set of query folders in each DirX Identity Provisioning view and each target system that you can use to search for and identify objects with:

  • Error or ToDo entries

  • Inconsistent users

  • Users to be deleted

  • Unassigned accounts (accounts without any user assigned)

When you open a query folder, it performs a search on the DirX Identity store (Provisioning Configuration) according to the values in its Filter tab and displays the results as objects underneath the query folder.

You can easily create new query folders or modify the default folders to deliver object sets that meet special conditions and thus highlight exceptional objects in a prominent location.

Provisioning Object Attributes that Identify Inconsistencies

Objects like user, role, permission, account or group have "dxrError" and "dxrToDo" attributes. They inform you about errors that have occurred and of actions you need to perform. The "dxrState" and "dxrTsState" attributes in the account and group objects allow you to compare the states in DirX Identity Provisioning and in the target system. Especially important is the "dxrIsInconsistent" attribute of the user, which indicates users where assigned roles are not consistent with the calculated access rights (see below).

Handling Detected Inconsistencies

DirX Identity Provisioning cannot automatically repair all detected anomalies. DirX Identity Provisioning does a lot to relieve the administrator of this burden by enforcing start and end dates, enforcing access rights of inconsistent users, reapplying deleted group–account assignments and so on. But determining how to correct a broken reference, or how to repair a match rule with invalid permission parameters (for example, delete it?) requires the knowledge of a human administrator.

Consequently, the DirX Identity Provisioning administrator(s) must watch for exceptional situations on a regular basis using the standard (or customized) query folders or reports.

Administrators must delete broken references and objects with the wrong object and must then re-create them. By default, the object class is not displayed and editable in DirX Identity Manager. The administrator can customize the object and property description to allow him to make such changes with Manager or he can use another LDAP client provided with the database to edit these attributes by hand. In the case of assignments, this requires detailed knowledge of the way in which DirX Identity Provisioning stores them in the directory.

DirX Identity Provisioning deactivates outdated assignments, but does not remove them. This gives the administrator the opportunity to be informed of the existence of past assignments and extend them easily, but leaves him with the task of manually removing them.

Matching rules that use attributes that are no longer specified as permission or role parameters remain active, which enables a smooth migration. On the other hand, they carry the danger of security breaches. The role administrator must decide when to modify the rule and enforce the permission parameter changes. The reports can help to determine which users are affected by this permission or role and optionally have to care for proper attribute values.

Special care must be taken of the validation results stored in the account and group objects. Objects deleted in the target system must be deleted manually in DirX Identity Provisioning: the same objects normally cannot be re-created. If accounts or group assignments are needed, DirX Identity Provisioning automatically creates new ones when the corresponding user is resolved. But groups must be created by the administrator manually. In any case, these should be an issue for the DirX Identity Provisioning target system administrator and the local target system administrators.

DirX Identity Provisioning Logging

The following DirX Identity Provisioning components perform logging functions:

  • DirX Identity Manager

  • DirX Identity Service Agent

DirX Identity Manager Logging

DirX Identity Manager trace logging is controlled by keys in the file install_path\GUI\bin\dxi.cfg.

See the section "Using DirX Identity Manager → Customizing DirX Identity Manager → dxi.cfg" in the DirX Identity Connectivity Administration Guide to understand how to configure the manager logging.

If you don’t specify anything, error messages are written into the file system.nnn.log.

On start-up, DirX Identity Manager removes existing prefix.nnn.log files to prevent inconsistencies between old and new trace messages.

DirX Identity Service Agent Logging

DirX Identity service agent logging is controlled via its initialization (ini) file.See the section "About the Maintenance Agent INI File" in the chapter "Managing the DirX Identity Provisioning System" for information about this file.

Tuning the Provisioning System

DirX Identity contains a lot of comfortable features and concepts that consume a lot of computer power.

The user interface (UI) applications (DirX Identity Manager, Business User Interface (BUI), Web Center) display complex information for users that are composed of the content of many objects (users, roles, permissions, groups, accounts).When assigning and resolving privileges, the role hierarchy must be navigated, role and permission parameters evaluated, SoD must be checked, sometimes approval workflows must be started or tickets created, and the real-time provisioning actions must be triggered.The time for performing all these actions is highly dependent on the number of objects (users, roles, permissions, groups), the use of parameters (role and permission parameters) and on the complexity of structures (role hierarchies, hierarchical group structures).

To minimize the time for an end user waiting in front of a UI application, assigning a privilege and resolving the assignments to the access rights in the target systems have been split.The client, namely the UI applications, only perform what is necessary before storing the requested changes: check consistency of input data, check SoD, start approval workflows and create tickets where necessary.If privilege resolution is necessary, they send a resolve message that is processed by a Resolution Adapter in an IdS-J server asynchronously in the background.This Resolution Adapter resolves the users, calculates the new access rights, and triggers the real-time provisioning.

Due to the variety of possible combinations of all the relevant parameters, there is no general approach that guarantees acceptable performance.To optimize your system, you can adjust some parameters, switch off some of the features or move intensive calculations to the background.

This section gives some hints on how you can tune the system for a specific customer environment.Read it carefully and experiment with the various settings to adapt the system for optimum performance.Identity Manager, BUI and Web Center are controlled by these settings.

Increasing the Number of Resolution Adapter Threads

Each IdS-J Server hosts a Resolution Adapter. It receives messages to perform privilege resolution for a selected user from the queue dxm.request.user.resolve. By default, the adapter starts two listeners. This means with n Java-based servers per domain, n * 2 different users can be resolved at the same time.

To resolve more users in parallel, you can increase the number of listeners per server:

  • In DirX Identity Manager, select the Provisioning view group and then the Domain Configuration view.

  • Select the top-level object and click the Privilege Resolution tab.

  • Set the number of resolution listeners per IdS-J Server in the respective field; for example, 3.

  • Activate the changes by restarting every IdS-J Server.

Tuning the User Edit Operation

To detect inconsistencies in a user entry, DirX Identity Manager must read all tabs of a user entry when Edit is clicked. If inconsistencies are detected, the relevant tabs are flagged and the user must correct them, otherwise the Save button will not be enabled.

It is important that roles, permissions, groups, and accounts are read with all relevant attributes during the first search operation. Otherwise, time-consuming re-reading of entries can occur. This behavior can be controlled by the LoadAttributes section in the User.xml object descriptions.

Changing the Customer-specific User.xml Object Description

If you have extended the role, permission, group or account object in your environment, perform these steps:

  • Open Domain Configuration → Customer Extensions → Object Descriptions.

  • Select User.xml and click Edit.

  • Enter a section like this one:

    <extension>
<loadAttributes>
<roles name="{<your list of extension attributes>}" />
<permissions  name="{<your list of extension attributes>}" />
<groups name="{<your list of extension attributes>}" />
<accounts name="{<your list of extension attributes>}" />
</loadAttributes>
</extension>

  • Save the object.

  • Restart the Manager.

This list will be merged with the list in the previous section.

To test for unnecessary re-reads:

  • Set the trace.level in the file dxi.cfg to 9 (remember the previous value).

  • Restart the Manager.

  • Click a typical user. Click Edit.

  • Open the file system.000.log in the folder install_path\GUI\log. There will be messages like this one:
    DBG(STG100): complete o=MultiMarket,dc=Customers,cn=Users,cn=My-Company (reason: o)

  • Search for the string reason:.

  • Check for multiple occurrences of the same string (for example, during read of roles, permissions, groups). If you find them, enter this attribute to the loadAttributes section.

  • Restart the Manager.

  • Repeat the test until multiple occurrences are no longer visible.

  • Reset the trace.level in the file dxi.cfg,

  • Restart the Manager.

Tuning the Tree Operation

Configure the attributes being requested when searching the node’s children to optimize the tree expansion. Define the requested attributes in the node’s object description in the <children> tag of the <loadAttributes> extension tag.

To optimize expansion of a tree node, run the identity manager with trace level 9 and observe DBG - messages 'complete object_dn (reason: attribute name)' in the identity manager’s system log that are reported when the tree is expanded. In case those messages occur, add the attribute name reported in the message to the load attributes.

Example:

When expanding an organizational unit (or an organization), the following messages can occur:

DBG(STG001): complete <cn=aUser>,cn=Users,cn=My-Company (reason: employeenumber)

To avoid reading each user as a whole, when the tree is expanded, just add employeeNumber to the load attributes for searching children in Org.xml and in OrgUnit.xml:

<extension>
<loadAttributes>
  <children name="{ou,sn,givenName,dxrState,employeeNumber}" />
</loadAttributes>
</extension>
Be sure that you observe the messages resulting from tree expansion.

  • Start DirX Identity Manager with trace level 9.

  • Expand the tree node to be optimized.

  • Quit the Manager and check the messages. Only messages about the objects in the expanded tree are relevant.

  • Repeat this procedure until no more "complete" messages occur.

It is possible to use a JavaScript to create the names displayed in the tree. However, this method does not perform well when dealing with thousands of children in one node. A better strategy is to fill an attribute "displayName" at the user being maintained with each user edit and to display this attribute. Note that the attribute must be added to the load attributes as described above.

Managing Long Delays

Clicking Edit for a user object in DirX Identity Manager or selecting Assign Privileges in the Web Center can cause long delays if the switch "assign.InitialSearch=true" is set in the dxi.cfg file. The delays result from reading a large number of privileges to populate the lists for the privileges to assign. Each of these entries must be checked by an access control operation.

By default, the lists are empty. The user must perform a search operation by defining the filter and clicking the corresponding button. This action can significantly affect performance depending on the number of existing privileges and the complexity of access policies in the configuration.

This behavior is enforced in the Web Center and is the default for the Manager.

Ignoring Nested Group Searches

By default, DirX Identity searches for nested groups in each target system during resolution and check processes. This requires additional time especially with large groups and thus can lower performance significantly.

For target systems that do not use nested groups, you can set a flag to switch off these unnecessary searches:

  • Start the DirX Identity Manager.

  • Login to the Provisioning View.

  • Check the Ignore Nested groups check box in the Advanced tab of the target system.

  • Apply this setting to each target system that does not require nested groups.

  • To activate the changes in the Manager, restart it.

  • To activate the changes in the Web Center, restart Tomcat.

Activating XXL Groups

A search for assigned groups might result in low performance if a target system has only a few groups with a high number of members (this limit depends on the directory server technology in use).

You can activate the XXL group flag at all target systems that meet this condition:

  • Start the DirX Identity Manager.

  • For each target system, select the option XXL Groups in the Advanced tab.

  • To activate the changes in the Manager, restart it.

  • To activate the changes in the Web Center, restart Tomcat.