Sun[TM] Identity Manager 8.0 Administration |
Chapter 10
Audit LoggingThis chapter describes how the auditing system records events.
This chapter is organized into the following sections:
OverviewThe purpose of Identity Manager auditing is to record who did what to which Identity Manager objects, and when did they do it.
Audit events are handled by one or more publishers. By default, Identity Manager records audit events in the repository using the repository publisher. Filtering, with the help of audit groups, allows the administrator to select a subset of audit events for recording. Each publisher can be assigned one or more audit groups that are enabled initially.
Note
For information about monitoring and managing user violations, see Chapter 13, "Identity Auditing: Basic Concepts."
What Does Identity Manager Audit?Most default auditing is carried out by internal Identity Manager components. There are, however, interfaces that allow events to be generated from workflows or from Java code.
The default Identity Manager audit instrumentation focuses on four main areas:
- Provisioner – An internal component known as the provisioner may generate audit events.
- View Handlers – In the view architecture, the view handler generates audit records. A view handler should always audit when objects are created or modified.
- Session – The session methods (such as checkinObject, createObject, runTask, login, and logout) create an audit record after completing an auditable operation. Most of the instrumentation is pushed into the view handlers.
- Workflow – By default, only the approval workflows are instrumented to generate audit records. These generate an audit event when requests are approved or rejected. The workflow feature’s interface to the audit logger is through the com.waveset.session.WorkflowServices application. See the next section for more information.
Creating Audit Events From WorkflowsBy default, only the approval workflows are instrumented to generate audit records. This section describes how to use the com.waveset.session.WorkflowServices application to generate extra audit events from any workflow process.
Additional audit events may be required if you need to report on custom workflows. See Modifying Workflows to Log Standard Audit Events for information on adding audit events to workflows.
Special audit events can also be added to workflows in support of Workflow Reports ((more...) ). Workflow Reports report the amount of time it takes for workflows to complete. Special audit events are required to store the data necessary for time computations. See Modifying Workflows to Log Timing Audit Events for information on adding timing audit events to workflows.
The com.waveset.session.WorkflowServices Application
The com.waveset.session.WorkflowServices application generates audit events from any workflow process. Table 10-1 describes the arguments that are available for this application.
Table 10-1 Arguments for com.waveset.session.WorkflowServices
Argument
Type
Description
op
String
Operation for WorkflowServices. Must be set to audit or auditWorkflow. Use audit for standard workflow auditing. Use auditWorkflow to store timing audit events required for time computations. Required.
type
String
Name of the object type that is being audited. Auditable object types are listed in Table B-5. Required to log standard audit events.
action
String
Name of the action performed. Auditable actions are listed in Table B-6. Required.
status
String
Name of the status for the specified action. Status is listed in Table B-7 (in the Results column). Required to log standard audit events.
name
String
Name of the object being affected by the specified action. Required to log standard audit events.
resource
String
(Optional) Name of the resource where the object being changed resides.
accountId
String
(Optional) Account ID that is being modified.
This should be a native resource account name.error
String
(Optional) Localized error string to accompany any failures.
reason
String
(Optional) Name of the ReasonDenied object, which maps to an internationalized message describing the causes of common failures.
attributes
Map
(Optional) Map of attribute names and values that were added or modified.
parameters
Map
(Optional) Maps up to five additional names or values that are relevant to an event.
organizations
List
(Optional) List of organization names or IDs where this event will be placed. This is used for organizational scoping of the audit log. If not present, the handler will attempt to resolve the organization based on the type and name. If the organization cannot be resolved, the event is placed in Top (the highest level of the organizations hierarchy).
originalAttributes
Map
(Optional) Map of old attribute values. The names should match the ones listed in the attributes argument. The values will be any previous value you wish to save in your audit log.
Modifying Workflows to Log Standard Audit Events
To create a standard audit event in a workflow, add the following <Activity> element to the workflow:
<Activity name='createEvent'>
Next, nested in the <Activity> element, include an <Action> element that references the com.waveset.session.WorkflowServices application:
<Action class='com.waveset.session.WorkflowServices'>
Nested in the <Action> element, include the required and optional <Argument> elements. See Table 10-1 for a list of the arguments.
To log standard audit events, the op argument must be set to audit.
Code Example 10-1 shows the minimum code required to create a standard audit event.
Examples
Code Example 10-1 illustrates a simple workflow activity. It shows the generation of an event that will log a resource deletion activity named ADSIResource1, performed by ResourceAdministrator:
Code Example 10-2 shows how you can add specific attributes to a workflow that tracks the changes applied by each user in an approval process to a granular level. This addition typically will follow a ManualAction that solicits input from a user.
ACTUAL_APPROVER is set in the form and in the workflow (if approving from the approvals table) based on the person who actually performed the approval. APPROVER identifies the person to whom it was assigned.
Code Example 10-2 Attributes Added to Track Changes in an Approval Process
(Page 1 of 2)
<Action name='Audit the Approval' application='com.waveset.session.WorkflowServices'>
<Argument name='op' value='audit'/>
<Argument name='type' value='User'/>
<Argument name='name' value='$(CUSTOM_DESCRIPTION)'/>
<Argument name='action' value='approve'/>
<Argument name='accountId' value='$(accountId)'/>
<Argument name='status' value='success'/>
<Argument name='resource' value='$(RESOURCE_IF_APPLICABLE)'/>
<Argument name='loginApplication' value='$(loginApplication)'/>
<Argument name='attributes'>
<map>
<s>fullname</s><ref>user.accounts[Lighthouse].fullname</ref>
<s>jobTitle</s><ref>user.accounts[Lighthouse].jobTitle</ref>
<s>location</s><ref>user.accounts[Lighthouse].location</ref>
<s>team</s><ref>user.waveset.organization</ref>
<s>agency</s><ref>user.accounts[Lighthouse].agency</ref>
</map>
</Argument>
<Argument name='originalAttributes'>
<map>
<s>fullname</s>
<s>User's previous fullname</s>
<s>jobTitle</s>
<s>User's previous job title</s>
<s>location</s>
<s>User's previous location</s>
<s>team</s>
<s>User's previous team</s>
<s>agency</s>
<s>User's previous agency</s>
</map>
</Argument>
<Argument name='attributes'>
<map>
<s>firstname</s>
<s>Joe</s>
<s>lastname</s>
<s>New</s>
</map>
</Argument>
<Argument name='subject'>
<or>
<ref>ACTUAL_APPROVER</ref>
<ref>APPROVER</ref>
</or>
</Argument>
<Argument name='approver' value='$(APPROVER)'/>
</Action>
Modifying Workflows to Log Timing Audit Events
Workflows can be modified to log timing events in support of Workflow Reports ((more...) ). Standard audit events only log that an event occurred; Timing audit events log when an event started and stopped, making it possible to perform time computations. In addition to timing event data, most of the information logged by standard audit events is also stored. See What Information Do Timing Audit Events Store? for more information.
Note
In order to log timing audit events, you must first activate workflow auditing for each workflow type that you plan to audit.
- For workflows that you can configure in the Administrator interface using task templates, first enable the task template that corresponds to the workflow that you want to audit. See Enabling the Task Templates for instructions.
Next, turn on workflow auditing by selecting the Audit entire workflow checkbox. See Configuring the Audit Tab for instructions.
Note that auditing workflows degrades performance.
Code Example 10-3 shows the code required to create timing audit events. To log timing audit events, the op argument must be set to auditWorkflow.
The action argument is also required and must be set to one of the following values:
Additional action arguments may be defined in auditconfig.xml.
Examples
Code Example 10-3 illustrates enabling timing audit events in a workflow. To instrument a workflow, auditWorkflow events should be added at the beginning and end of workflows, processes, and activities.
The auditWorkflow operation is defined in com.waveset.session.WorkflowServices. See (more...) for more information.
Code Example 10-3 Starting Timing Audit Events in a Workflow
<Action application='com.waveset.session.WorkflowServices'>
<Argument name=’op’ value=’auditWorkflow’/>
<Argument name=’action’ value=’StartWorkflow’/>
</Action>
To stop logging timing audit events in a workflow, add the code in Code Example 10-4 to a pre-end activity near the conclusion of the workflow. Note that, when instrumenting a workflow or process, you are not permitted to put anything in an end activity. You must create a pre-end activity that performs the final auditWorkflow event, and then unconditionally transition to the end event.
Code Example 10-4 Stopping Timing Audit Events in a Workflow
<Action application='com.waveset.session.WorkflowServices'>
<Argument name=’op’ value=’auditWorkflow’/>
<Argument name=’action’ value=’EndWorkflow’/>
</Action>
What Information Do Timing Audit Events Store?
By default, timing audit events log most of the information stored by regular audit events, including the following attributes:
Attribute
Description
WORKFLOW
Name of the workflow being executed
PROCESS
Name of the current process being executed
INSTANCEID
Unique instance ID of the workflow being executed
ACTIVITY
Activity in which the event is being logged
MATCH
Unique identifier within a workflow instance
The above attributes are stored in the logattr table and they come from auditableAttributesList. Identity Manager also checks whether the workflowAuditAttrConds attribute is defined.
It is possible to call some activities several times within a single instance of a process or a workflow. To match the audit events for a particular activity instance, Identity Manager stores a unique identifier within a workflow instance in the logattr table.
To store additional attributes in the logattr table for a workflow, you must define a workflowAuditAttrConds list, which is assumed to be a list of GenericObjects. If you define an attrName attribute within the workflowAuditAttrConds list, Identity Manager pulls attrName out of the object within the code, first using attrName as the key, and then storing the attrName value. All keys and values are stored as uppercase values.
Audit ConfigurationAudit configuration is composed of one or more publishers and several pre-defined groups.
An audit group defines a subset of all audit events based on object types, actions, and action results. Each publisher is assigned one or more audit groups. By default, the repository publisher is assigned to all audit groups.
An audit publisher delivers audit events to a particular audit destination. The default repository publisher writes audit records into the repository. Each audit publisher may have implementation specific options. Audit publishers may have a text formatter assigned. (Text formatters provide textual representation of audit events.)
The Audit Configuration (#ID#Configuration:AuditConfiguration) object is defined in the sample/auditconfig.xml file. This configuration object has an extension that is a generic object. At the top level, it has the following attributes:
filterConfiguration
The filterConfiguration attribute lists event groups, which are used to enable one or more events to pass through the event filter. Each group listed in the filterConfiguration attribute contains the attributes listed in Table 10-2.
Table 10-2 filterConfiguration Attributes
Attribute
Type
Description
groupName
String
Event group name
displayName
String
Message catalog key representing the group name
enabled
String
Boolean flag indicating whether the entire group is enabled or disabled. This attribute is an optimization for the filtering object.
enabledEvents
List
List of generic objects that describe which events a group enables. An event must be listed to enable its logging. Each object listed must have these attributes:
Code Example 10-5 illustrates the default Resource Management group.
Code Example 10-5 Default Resource Management Group
<Object name='Resource Management'>
<Attribute name='enabled' value='true'/>
<Attribute name='displayName'
value='UI_RESOURCE_MGMT_GROUP_DISPLAYNAME'/>
<Attribute name='enabledEvents'>
<List>
<Object>
<Attribute name='objectType' value='Resource'/>
<Attribute name='actions' value='ALL'/>
<Attribute name='results' value='ALL'/>
</Object>
<Object>
<Attribute name='objectType' value='ResourceObject'/>
<Attribute name='actions' value='ALL'/>
<Attribute name='results' value='ALL'/>
</Object>
</List>
</Attribute>
</Object>
Identity Manager provides the following default audit event groups:
You can configure each group from the Audit Configuration page of the Identity Manager Administrator interface (Configure > Audit). See Configuring Audit Groups and Audit Events.
The Audit Configuration page allows you to configure successful or failed events for each group. The interface does not support adding or modifying enabled events for groups, but you can do this by using the Identity Manager debug pages ((more...) ).
The default event groups and the events they enable are described in the following sections.
Account Management
This group is enabled by default.
Table 10-3 Default Account Management Event Groups
Type
Actions
Encryption Key
All Actions
Identity System Account
All Actions
Resource Account
Approve, Change Password, Create, Delete, Disable, Enable, Modify, Reject, Rename, Reset Password, Unlock
Workflow Case
End Activity, End Process, End Workflow, Start Activity, Start Process, Start Workflow
User
Approve, Create, Credentials Expired, Delete, Disable, Enable, Lock, Login, Logout, Modify, Reject, Rename, Unlock, Username Recovery
Changes Outside Identity System
This group is disabled by default.
Table 10-4 Changes Outside Identity Manager Event Groups and Events
Type
Actions
ResourceAccount
NativeChange
Compliance Management
This group is enabled by default.
Table 10-5 Default Compliance Management Group Events
Type
Actions
AuditPolicy
All Actions
AccessScan
All Actions
ComplianceViolation
All Actions
Data Exporter
All Actions
UserEntitlement
Attestor Approved, Attestor Rejected, Remediation Requested, Rescan Requested, Terminate
Access Review Workflow
All Actions
Remediation Workflow
All Actions
Configuration Management
This group is enabled by default.
Table 10-6 Default Configuration Management Event Groups
Type
Actions
Configuration
All Actions
UserForm
All Actions
Rule
All Actions
EmailTemplate
All Actions
LoginConfig
All Actions
Policy
All Actions
XmlData
Import
Log
All Actions
Event Management
This group is enabled by default.
Logins/Logoffs
This group is enabled by default.
Table 10-8 Default Identity Manager Logins/Logoffs Event Groups
Type
Actions
User
Credentials Expired, Lock, Login, Logout, Unlock, Username Recovery
Password Management
This group is enabled by default.
Table 10-9 Default Password Management Event Groups and Events
Type
Actions
Resource Account
Change Password, Reset Password
Resource Management
This group is enabled by default.
Table 10-10 Default Resource Management Event Groups and Events
Type
Actions
Resource
All Actions
Resource Object
All Actions
ResourceForm
All Actions
ResourceAction
All Actions
AttrParse
All Actions
Workflow Case
End Activity, End Process, End Workflow, Start Activity, Start Process, Start Workflow
Role Management
This group is disabled by default.
Security Management
This group is enabled by default.
Table 10-12 Default Security Management Event Groups and Events
Type
Actions
Capability
All Actions
EncryptionKey
All Actions
Organization
All Actions
Admin Role
All Actions
Service Provider Edition
This group is enabled by default.
Table 10-13 Service Provider Event Groups and Events
Type
Actions
Directory User
Challenge Response, Create, Delete, Modify, Post-Operation Callout, Pre-Operation Callout, Update Authentication Answers, Username Recovery
Task Management
This group is disabled by default.
Table 10-14 Task Management Event Groups and Events
Type
Actions
TaskInstance
All Actions
TaskDefinition
All Actions
TaskSchedule
All Actions
TaskResult
All Actions
ProvisioningTask
All Actions
extendedTypes
Each new Type that you add to the com.waveset.object.Type class can be audited. A new Type must be assigned a unique two-character database key, which is stored in the database. All new Types are added to the various audit reporting interfaces. Each new Type to be logged to the database without being filtered must be added to an audit event groups enabledEvents attribute (as described with the enabledEvents attribute).
There may be situations in which you want to audit something that does not have an associated com.waveset.object.Type, or where you want to represent an existing type more granularly.
For example, the WSUser object stores all of the user's account information in the repository. Instead of marking each event as a USER type, the auditing process splits the WSUser object into two different audit types (Resource Account and Identity Manager Account). Splitting the object in this way makes it easier to find specific account information in the audit log.
Add extended audit types by adding to the extendedObjects attribute. Each extended object must have the attributes listed in the following table:
Table 10-15 Extended Object Attributes
Argument
Type
Description
name
String
The name of the type, which is used when constructing AuditEvents and during event filtering.
displayName
String
A message catalog key that represents the name of the type.
logDbKey
String
Two-character database key to use when storing this object in the Log table. See Audit Log Database Mappings for reserved values.
supportedActions
List
Actions supported by the object type. This attribute will be used when creating audit queries from the user interface. If this value is null, all actions will be displayed as possible values to be queried for this object type.
mapsToType
String
(Optional) The name of the com.waveset.object.Type that maps to this type, if applicable. This attribute is used when attempting to resolve an object organizational membership if not already specified on the event.
organizationalMembership
List
(Optional) A default list of organization IDs where events of this type should be placed, if they do not already have assigned organizational membership.
All customer-specific keys should start with the # symbol to prevent duplicate keys when new internal keys are added.
Code Example 10-6 illustrates the extended-type Identity Manager Account.
Code Example 10-6 Extended Type Identity Manager Account (Page 1 of 2)
<Object name='LighthouseAccount'>
<Attribute name='displayName' value='LG_LIGHTHOUSE_ACCOUNT'/>
<Attribute name='logDbKey' value='LA'/>
<Attribute name='mapsToType' value='User'/>
<Attribute name='supportedActions'>
<List>
<String>Disable</String>
<String>Enable</String>
<String>Create</String>
<String>Modify</String>
<String>Delete</String>
<String>Rename</String>
</List>
</Attribute>
</Object>
extendedActions
Audit actions typically map to com.waveset.security.Right objects. When adding new Right objects, you must specify a unique two-character logDbKey, which will be stored in the database. You may encounter situations where there is no right to correspond to a particular action that must be audited. You can extend actions by adding them to the list of objects in the extendedActions attribute.
Each extendedActions object must include the attributes listed in Table 10-16.
Table 10-16 extendedAction Attributes
Attribute
Type
Description
name
String
The name of the action, which is used when constructing AuditEvents and during event filtering.
displayName
String
A message catalog key that represents the name of the action.
logDbKey
String
Two-character database key to use when storing this action in the Log table.
See Audit Log Database Mappings for reserved values.
All customer-specific keys should start with the # symbol to prevent duplicate keys when new internal keys are added.
Code Example 10-7 illustrates adding an action for Logout.
Code Example 10-7 Adding an Action for Logout
<Object name='Logout'>
<Attribute name='displayName' value='LG_LOGOUT'/>
<Attribute name='logDbKey' value='LO'/>
</Object>
extendedResults
In addition to extending audit types and actions, you can add results. By default, there are two results: Success and Failure. You can extend results by adding them to the list of objects in the extendedResults attribute.
Each extendedResults object must include the attributes described in Table 10-17.
Table 10-17 extendedResults Attributes
Attribute
Type
Description
name
String
The name of the result, which is used when setting the status on AuditEvents and during event filtering.
displayName
String
A message catalog key that represents the name of a result.
logDbKey
String
One-character database key to use when storing this result in the Log table. See the section titled Database Keys for reserved values.
All customer-specific keys should use the range 0–9 to prevent duplicate keys when new internal keys are added.
publishers
Each item in the publishers list is a generic object. Each publisher has the following attributes:
Table 10-18 publishers Attributes
Attribute
Type
Description
class
String
The name of the publisher class.
displayName
String
A message catalog key that represents the name of the publisher.
description
String
A description of the publisher.
filters
List
A list of audit groups assigned to this publisher.
formatter
String
The name of the text formatter (if any).
options
List
A list of publisher options. These options are publisher specific; each item in the list is a map representation of PublisherOption. See sample/auditconfig.xml for examples.
Database SchemaThere are two tables in the Identity Manager repository that are used to store audit data:
These tables are discussed first in this section.
When audit log data exceeds the column length limit(s) specified for the above tables, Identity Manager truncates the data to fit. Audit log truncation is discussed on (more...) .
A few columns in the audit log have configurable column length limits. To find out about these columns and learn how to change their length limits, see Audit Log Configuration.
waveset.log
This section lists the various column names and data types found in the waveset.log table. The data types are taken from the Oracle database definition and will vary slightly from database to database. For a list of data schema values for all supported databases, see Appendix B, "Audit Log Database Schema."
A few of the column values are stored as keys in the database for space optimization. For key definitions, see the section titled Audit Log Database Mappings.
- objectType CHAR(2) – A two-character key that represents the object type that is being audited.
- action CHAR(2) – A two-character key that represents the action that was performed.
- actionStatus CHAR(1) – A one-character key that represents the result of the action that was performed.
- reason CHAR(2) – A two-character database key to describe a ReasonDenied object if there was a failure. ReasonDenied is a class that wraps a message catalog entry and is used for common failures such as invalid credentials and insufficient privileges.
- actionDateTime VARCHAR(21) – The date and time in which the above action took place. This value is stored in GMT time.
- objectName VARCHAR(128) – The name of the object that was acted on during an operation.
- resourceName VARCHAR(128) – The resource name that was used during an operation, if applicable. Some events do not reference resources; however, in many situations it gives greater detail to log the resource where an operation has performed.
- accountName VARCHAR(255) – The account ID being acted on, if applicable.
- server VARCHAR(128) – The server where the action was performed (automatically assigned by the event logger).
- message VARCHAR(255*) or CLOB – Any localized messages associated with an action including things like error messages. The text is stored localized so it will not be internationalized. The column length limit for this column is configurable. The default data type is VARCHAR and the default size limit is 255. See Audit Log Configuration for information on how to adjust the size limit.
- interface VARCHAR(50) – The Identity Manager interface (such as the Administrator, User, IVR, or SOAP interface) from which the operation was performed.
- acctAttrChanges VARCHAR(4000) – Stores the account attributes that have changed during a create and update. The attributes changes field is always populated during a create or update for a resource account or Identity Manager account object. All of the attributes changed during an action are stored in this field as a string. The data is in NAME=VALUE NAME2=VALUE2 format. This field can be queried by executing “contains” SQL statements against the name or value.
Code Example 10-8 illustrates a value in the acctAttrChanges column:
Code Example 10-8 Value in acctAttrChanges Column
COMPANY="COMPANY" DEPARTMENT="DEPT" DESCRIPTION="DSMITH
DESCRIPTION" FAX NUMBER="5122222222" HOME ADDRESS="12282
MOCKINGBIRD LANE" HOME CITY="AUSTIN" HOME PHONE="5122495555"
HOME STATE="TX" HOME ZIP="78729" JOB TITLE="DEVELOPER"
MOBILE PHONE="5125551212" WORK PHONE="5126855555"
EMAIL="someone@somecompany.COM" EXPIREPASSWORD="TRUE"
FIRSTNAME="DANIEL" FULLNAME="DANIEL SMITH" LASTNAME="SMITH"
- acctAttr01label-acctAttr05label VARCHAR(50) – These five additional NAME slots are columns that can promote up to five attribute names to be stored in their own column instead of in the big blob. You can promote an attribute from the Resource Schema Configuration page using the "audit?" setting, and the attribute will be available for data mining.
- acctAttr01value-acctAttr05value VARCHAR(128) – Five additional VALUE slots that can promote up to five attribute values to be stored in a separate column instead of in the blob column.
- parm01label-parm05label VARCHAR(50) – Five slots used to store parameters associated with an event. Examples of these are Client IP and Session ID names.
- parm01value-parm05value VARCHAR(128*) or CLOB – Five slots used to store parameters associated with an event. Examples of these are Client IP and Session ID values. The column length limit for these columns is configurable. The default data type is VARCHAR and the default size limit is 128. See Audit Log Configuration for information on how to adjust the size limit.
- id VARCHAR(50) – Unique ID assigned to each record by the repository referenced in the waveset.logattr table.
- name VARCHAR(128) – Generated name assigned to each record.
- xmlBLOB– Used internally by Identity Manager.
waveset.logattr
The waveset.logattr table is used to store IDs of the organizational membership for each event, which is used to scope the audit log by organization.
Audit Log Truncation
When one or more columns of audit log data exceed the specified column length limit(s), the column data is truncated to fit. Specifically, the data is truncated to the specified limit, less three characters. An ellipsis (... ) is then appended to the column data to indicate truncation has occurred.
In addition, the NAME column of that audit record is prepended with the string #TRUNCATED# to facilitate querying of truncated records.
Note
Identity Manager assumes UTF8 encoding when it computes where to truncate messages. If your configuration uses encoding other than UTF8, there is a chance that truncated data may still exceed the actual column size in your database. If this happens, the truncated message does not appear in the audit log and an error is written in the system log.
Audit Log ConfigurationCertain columns in the Audit Log can be configured to store large amounts of data in the repository.
Resizing Column Length Limits
Several columns in the audit log have configurable column length limits. These columns are:
- the message column
- the parmNNvalue columns (where NN = 01, 02, 03, 04, or 05)
- the xml column
Note
For audit log column descriptions see Database Schema.
Column length limits can be changed by editing the RepositoryConfiguration object. For instructions on editing the RepositoryConfiguration object, see Editing Identity Manager Configuration Objects.
- To change the column length limit for the message column, modify the maxLogMessageLength value.
- To change the column length limit for the parmNNvalue column, modify the maxLogParmValueLength value. The same limit value applies to all five columns. (Individual column length values cannot be defined.)
- To change the column length limit for the xml column, modify the maxLogXmlLength value.
A server restart is required in order for the new values to take effect.
The column length limit settings in the RepositoryConfiguration object determine the maximum amount of data that can be stored in a column. If the data to be stored exceeds these settings, Identity Manager truncates the data. See Audit Log Truncation for more information.
If you increase a column length setting in the RepositoryConfiguration object, also verify that the column size setting in your database is at least as large as the size configured in the RepositoryConfiguration object.
Removing Records from the Audit LogThe audit log should be truncated periodically to keep it from growing too large. Use the AuditLog Maintenance Task to remove old records from the audit log.
To schedule a task to remove old records from the audit log, follow these steps:
Preventing Audit Log TamperingYou can configure Identity Manager to prevent the following forms of audit log tampering:
All Identity Manager audit log records have unique, per-server sequence numbers and encrypted hash of records and sequence numbers. When you create a Tamper Detection Report, it scans the audit logs per server for:
Configuring tamper-resistant logging
To configure tamper-resistant logging, follow these steps:
- Create a tampering report by selecting Reports > New > Audit Log Tampering Report.
- When the Define a Tampering Report page displays (see Figure 10-1), enter a title for the report and then Save it.
Figure 10-1 Configuring an Audit Log Tampering Report
You can also specify the following optional parameters:
- Report Summary – Enter a descriptive summary of the report.
- Starting sequence for server '<server_name>' – Enter the starting sequence number for the server.
- This option enables you to delete old log entries without having them flagged as tampering and limits the report’s scope for performance reasons.
- Email Report – Enable to email report results to a specified email address.
- When you select this option, the page refreshes and prompts you for email addresses. However, keep in mind that email is not safe for text content — sensitive information (such as account IDs or account history) may be exposed.
- Override default PDF options – Select to override the default PDF options for this report.
- Organizations – Select organizations that should have access to this report.
- Next, select Configure > Audit to open the Audit Configuration page (shown in Figure 10-2).
Figure 10-2 Tamper-Resistant Audit Logging Configuration
- Select Use Custom Publisher, and then click on the Repository publisher link.
- Select Enable tamper-resistant audit logs, and then click OK.
- Click Save to save the settings.
You can turn this option off again, but unsigned entries will be flagged as such in the Audit Log Tampering Report, and you must reconfigure the report to ignore these entries.
Using Custom Audit PublishersIdentity Manager can submit audit events to custom audit publishers. The following custom publishers are provided:
- Console — Prints audit events to the standard output or standard error.
- File — Writes audit events to a flat file.
- JDBC — Records audit events in a JDBC datastore.
- JMS — Records audit events in a JMS queue or topic.
- JMX — Publishes audit events so that a JMX (Java Management Extensions) client can monitor Identity Manager audit log activity.
- Scripted — Allows for custom scripts to store audit events.
If you want to create your own publisher, see Developing Custom Audit Publishers.
Enabling Custom Audit Publishers
Custom audit publishers are enabled from the Audit Configuration page.
To enable custom audit publishers, follow these steps:
- In the Administrator interface, click Configure in the main menu, then click Audit in the secondary menu.
The Audit Configuration page opens.
- Select the Use custom publisher option at the bottom of the page.
A table opens listing the currently configured audit publishers.
- To configure a new audit publisher, select the custom publisher type from the New Publisher drop-down menu.
Complete the Configure New Audit Publisher form. Click Ok.
- Important! Click Save to save the new audit publisher!
The Console, File, JDBC, & Scripted Publisher Types
To enable the Console, File, JDBC, or Scripted audit publishers, follow the steps in Enabling Custom Audit Publishers. Select the appropriate publisher type from the New Publisher drop-down menu.
Complete the Configure New Audit Publisher form. If you have questions about the form, refer to the i-Helps and online Help.
- The Console audit publisher prints audit events to either standard out or to standard error.
- The File audit publisher writes audit events to a flat file.
- The JDBC audit publisher records audit events in a JDBC datastore.
- The Scripted audit publisher allows custom scripts written in JavaScript or BeanShell to store audit events.
The JMS Publisher Type
The JMS audit log custom publisher makes it possible to publish audit event records to a JMS (Java Message Service) queue or topic.
Why Use JMS?
Publishing to JMS provides additional flexibility for correlation in environments that have multiple Identity Manager servers. In addition, JMS can be used in situations where there are restrictions on using the File audit log publisher, for example in Windows environments where the log may not be accessible to a client reporting tool while the server is running.
JMS offers several benefits for environments with multiple servers:
Point-to-Point or Publish-and-Subscribe?
Java Message System provides two models for messaging: the point-to-point or queuing model, and the publish and subscribe or topic model. Identity Manager supports both models.
In the point-to-point model, a producer posts messages to a particular queue and a consumer reads messages from the queue. Here, the producer knows the destination of the message and posts the message directly to the consumer's queue.
The point-to-point model has the following characteristics:
The publish and subscribe model, on the other hand, supports publishing messages to a particular message topic. Zero or more subscribers may register interest in receiving messages on a particular message topic. In this model, neither the publisher nor the subscriber know about each other. A good metaphor for this model is the anonymous bulletin board.
The publish and subscribe model has the following characteristics:
- Multiple consumers can receive messages.
- A timing dependency exists between publishers and subscribers. The publisher has to create a subscription before clients can subscribe. Once subscribed, subscribers have to remain continuously active to receive messages, unless a durable subscription has been established. In the case of a durable subscription, messages published while the subscriber is not connected will be redistributed when the subscriber reconnects.
Note
For more information about JMS, see http://www.sun.com/software/products/message_queue/index.xml
Configuring the JMS Publisher Type
The JMS publisher formats audit events into JMS TextMessages. These TextMessages are then sent to either a queue or a topic, depending on the configuration. Text messages can be formatted as XML or ULF (Universal Logging Format), depending on configuration.
To enable the JMS publisher type, follow the steps in Enabling Custom Audit Publishers and select JMS from the New Publisher drop-down menu.
To configure the JMS publisher type, complete the Configure New Audit Publisher form. If you have questions about the form, refer to the i-Helps and online Help.
The JMX Publisher Type
The JMX audit log publisher publishes audit events so that a JMX (Java Management Extensions) client can monitor Identity Manager audit log activity.
What is JMX?
Java Management Extensions (JMX) is a Java technology that allows for managing and/or monitoring applications, system objects, devices, and service oriented networks. The managed/monitored entity is represented by objects called MBeans (for Managed Bean).
Identity Manager’s JMX Publisher Implementation
Identity Manager’s JMX audit log publisher monitors the audit log for events. When an event is detected, the JMX publisher wraps the audit event record with an MBean, and also updates a temporary history (which is kept in memory). For each event, a separate small notification is sent to the JMX client. If the event is of interest, the JMX client can query the MBean wrapping the audit event for additional information.
Note
See the com.waveset.object.AuditEvent Javadoc for information about audit event records. The Javadoc is available in the REF kit, which is discussed in Developing Custom Audit Publishers.
In order to retrieve information from the correct MBean, a history sequence number is required. This number is included in the event notification.
Each event notification includes the following information:
- Type — A string describing the type of event. The string follows the format AuditEvent.<ObjectType>.<Action> where ObjectType and Action are returned from com.waveset.AuditEvent. For example, if an unlock event is sent, the type would be AuditEvent.LighthouseAccount.Unlock.
- SequenceNumber — The history buffer key used to query information from the MBean.
Configuring the JMX Publisher Type
To configure the JMX publisher type, follow these steps:
- To enable the JMX publisher type, follow the steps in Enabling Custom Audit Publishers and select JMX from the New Publisher drop-down menu.
- To configure the JMX publisher type, complete the Configure New Audit Publisher form. If you have questions about the form, refer to the i-Helps and online Help.
Publisher Name — Type a unique name for the JMX audit event publisher.
History Limit — This is the number of event items that the publish should retain in memory. The default is 100. To change the limit, enter another value.
- Click Test to verify that the Publisher Name is acceptable.
- Click OK. The Configure New Audit Publisher form closes.
- Important! Click Save.
Viewing Audit Events with a JMX Client
Use a JMX client to view the JMX publisher. JConsole, which is included in the JDK 1.5, was used to create the following screen captures.
If using JConsole, choose attach to process to view the IDM:type=AuditLog MBean. For information on configuring JConsole for use as a JMX client, see Viewing JMX Data.
In JConsole, click the Notifications tab to view audit events. Note the sequence number in the notification. A sequence number is required when querying the MBean for additional information.
Figure 10-3 Viewing JMX Audit Event Notifications in JConsole
Querying the MBean for Additional Information
In JConsole, click the Operations tab. Use the sequence number in the notification to query the MBean for event details. Each of the operations are prefixed with 'get' and the only parameter is the 'sequence' number.
Figure 10-4 Querying
the MBean for Additional Information in JConsole
The MBean is virtually a one-to-one mapping to the com.waveset.object.AuditEvent class. Table 10-19 provides a description for each attribute/operation that the MBean provides.
Table 10-19 MBeanInfo attribute/operation descriptions
Attribute / Operation
Description
AccountAttributesBlob
The list of changed attributes
AccountId
AccountId associated with the event
Action
Action taken during the event
AuditableAttributes
The Auditable attributes
ErrorString
Any error string
Interface
The Audit interface
MemberObjectGroupRefs
The member object group references
ObjectName
The object name
ObjectType
The object type
OverflowAttributes
All the overflow attributes
Parameters
All the parameters
Reason
The reason for the event
ResourceName
Resource associated with the event
RoleName
Role associated with the event
SubjectName
User or service associated with the event
Server
Name of the server from which the event fired
Status
Status of the audit event
Timestamp
Date/Time of the audit event
In JConsole, click the Attributes tab. Attributes are prefixed with Current to indicate that the attribute contains the most recent audit event sent to the system.
Figure 10-5 Viewing
MBean Attributes in JConsole
Developing Custom Audit PublishersThis section documents how to create a new custom audit publisher in Java.
The Console, File, and JDBC custom publishers that are provided with Identity Manager implement the AuditLogPublisher interface. The source code of these publishers can be found in the REF kit. The documentation of the interfaces is also available in the REF kit, in Javadoc format. (Refer to the Javadoc for interface details.)
Note
The REF (Resource Extension Facility) kit is provided in the /REF directory on your product CD or with your install image.
Developers are encouraged to extend the AbstractAuditLogPublisher class. This class parses the configuration and ensures that all required options have been provided to the publisher. (See the example publishers in the REF kit.)
Publishers must have a no-arg constructor.
Lifecycle
The following steps describe the lifecycle of a publisher:
Steps 1-3 are executed when Identity Manager starts up and whenever the audit configuration is updated. Step 4 will not occur if no audit event is generated before shutdown is called.
The configure(Map) is only called once on the same publisher object. (A publisher does not have to prepare for on-the-fly configuration changes). After the audit configuration is updated, the current publishers are first shut down and new publishers are created.
The configure() method in Step 3 may throw a WavesetException. In this case, the publisher will be ignored and no other calls will be made to the publisher.
Configuration
Publishers can have zero or more options. The getConfigurationOptions() method returns the list of options the publisher supports. The options are encapsulated using the PublisherOption class (see Javadoc for details of this class). The audit configuration viewer invokes this method when it builds the configuration interface for the publisher.
Identity Manager configures the publisher using the configure(Map) method at server startup and after audit configuration changes.
Developing Formatters
The REF kit includes the source code of the following formatters:
Formatters must implement the AuditRecordFormatter interface. In addition, formatters must have a no-arg constructor. Refer to the Javadoc included in the REF kit for details.
Registering Publishers/Formatters
The audit attribute of #ID#Configuration:SystemConfiguration object lists all the registered publishers and formatters. Only these publishers and formatters are available in the audit configuration user interface.