Customizing Auditing

This chapter explains how to customize DirX Identity’s auditing features, including:

  • Query folders

  • Audit policies

  • Certificate owner check

  • Status reports

Creating a Query Folder

Query folders are a type of persistent LDAP query.They are displayed as folders in the DirX Identity Manager tree and - when opened - perform an LDAP search using the search parameters specified the query’s Filter fields, and displaying the result as nodes below the query folder.In DirX Identity, query folders are primarily used to display objects that are in an "exceptional" (inconsistent or error) state in a prominent location in the tree.As a result, you can use query folders for auditing or maintenance tasks.

The DirX Identity installation provides sample query folders in both Provisioning and Connectivity views.In the Provisioning view group, the sample query folders are located at the root of the user subtree and in each target system’s subtree.They can be used, for example, to search for and display:

  • Inconsistent users

  • Users with values in their To do or Error fields

  • Users that are marked as "to be deleted" (State=TBDEL)

  • Unassigned accounts (an account without an associated user, for example, system accounts)

  • Active and inactive rules and policies

In the Connectivity view group, the sample query folders are located in the Expert and Monitor views. They can be used for example to search and display:

  • Active or inactive workflows and schedules

  • Workflow instances with errors or warnings

You can copy these query folders and modify the copies to create your own set of queries.(Changing the sample query folders is not recommended, because the changes you make will be overwritten with each DirX Identity update.).You can also create new query folders according to your requirements.

A query’s LDAP search criteria consists of the following parameters (which are displayed in the Filter tab when you open a query folder in DirX Identity Manager):

  • The search base

  • The search scope (see the online help for details)

  • The search filter, in LDAP notation.Refer to RFC 2254, "A String Representation of LDAP Search Filters" for further details.An extension is provided to allow for building timing constraints (see the online help for details).

  • The maximum number of entries to be returned as a result; when this limit is reached, DirX Identity terminates the search and notifies you of this exception.

Customizing Audit Policies

The section "Managing the Audit Trail" in the "Managing Auditing" section of the DirX Identity Provisioning Administration Guide describes how to manage and customize audit policies.

Customizing the Certificate Owner Check

This section describes

  • recommendations and hints for implementing a certificate owner check

  • the matching algorithm of DirX Identity’s built-in certificate owner check.

  • how to write your own custom certificate owner check.

Recommendations and hints

Implementing a secure certificate owner check requires to follow some guidelines:

  • First check your certificates which user attributes they contain.

  • If a GUID is contained (a global unique identifier), use this attribute as check parameter. Such attributes are defined by automatic algorithms and users are not allowed to change this identifying attribute. We highly recommend that only the GUID creation process should have the directory access right (ACI) to write this attribute.

  • If no GUID attribute is available, you can use another unique attribute. In many cases the mail attribute is used. This means that you must protect this attribute against unauthorized changes. A process must be in place that defines this attribute, adds it to the certificate during creation and stores it at the user entry. Only this process should have the directory access right (ACI) to write this attribute.

If you follow these recommendations, your certificate owner check is secure.

Built-in Certificate Owner Check Matching Algorithm

DirX Identity supplies a default verifier, that uses the following algorithms to identify the certificate owner:

  • The attributes are checked against attributes being read from the X509Certificate Object using the method getSubjectAlternativeNames().

  • If no matching value is found, the certificate owner’s DN components are checked. The check is done case-insensitive, without naming attributes.

  • In case DN is used as attribute name, the signer’s DN is compared to the DN extracted from the certificate by getSubjectDN().getName().

  • The DNs are normalized and compared case-insensitive. Since certificates often contain OIDs, only the DN component values, not the naming attributes, are used in comparison.

In case multiple attributes are entered in ‘Attributes to check’, each attribute value has to match (AND condition).

Custom Certificate Owner Check Matching Algorithm

If the default verifier does not meet the customer’s requirements, he may write an own verifier and enter its fully classified class name in the Custom Owner Verifier Classname field at the domain object (Auditing tab). Note that the custom verifier has to implement the Interface com.siemens.dxm.api.audit.SignatureOwnerVerifier.

It contains the methods

setSigner(ImmutableEntry signer) - passes the logged-in user to the verifier

setParameters(String parameters) - passes the ‘Attributes to check’ to the verifier

verify(X509Certificate certificate) - called to verify the owner.

Java interface definition:

package com.siemens.dxm.api.audit;
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) Atos 2011
* All rights reserved.
*
* This software is the confidential and proprietary information of
* Atos IT Solutions and Services GmbH ("Confidential Information").
* You shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Atos IT Solutions and Services GmbH.
*
* END OF COPYRIGHT NOTICE.
*/

