Customizing Digest and Tag Producers

This chapter describes how to customize the DirX Audit digest producers (also called digest generators) and tag producers (also called dimension generators or tag generators).

DirX Audit supports the generation of digests and tags for the imported audit messages. A digest producer calculates a list of audit events for each audit message. At least one audit event should be produced for an audit message. A tag producer calculates a list of tags both for an audit message and its associated audit events. These lists can be empty.

Digest and tag producers are product-specific: They work on the same format - the audit message - but depend on the content. An additional digest producer and tag producer must be configured for each audit producer (DirX Identity, DirX Access, third party).

By default, the configuration is stored in the following file:

install_path/conf/event-dim-configuration/dgtDimConfig.xml

The next sections describe:

  • The data flow in the DirX Audit Persistence Service Unit

  • How to configure the digest dimension generator

  • How to configure a digest producer

  • How to add a digest producer

  • How to configure a tag producer

  • How to add a tag producer

About Persistence Service Unit Data Flow

Digests and tags are normally generated in the DirX Audit Server during import of audit messages. Digest and tag producers are part of the DirX Audit Persistence Service Unit and are called after the transformation of the original format to the DirX Audit internal standard audit message. The following figure shows the important components in the Persistence Service Unit:

DirX Audit Persistence Service Unit Components
Figure 1. DirX Audit Persistence Service Unit Components

The Persistence Service Unit passes the transformed audit message to the Record Persistence component. First, it stores the audit message in the database (table: DAT_AUDITMESSAGES). Next, it calls the digest producer and next calls the tag producer for each message and stores each digest as an audit event (table: DAT_AUDITEVENTS) and the tags into the tag tables (TAG*) of the database.