import java.security.cert.X509Certificate;
import com.siemens.dxm.api.entry.ImmutableEntry;
/**
* This interface provides the methods to verify the signer owns the certificate
*/

public interface SignatureOwnerVerifier {
/**
* sets the person who signed the data
*/

public void setSigner(ImmutableEntry signer);
/**
* sets the parameters for verification (e.g. the signer's attributes to be verified)
* @param parameters
*/

public void setParameters(String parameters);
/**
* verifies that the correct certificate was used for signing, i.e. the signer is the owner of the certificate.
* @param certificate
* @return
*/

public boolean verify(X509Certificate certificate);
}

Customizing Status Reports

DirX Identity status reports represent a powerful generic mechanism for extracting and viewing information about the current state of objects in the DirX Identity store, particularly bulk information on selected DirX Identity objects and their relationships to other DirX Identity objects.Status reports do not provide history information.

A report consists of an XML configuration for extracting data from the DirX Identity store and an XSLT program that transforms the extracted data.DirX Identity provides a set of pre-configured, ready-to-use reports that return information on the DirX Identity Provisioning and Connectivity objects and their related objects in a format that is tailored to the way these objects are presented in DirX Identity Manager and Web Center.

Reports can be displayed in DirX Identity Manager and Web Center (only for Provisioning objects), and they can be downloaded to files.They can be generated on demand from DirX Identity Manager and Web Center, and they can be generated automatically by DirX Identity workflows that run at scheduled intervals.

In the Provisioning view group, access policies can be used to control who is allowed to run a given report; for example, to permit only those users who are assigned an auditor role to run a report that checks for SoD exceptions in the DirX Identity store, or to permit a specific group manager to run user-role assignment reports only on the members of his group.

The pre-configured reports provided with DirX Identity are designed to be highly customizable.You can copy these pre-configured report templates and pre-defined subroutines and then modify them to your requirements using XML and XLST/XPATH.

Reports in DirX Identity also support the concept of virtual attributes, which represent complex DirX Identity logic for values displayed in DirX Identity Manager or Web Center. A virtual attribute is a value displayed in DirX Identity Manager or Web Center that represents the result of multiple LDAP attribute searches and a computation made on these attributes.

The next sections provide:

  • General information about how reports work and how to customize them to your requirements

  • Information that is specific to customizing provisioning reports

  • Information that is specific to customizing connectivity reports

Status Report Architecture

A status report is partitioned into the following elements:

  • A producer, which makes the basic supply of DirX Identity objects of interest available to the selector.

  • A selector, which defines the attributes to load, handles the relationships these objects may have with other DirX Identity objects (triggering additional LDAP searches to load the related objects) and creates an intermediate XML output that is passed to the transformer.

  • A transformer, which creates the desired format (by applying an XSL transformation, in most cases) and passes the result to the consumer.

  • A consumer, which typically stores the result in one or more files, depending on its size.

The following figure shows the data flow between these report elements.

Report Data Flow
Figure 1. Report Data Flow

When displayed in DirX Identity Manager, a report object consists of the following tabs:

  • A General tab, which contains a Types field that determines whether or not the report is made available when right-clicking an object and selecting Report.

  • A Content tab, which stores the report’s XML definition. The Content tab contains the producer, selector and consumer definitions.

  • A Format tab, which stores the XSL transformation that turns the output of the selector that is defined in the XML into the desired result.

Running Status Reports

DirX Identity allows you to run status reports dynamically from DirX Identity Manager and Web Center and to schedule automatic runs of pre-defined reports.

From DirX Identity Manager, you can:

  • Select an object or a folder and select from a set of status reports that can be generated for the object

  • Select a report, and then select the object or folder (by specifying the search base) on which the status report is to be generated

(For Provisioning objects only) From Web Center, you can:

  • Select a single object and then select from a set of reports that can be generated for this object

  • Select a single tree object and then select from a set of reports that can be generated for this object

  • Select a folder in a tree and then select from a set of reports that can be generated for this object

DirX Identity provides provisioning and connectivity status report agents that you can set up to run a report automatically at scheduled intervals. These agents actually consist of a workflow with one activity - the status report agent - that runs in the C++-based server. To set up a scheduled status report, you start one of the status report agents, and then supply the information about the report you want to produce. The report agent will then run the report at a scheduled time.

Matching Status Reports to Objects

The Types field in the report object’s General tab determines whether or not the report is made available in a context menu when the object specified in the field is selected (right-clicked). The class attribute of an action element in the corresponding object description specifies the reports that can be run for the object. The following figure illustrates this relationship.