The Persistence Service Unit instantiates the digest and tag producers and leverages the Dependency Injection framework Spring (see http://www.springsource.org) for their flexible configuration as Spring beans.

Configuring Producers

Digest producers generate an audit event which is the digest or summary for an audit message. More than one event can be produced for an audit message. Tag producers generate a list of tags either for an audit event or for an audit message.

All of these producers are configured using Spring Bean configuration. The file is named dgtDimConfig.xml and located in the folder install_path/conf/event-dim-configuration/.

The structure of the file is as shown in the following snippet:

  <beans>
    <bean id="DigestDimensionGenerator" …/>
    <bean id="DxiDigestProducer" … />
    <bean id="DxiDigestDimensionProducer" … />
    <bean id="DxiEventDimensionProducer" … />
    <bean id="DxiStandardDimensions" … />
    <bean id="OuDimensionProducer" … />
    <bean id="AssignmentModeDimProducer" … />
    <bean id="AccessDigestProducer" … />
    <bean id="DxaEventDimensionProducer" … />
    <bean id="DxaStandardDimensions" … />
    <bean id="TomcatDigestProducer" … />
    <bean id="TomcatEventDimensionProducer" … />
    <bean id="TomcatStandardDimensions" … />
  </beans>

The next sections describe these beans and their configurators.

Configuring the Digest Dimension Generator

The Persistence Service unit within the DirX Audit Server uses the Spring framework to instantiate the DigestDimensionGenerator, which is the bean that produces the digests and tags for all imported audit messages and events. It contains three maps with the bean references to digest, event dimension and digest dimension - tag - producers. These maps are indexed by the name of the product in lowercase that produces the audit message. The referenced generators are configured as separate <bean> elements. Here is the list of bean properties that hold these maps:

  • digestProducers - a map with all digest (event) producers indexed by the audit producer name as contained in the audit message.

  • digestDimensionProducers - a map with all tag producers for an audit event indexed by the audit producer name as contained in the audit message.

  • eventDimensionProducers - a map with all tag producers for an audit message indexed by the audit producer name as contained in the audit message.

Here is the snippet with the default configuration for the bean DigestDimensionGenerator:

  <bean id="DigestDimensionGenerator"
        class="com.DigestDimensionGeneratorImpl"
        scope="prototype">
    <property name="digestProducers">
      <map>
        <entry key="dirx identity">
          <ref bean="DxiDigestProducer" />
        </entry>
        <entry key="dirx access">
          <ref bean="AccessDigestProducer" />
        </entry>
        <entry key="tomcat">
          <ref bean="TomcatDigestProducer" />
        </entry>
      </map>
    </property>
    <property name="digestDimensionProducers">
      <map>
        <entry key="dirx identity">
          <ref bean="DxiDigestDimensionProducer" />
        </entry>
      </map>
    </property>
    <property name="eventDimensionProducers">
      <map>
        <entry key="dirx identity">
          <ref bean="DxiEventDimensionProducer" />
        </entry>
        <entry key="dirx access">
          <ref bean="DxaEventDimensionProducer" />
        </entry>
        <entry key="tomcat">
          <ref bean="TomcatEventDimensionProducer" />
        </entry>
      </map>
    </property>
  </bean>

Configuring a Digest Producer

You need to configure a digest (event) producer bean for each supported source product. For DirX Identity, this is the bean with the name DxiDigestProducer. For DirX Access, it is the bean AccessDigestProducer. You can simply stay with the default configuration that is shown in the next snippet for the DirX Identity digest producer:

  <bean id="DxiDigestProducer"
    class="com.DxiDigestProducerImpl"
    scope="prototype">
  </bean>

The configuration of the digest producer for DirX Access is similar.

Adding a Digest Producer

To support a third-party audit producer, you need to add a digest producer into the configuration.

First, you implement the producer as a Java bean and then deploy it; see the section "Implementing a Digest Producer" in the chapter "Collecting Audit Messages from Third-party Applications" in this guide.

Next, add this bean to the <digestProducers> map of the digest dimension generator, for example:

  <bean id="DigestDimensionGenerator"> …
    <property name="digestProducers">
      <map>
      …
        <entry key="yourThirdPartyApp">
          <ref bean="YourDigestProducer" />
        </entry>
      </map>
    </property>
  </bean>

The map contains a reference to the bean that configures your digest producer. The key value must match (case insensitive) the name that your application puts into the attribute source of the <identification> element of the audit message.

Finally, add the new bean into the configuration file with the ID you used in the map reference:

  <bean id="YourDigestProducer"
    class="fully_qualified_name_of_YourDigestProducerImpl"
    scope="prototype">
  </bean>

Note that you can add any property definitions into the bean; see the Spring framework definition for more details.

Configuring a Tag Producer

The message and event tag (dimension) producers for DirX Identity are composed of a list of producer beans that is easily extensible. The following snippet shows the configuration of the tag producer for DirX Identity audit messages:

  <bean id="DxiEventDimensionProducer"
      class="com.DxiEventDimensionProducer"
      scope="prototype">
    <property name="producers">
      <list>
        <ref bean="DxiStandardDimensions" />
        <ref bean="OuDimensionProducer" />
      </list>
    </property>
  </bean>

By default, it supports a standard tag producer (named DxiStandardDimensions) and another producer that generates tags for organizational units associated with the active participant (who) or the object (what) of the message. The tags are named WHO_OU and WHAT_OU respectively. This producer looks for the identifying attribute of the active participant or the object that describes the organizational unit. As this attribute name depends on the configuration of the corresponding audit policy in DirX Identity, the property for the attribute name identifierType is configurable and must be adapted to the project settings:

   <bean id="OuDimensionProducer"
        class="com.OuDimensionProducer"
        scope="prototype">
      <property name="identifierType"
        value="Organizational Unit"/>
  </bean>

For example, suppose you change the label in the DirX Identity audit policy to OU. As a result, you need to adapt the value in the bean configuration as follows:

  <property name="identifierType"
    value="OU"/>

Adding a Tag Producer

If you want to add a tag producer for generating additional tags or tags for a third-party application, you need to:

  • Implement the producer as a Java class and deploy it; see the section "Implementing a Tag Producer" in the chapter "Collecting Audit Messages from Third-party Applications" in this guide.

  • Configure a bean for your producer.

  • Enter a reference to your bean into the appropriate tag producer.

First, configure the bean for your tag producer:

  <bean id="YourTagProducer"
        class="fully_qualified_name_of_YourTagProducerImpl"
        scope="prototype">
  </bean>

Use <property> child elements to configure any properties of your class; see the previous sections in this chapter for examples.

Next, add your tag producer bean to the appropriate product tag producer. For DirX Identity, this is either the DxiEventDimensionProducer for tags applicable to audit messages or DxiDigestDimensionProducer for tags applicable to digests ~ audit events.

The following example shows the insertion into the digest tag producer (see the element in italics):

  <bean id="DxiDigestDimensionProducer"
        class="com.DxiDigestDimensionProducer"
        scope="prototype">
    <property name="producers">
      <list>
        <ref bean="DxiStandardDimensions"/>
        <ref bean="AssignmentModeDimProducer"/>
        <ref bean="YourTagProducer"/>
      </list>
    </property>
  </bean>

If you want to add the tag producer for a third-party application, you need to add a reference to your bean into the map digestDimensionProducers or eventDimensionProducers of the DigestDimensionGenerator bean (see the section "Configuring the Digest Dimension Generator"). Here is an example for the eventDimensionProducers map:

  <bean id="DigestDimensionGenerator"> …
    <property name="digestDimensionProducers">
      <map>
      …
        <entry key="yourThirdPartyApp">
          <ref bean="YourTagProducer" />
        </entry>
      </map>
    </property>
  </bean>