Report Object and Object Description Matching
Figure 2. Report Object and Object Description Matching

For example, the user object description role.xml (Provisioning → Domain Configuration → Object Descriptions > role.xml) contains the following action class definition:

<action class="siemens.dxr.manager.actions.ActionReport" parameter="role" />

This definition specifies that all reports whose General > Types field specify Role are considered to be reports that are suitable for role objects. If you change the report’s Type field to specify Roles without changing the object description’s action class definition accordingly, the report will no longer be considered a role report.

The role.xml object description does not apply to role objects because of its name.Instead, it applies to them due to a clause such as:

<mapping><attribute objectclass="{any}dxrRole"/></mapping>

This clause specifies that this object description applies to all objects where one of its object classes is objectclass=dxrRole.If the prefix "(any)" is omitted, dxrRole must be the only object class.

Creating or Changing Status Reports

You should not change the standard connectivity and provisioning status report objects provided with DirX Identity. Instead, you should copy and modify them to create your own new report objects. Although you may want to completely change a report, the most likely changes you might want to make are:

  • Changing the search base to reduce the output volume.

  • Changing the LDAP search filter to reduce the output or to search for objects with special characteristics.

  • Changing the attributes to be displayed with each object.

  • Changing the output format and output files.

To create your own status report from the templates provided with DirX Identity:

  • Look for a report definition that most nearly matches your requirements

  • Copy this report

  • Change the producer as you need it

  • Produce an XML format to a file to check and understand the XML structure (are all objects and attributes contained?) For performance reasons, check also that no objects and attributes are contained that you do not need.

  • Adapt the transformer routines step by step

  • Add attributes clauses to display all attributes

  • Check for helpful existing sub-routines

Status Report Content Tab

A status report’s Content tab displays the report’s object description, which has the following structure:

<report>
<import file=.../>
<producer> ... </producer>
<selector> <entry> ... </entry> <entry> ... </entry> ... </selector>
<html><transformer> ... </transformer><file><consumer> ...</consumer> </file></html> and/or
<txt><transformer> ... </transformer><file><consumer> ...</consumer> </file></txt>       and/or
<xml> <transformer> ... </transformer><file><consumer> ...</consumer> </file></xml>   and/or
<another output type> <transformer> ... </transformer><file><consumer> ...</consumer> </file></another output type>
</report>

A status report object description begins with an optional import element, followed by a producer, followed by a selector, followed by one or more output-related clauses such as html, txt or xml.

The next sections describe this report structure in more detail using a sample report as it is used or as it could be used for user objects as an example. The following figure shows this report’s Content tab in DirX Identity Manager.

Example Content Tab
Figure 3. Example Content Tab

Producer Element

A producer defines an LDAP search in XML. The producer is a Java class that searches for objects in the DirX Identity store that match an LDAP search and passes the search result to the selector. You define for the producer which objects to search, while you define for the selector the attributes to extract from these objects; for example, the state of a role in addition to its name.

DirX Identity supplies two producer Java classes (other producer Java classes, including customer-supplied ones, are basically possible, too):

  • ObjectEnumerationProducer - the standard producer that can perform any LDAP search. It uses the "virtual list view" or the "simple paged results" control (if the server supports them). These controls allow the client to handle large search results in a resource-saving way.

  • UnassignedRoles - a specialized producer that is intended to be used in reports that list roles that are not assigned to any user.

Here is an example of a producer:

<producer class="siemens.dxm.storage.report.ObjectEnumerationProducer">
<search base="cn=users,$(rootDN)" filter="$(SearchFilter)" scope="$(SearchLevel)"  sizelimit="$(MaxNumberOfEntries)" attributes="$(RequestedLdapAttributes)" order="$(SortOrder)"
/>
</producer>

The class attribute determines which producer to use.

The search clause expresses an LDAP search request. This example uses a number of variables that apparently are defined elsewhere; therefore this producer appears to presume an import element that imports them. For example:

<import file="storage://DirXmetaRole/cn=Settings for Producer/Selector,$(./..)?content=dxrObjDesc"/>

In this example:

  • The import element addresses a directory object whose last RDN is cn=Settings for Producer/Selector.

  • $(./..) specifies that this object is located below the same node as the object that defines the report.

  • content=dxrObjDesc specifies that the variables are found in the attribute dxrObjectDesc of this object. This is why the tab that presents this information in the DirX Identity Manager is called "Content".

Import Element

The import element is intended to include additional code for example a selected set of variables that are defined elsewhere. The keyword include can also be used as an alternative to import.

Selector Element

The selector is a Java class that allows you to restrict the amount of data extracted from the DirX Identity store by the producer. It also allows you to expand the amount of data extracted beyond the capabilities of LDAP searches. The use of multiple entry clauses permits you to structure the selector to satisfy relationships that the objects provided by the producer may have with other objects; for example, to create a status report on users and attributes of their assigned roles. (Note that these attributes are role attributes, not user attributes.) The selector provides the data in an intermediate XML format from which any desired output format can be (preferably XSL-) transformed.

DirX Identity provides the following selector Java classes (customer-supplied selectors are also possible):

  • dom.SelectorImpl. - the standard selector

  • dom.ScriptSelectorImpl - allows you to write your own selector in JavaScript. Since this typically implies programming internal, unpublished interfaces, its use is rather limited.

Here is an example of a selector that refers to the producer example given in the "Producer Element" section.

<selector class="siemens.dxm.storage.dom.SelectorImpl">
<entry>
<match><property name="$odname" value="dxrUser" /></match>
<property name="attributes" value="$(RequestedLdapAttributes),$(RequestedVirtualAttributes)" />
<attr/><value/>
<reference maxDepth="0"><match><property name="name" value="$(DNsToBeDereferenced)"/></match></reference>
</entry>
<entry>
<match><property name="$odName" value="dxrRole"/></match>
<property name="attributes" value="$(RequestedRoleAttributes)" />
<attr/><value/>
</entry>
<entry>
<match><property name="$odName" value="svcGroup"/></match>
<property name="attributes" value="$(RequestedGroupAttributes)" />
<attr/><value/>
</entry>
</selector>

The class attribute determines which selector to use.

Within the entry clause:

  • The match element filters entries from the producer’s input stream by name and by value (wildcards are supported)

  • The attributes element selects attributes or virtual attributes

  • The reference element follows references to directory subentries

  • The child element follows references to one level of subentry

  • The entry element defines the details of the subentry (child or referenced object)

In the example provided here:

  • The first entry clause selects most of the data that the producer has provided and some additional attributes that are subsumed in a variable called RequestedVirtualAttributes. This entry clause filters out - based on the first match clause and the property clause- all entries from the producer’s output that match the object description with "<object name="dxrUser">" (in this example, Provisioning view > Domain Configuration > Customer Extensions > Object Descriptions > User.xml) and adds the attributes named in the variable RequestedVirtualAttributes as additional attributes.

  • The attr clause specifies that the attribute names are to be provided.

  • The value clause specifies that the attribute values are to be provided.

  • The reference clause leads to the entry clauses that follow; it lists the DNs that are to be de-referenced and expects details in these entry clauses. To avoid loops, you should always define the depth to which the references should be followed. In this example, maxDepth="0" specifies that only one level is followed.

In order for the second entry clause to be useful, RequestedVirtualAttributes and DNsToBeDereferenced must contain the name of the virtual attribute Roles.Assigned. This attribute provides DNs of object class dxrRole and the second entry clause specifies the attributes that are to be provided in addition to these DNs. If the reference clause is not present, this entry clause will not match anything, since the producer does not produce any role objects. If the match clause is missing within the reference clause, all references that have a matching entry clause are resolved.

The third entry clause follows the same principles, but it manages the virtual attribute Groups.Assigned rather than *Roles.Assigned*.

The following figure illustrates another example of a selector.

Example Selector
Figure 4. Example Selector

In the figure, the left side shows the DirX Identity object structure and the links between the objects. The right side shows a possible selector definition. The basic objects to search are role objects (this is defined in the producer). The assigned user objects can be found via the virtual attribute Affected.Users. This virtual attribute completely hides the complexity of the DirX Identity object structure. This is also important if the object structure must be changed. The virtual attribute will hide this change completely. The link from the User objects to the Assignment objects is followed by the reference statement (not visible in the figure).

Here are some hints about selectors:

  • Deleting lines such as <property name="attributes" value="$(RequestedLdapAttributes),$(RequestedVirtualAttributes)" /> is helpful for test purposes, since this deletion causes all attributes - including all or almost all virtual attributes - to be revealed in the XML output.

  • A selector expects the producer to pass in "storage objects", which represent directory entries enhanced by the specifications in the corresponding object descriptions. If no object description can be mapped, a generic object description is created. We recommend that you provide well-designed object descriptions for all objects.

  • A selector may comprise several entry clauses. Their order is significant if they refer to the same storage object. In this case, the first entry clause "wins". Subsequent entry clauses often appear not to match anything produced by the producer. This may make sense under the following conditions:

    • If a previous entry clause uses a reference clause, as it does in the example. This causes the references to be resolved, as far as matching entry clauses are there.

    • If a previous entry clause uses a child clause. This causes all one-level sub-entries to be resolved, as far as matching entry clauses are there.

    entry clauses only make sense if reference or child clauses in previous entry clauses are present.

  • Values can be specified as comma-separated lists. An asterisk (*) can be used as a wild card.

  • The property in a match clause such as "<entry><match><property name="$odname" value="dxrUser" /></match>…​" can use any attribute name as reported in the XML report. For example, if an XML report contains the following snippet:

    ...
<attr name="dxrState" ><value>ENABLED</value></attr>
...

    you can specify "<entry><match><property name="dxrState" value="ENABLED" /></match>…​" (which means that all produced entries whose dxrState attribute has the value ENABLED will be selected). Or you can specify "<entry><match><property name="dxrState" value="*" /></match>…​" (which means that all produced entries whose dxrState attribute has any non-empty value will be selected).

Transformer Element

A transformer processes the data from the selector into an output format to be processed by the consumer. The section "Report Format Tab" provides more information about this attribute.

DirX Identity provides the following transformers:

  • XMLWriter - use this transformer to determine the data and the data format that the selector provides. This transformer operates on the pure XML-formatted output generated by the selector.

  • XSLTWriter - use this transformer to process XSL transformations (XSLT). The programming languages used in this transformer are XSLT and XML Path (Xpath).

  • ScriptWriter - use this transformer to write a custom transformer in JavaScript. Using this transformer implies programming internal, unpublished interfaces. Its use is therefore rather limited.

XSL transformation features include:

  • Support of the import element to structure report definitions

  • Structuring through a variable concept (to separate configuration)

  • Structuring through XSLT subroutines with parameters

Consumer Element

A consumer defines the output to files or to a simple viewer. Output formats include XML, RAW, HTML, and TXT. The section "Output Formats" provides more information about these output types. DirX Identity currently provides one consumer: DefaultConsumer.

Status Report Format Tab

A status report’s Format tab stores the transformations for the report. Note that XSL transformations are case-sensitive. If in doubt, look at the XML output to see what is upper and what is lowercase.

The following explanations are based on the reports provided with DirX Identity. These reports use include/import mechanisms to better structure the reports, to allow re-using identical parts in different reports and to isolate settings in separate directory objects. Note that a special type of setting (the producer-related settings) has - for technical reasons - been isolated into its own file that is not included here but is imported (using include rather than import would work, too) within the attribute dxrConfig; for details see the "Producer Element" section).

Start with the last include element in the format definition shown in the following figure. It is an XSL transformation that is based on the data the plain XML report reveals and calls miscellaneous templates that must be included in one of the include elements shown in the figure.

Example Format Definition
Figure 5. Example Format Definition

The following figure shows an excerpt of an XSL template definition for a user report. It singles out all objects with their properties whose type is dxrUser and calls a template ("EntryTitleNCols") that creates a title for each user object. The template that follows ("RowHeaderNCols") creates another title for the first block of data ("General"). The last template shown in this figure outputs the user’s common name and first name. All these templates must be found in one of the objects included in the "Example Format Definition" figure.

Example User Report XSL Template Definition
Figure 6. Example User Report XSL Template Definition

Status Report Output Formats

The output format definition in a status report object description includes the transformer- and the consumer-related settings:

<output format, for example, HTML enable="true">
<transformer> ... </transformer>
<FILE><consumer>...</consumer></FILE>
</same output format as above>

Although DirX Identity does not restrict the types of output formats, HTML and TXT are the most common formats. XML is a type of transparent auxiliary format that helps to build the really useful output formats. There is another format called "RAW". By default, it does pretty much the same as the output format XML. It can however be customized, since it is implemented based on XSL transformations (found in the xslFile property) rather than a Java class.

XML Output Format

XML format generally corresponds to the output of the selector and therefore serves as a source of information for the XSL transformations carried out for other formats. Here is an example of an XML format:

<XML enable="true">
  <transformer class="siemens.dxm.storage.report.XMLWriter"/>
  <FILE>
    <consumer class="siemens.dxm.storage.report.DefaultConsumer">
      <property name="file" value="RoleXMLReport.xml"/>
      <property name="contenttype" value="text/plain"/>
      <property name="includeTimestamp" value="true"/>
      <property name="timestampFormat" value="yyMMddHHmmss"/>
    </consumer>
  </FILE>
</XML>

With regard to the preceding example:

  • Setting enable to "false" prevents the format from being selectable when running a report. The enable keyword can be omitted, its default value is "true".

  • RoleXMLReport.xml is the default file name. You can choose a different one when running a report. You can also have the XML output be displayed in a viewer instead of storing it in a file.

  • If enabled, the property includeTimestamp adds a timestamp in the default format yyMMddHHmmss to the configured file name. The default format can be redefined using property timestampFormat. You can use any format that can be correctly used for the common Java class java.text.SimpleDateFormat. (See the Java documentation for more details.) Be aware of timestamp formats which can collide with restrictions of the file system you are using. Any configured format using forbidden characters might cause creation of an invalid file name for the selected report object.

HTML Output Format

HTML is the preferred format of the reports provided with DirX Identity. Here is an example of an HTML format:

<HTML enable="true">
  <transformer class="siemens.dxm.storage.report.XSLTWriter">
    <property name="xslFile" value="storage://DirXmetaRole/$(.)?content=dxrFormat" />
    <property name="segmentSize" value="100" />
  </transformer>
  <FILE>
    <consumer class="siemens.dxm.storage.report.DefaultConsumer">
      <property name="file" value="RoleHTMLReport.html"/>
      <property name="contenttype" value="text/html" />
      <property name="includeTimestamp" value="true"/>
      <property name="timestampFormat" value="yyMMddHHmmss"/>
    </consumer>
  </FILE>
</HTML>

Regarding the preceding example:

  • Setting enable to "false" prevents the format from being selectable when running a report. The enable keyword can be omitted; its default value is "true".

  • storage://DirXmetaRole/$(.)?content=dxrFormat specifies that the XSL transformation is to be found in the attribute dxrFormat.

  • RoleHTMLReport.xml is the default file name. You can choose a different one when running a report. You can also have the HTML output be displayed in a viewer instead of storing it in a file (for test purposes).

  • You can set a limit on the size of the output file with the segmentSize keyword. The clause: <property name="segmentSize" value="100"/> shown in the example specifies that an output file must not contain more than 100 objects that match the first entry clause of the selector. The first 100 objects (including their relationships, if specified) will be stored in the file name specified in the consumer section. The segments that follow are stored in a file of the same name with an additional ascending suffix that starts with "1"; for example, *.1.html instead of *.html, and so on. For HTML files, you are supposed to be offered to navigate between the files within your browser.

  • Additionally, you can use the properties includeTimestamp and timestampFormat to add timestamps to the report file names automatically. See the section "XML Output Format" for details.

Other Output Formats

Some DirX Identity reports use TXT or CSV format. Its definition differs from the HTML format definition only by the initial clause "<TXT>" …​ "</TXT>" or "<CSV>" …​ "<CSV>" which replaces "<HTML>" …​ "</HTML>".

Customizing Provisioning Status Reports

This chapter provides information specific to customizing provisioning status reports, including:

  • Status report locations

  • Virtual objects and attributes

  • Graphical reports

Locating Provisioning Reports

DirX Identity Manager’s Auditing view provides a virtual view of the collection of Provisioning status reports that exist in various locations in the Provisioning configuration. In this view, the Status Reports tree contains two sub-trees: Default and Customer Specific. The Default sub-tree contains the default Provisioning status reports, while the Customer Specific sub-tree is intended to store status reports that you, the customer, create. Do not change a default report within the Default sub-tree! New releases of DirX Identity will overwrite your changes. Instead, copy a default report to the Customer Specific sub-tree and modify it there. You can also right-click in this tree and create your own reports from scratch.

The Customer-Specific tree contains the sub-tree Target Systems Instances. This tree is a virtual view into the target system-specific status reports contained in Target Systems → target_system → Configuration → Reports, where target_system represents a particular system, for example, SAP R3 or Intranet Portal. You can work with target systems status reports in the virtual view or work directly in the target system’s Configuration → Reports view.

Virtual Objects and Attributes

You can use the whole set of attributes that are defined for an object via the related object description. This includes all custom attributes defined in your specific project. Additionally you can use a set of virtual attributes available for convenience. These attributes represent properties that do not exist directly in the underlying LDAP repository. Their calculation might require access to a set of LDAP attributes and deep knowledge of the calculation algorithm. Such attributes are displayed in the DirX Identity Manager or DirX Identity Web Center. Using them in reports guarantees consistent display. Changes and extensions in the calculation algorithms do not require report adaption.

The following section lists and explains the virtual attributes of the most important objects.

User (dxrUser) - represents the basic user object.

  • Roles.Assigned - contains all roles assigned to a user.

    • The assignment attributes for a role assignment are:

    • assign.dxrStartDate - the start date of the assignment.

    • assign.dxrEndDate - the end date of the assignment.

    • assign.dxrNeedsReapproval - the reapproval flag

    • assign.dxrRoleParamValue - the role parameters

    • assign.mode - mode of assignment (manual, rule, …​)

    • assign.displayState - state of the assignment

  • UserPermissions.Assigned - contains all permissions assigned to a user.

    • The assignment attributes for a permission assignment are:

    • assign.dxrStartDate - the start date of the assignment.

    • assign.dxrEndDate - the end date of the assignment.

    • assign.dxrNeedsReapproval - the reapproval flag

    • assign.mode - mode of assignment (manual, rule, …​)

    • assign.displayState - state of the assignment

  • Groups.Assigned - contains all groups assigned to a user.

    • The assignment attributes for a group assignment are:

    • assign.dxrStartDate - the start date of the assignment.

    • assign.dxrEndDate - the end date of the assignment.

    • assign.dxrNeedsReapproval - the reapproval flag

    • assign.mode - mode of assignment (manual, rule, …​)

    • assign.displayState - state of the assignment

  • Accounts.Assigned - contains all accounts assigned to a user.

    • assign.state - state of the assignment

  • subjectmodifyorders - list of orders for object modification with these properties:

    • duedate

    • attribute

    • oldvalues

    • newvalues

  • resourceorders - list of orders for resources with these properties:

    • $mergegroup - a pseudo property that defines the rows that could be merged in a table

    • operation

    • duedate

    • resourcetype

    • privilege

    • attribute

    • oldvalues

    • newvalues

    • mode

  • sodexceptions - all granted SoD exceptions for this user with these properties:

    • policy.cn

    • dxracceptedsodviolationslink

    • activityid

    • reason

    • who

    • when

  • sodviolations - all pending SoD violations with these properties:

    • policyname

    • privilege

  • allactivedelegations.assigned - all active delegation assignments for the user with these properties:

    • dxrName

    • description

    • dxrAssignFrom@cn

    • dxrAssignFrom@ou

    • dxrStartDate

    • dxrEndDate

    • dxrPreventDelegation

  • gotdelegations.assigned - all delegations for a user (active and inactive ones) with these properties:

    • dxrName

    • description

    • dxrAssignFrom@cn

    • dxrAssignFrom@ou

    • dxrStartDate

    • dxrEndDate

    • dxrPreventDelegation

  • granteddelegations.assigned - all delegations this user has delegated to other users with these properties:

    • dxrName

    • description

    • dxrAssignFrom@cn

    • dxrAssignFrom@ou

    • dxrStartDate

    • dxrEndDate

    • dxrPreventDelegation

  • delegateabledelegations.assigned - all delegations a user could delegate to other users with these properties:

    • dxrName

    • description

    • dxrAssignFrom@cn

    • dxrAssignFrom@ou

    • dxrStartDate

    • dxrEndDate

Roles (dxrRole) - represents the role object.

  • Roles.Assigned - contains all assigned junior roles (lower hierarchy level).

  • Permissions.Assigned - contains all assigned permissions.

  • seniorroles - contains all assigned senior roles (higher hierarchy level).

  • affectedUsers - contains all assigned users. Note: this list can be very long for specific roles. Display of this property can result in poor performance or memory problems.

Permissions (dxrPermission) - represents the permission object.

  • Matchrules - the match rules with these properties:

    • AndOr

    • UserAttribute

    • Operator

    • Object

    • Value

  • Groups.Assigned - contains all assigned groups.

Group (dxrTargetSystemGroup) - represents the target system group object.

  • Permissions - all permissions that use this group.

  • memberAccounts - all accounts that are assigned to this group.

  • remoteMembers - members of this group that do not have an account.

  • Groups.memberOf - all groups this group is a member of.

Account (dxrTargetSystemAccount) - represents the target system account object.

  • Groups.Assigned - groups assigned to an account.

About Graphical Status Reports

In DirX Identity’s Provisioning view, users, roles, permissions, groups, target systems etc. are connected by various relationships. DirX Identity Manager is currently unable to represent these relationships in a graphical way. However, the report mechanism of both Manager and the DirX Identity report agent can be used to generate output format that can be interpreted by visualization tools.

DirX Identity provides a set of standard reports that generate output in GVF (Graph Visualization Framework) format. A trailing _GVF in a DirX Identity report name indicates that it generates output in GVF format.

For more information on the GVF visualization tool, see

http://gvf.sourceforge.net/

and

http://www.cwi.nl/InfoVisu/

Customizing Connectivity Status Reports

This section provides information specific to customizing connectivity status reports, including information about:

  • Locating the connectivity status reports

  • Types of connectivity status reports

  • XSL template definitions for the connectivity status reports

Locating Connectivity Reports

The pre-configured Connectivity "template" reports provided with DirX Identity cover the important Connectivity objects and their relationships: scenarios, schedules, workflows, jobs, channels and connected directories - including sub-elements, for example, Tcl scripts and INI files. The reports produce a complete list of these objects and their direct assignments in the domain together with the set of attributes describing them.

currently the default reports do not cover samples for Java-based workflows.

Using DirX Identity Manager’s Connectivity view, you can find the Connectivity reports in Status Reports → Default. You can also find them in the Expert View under Configuration → GUI → Reports → Default. The following figure illustrates the relationships between the Connectivity report objects in the Default subdirectory.

Default Connectivity Report Structure
Figure 7. Default Connectivity Report Structure

The Common folder contains the XSLT template definitions required by the default DirX Identity Connectivity reports. Any report can use the GlobalNamedTemplates and the GeneralMatchObj XSLT routines.

Types of Connectivity Reports

There are two basic types of Connectivity reports. The Generic report creates information about almost any object in the configuration database in a generic table format. The other reports produce the requested information in format that is similar to the object representation at the user interface level (DirX Identity Manager and Web Center).

  • Configuration - you can use this report either at the Connectivity Configuration Data root object or at Configuration. It produces:

    • The root object itself

    • The (central) configuration object

    • All C++based Server objects

    • All Service objects

    • All System objects

  • Scenario - available only at the Scenario folder or objects. It produces:

    • All scenario objects contained in the folder (if a folder was selected) or the selected scenario object

    • The contained workflows and activities

    • The related jobs and sub-objects (configuration files, notification objects)

    • The contained connected directories, sub-objects and channels

  • Schedule - use this report either on Schedule folders or objects. It produces:

    • All schedule objects contained in the folder (if a folder was selected) or the schedule object

    • The contained workflows and activities

    • The related jobs and sub-objects (configuration files, notification objects)

    • The contained connected directories, sub-objects and channels

  • Workflows - available only on Workflow folders or objects. It produces:

    • All workflow objects contained in the folder (if a folder was selected) or the workflow and its activities

    • The related jobs and sub-objects (configuration files, notification objects)

    • The contained connected directories, sub-objects and channels

  • Jobs - use this report on Job folders or objects. It produces:

    • All job objects contained in the folder (if a folder was selected) or the related jobs and sub-objects (configuration files, notification objects)

    • The contained connected directories, sub-objects and channels

  • ConnDirs - use this report on Connected Directory folders or objects. It produces:

    • All connected directory objects contained in the folder (if a folder was selected) or the selected connected directory object

This report currently does not contain channels.
Reports can be very resource-consuming. Do not try to produce too much data at one time. If you run into problems, try to produce several sub-reports instead of one big one. You can also try to reduce the level of detail.

XSL Template Definitions

The XSLT definitions for the DirX Identity Connectivity reports allow you to control display properties and the level of detail for all reports except for the generic report.

GeneralMatchObj.xslt, CdMatchObj.xslt, JobMatchObj.xslt, WorkflowMatchObj.xslt and ScenarioMatchObj.xslt specify the definition of the related objects in a hierarchical way

GlobalNamedTemplates.xslt contains the variables and constants that control display and the level of detail as well as common routines that are used to produce the common representation of the objects. This routine controls all reports except for the generic report.

To control the level of detail, use:

  • DisplayEmpty - defines whether attributes with empty values shall be displayed. Default is false.

  • ConfigFileDisplay - controls whether or not configuration file objects are processed. Default is true.

  • NotifyDisplay - defines whether or not Notify objects are displayed. Default is true.

  • IniTextDisplay - controls INI file text content display. Default is false.

  • TclTextDisplay - displays Tcl file content. Default is false.

  • MapTableDisplay - defines whether or not map tables are displayed. Default is true.

  • SelectedAttributesDisplay - controls the display of selected attributes tables. Default is true.

  • AttributeConfigDisplay - displays attribute configuration tables. Default is false.

To control display behavior, use:

  • textstyle - defines the style of the output text.

  • objcolor - controls the color of object headers.

  • groupcolor - defines the color of group separators.

  • tblheadcolor - sets the color of a table heading.

  • tablecolor - defines the color of the table body.