Auditing is a mechanism that records the most important interactions in the system in a computer-processable forms. The goal of the auditing is to record the interactions on "business" level, essentially recording who does what, who changed what, etc.

The audit record (audit trail) has to be machine-processable. It should be eventually possible to reconstruct a partial historical state of the system from the audit records by "going back in time".

Synchronizing a change notification. This type should only be present in REQUEST stage, the EXECUTION stage of the event will provide a more specific event type.

CREATE_SESSION

6

Creating a new session, e.g. user login.

TERMINATE_SESSION

7

End of a session, e.g. user logout.

WORK_ITEM

8

Creation or completion of a work item (e.g. a request to approve particular assignment). See Workflow Auditing.

WORKFLOW_PROCESS_INSTANCE

9

Creation or completion of a workflow process instance (may include 0, 1 or many work items). See Workflow Auditing.

RECONCILIATION

10

Initiation or completion of reconciliation

Other event types may be added in the future (including custom event types).

Event Stages

Operations in midPoint may be subject to quite complex processing before they get executed. This may include processing RBAC, expressions, workflows or other "plugin" hooks. Therefore the details of the operation may considerably differ at the beginning of the operation and at the end. Event stages are defined to denote this difference and to record events at various stages through the operation lifecycle.

Event Stage

Stage DB ID

Description

REQUEST

0

The operation is requested. The record shows operation details (e.g. deltas) in the form as originally intended by the user or client.

EXECUTION

1

The operation after execution. The record shows operation details (e.g. deltas) in the form as it was executed.

Other stages may be added in the future (e.g. stage for approvals or workflow steps).

There is usually one request and one execution record for each operation. E.g. the request record contains the delta that assigns role to a user. The execution record will also contain that delta but it may additional deltas, e.g. deltas for adding new accounts implied by the role. In some cases there may be several execution records for a single request record. This happens if the execution happens in several waves. E.g. a role is assigned to a user. Some of the accounts implied by the role may be created immediately and others needs to wait for an approval. Therefore the accounts that can be created immediately will be audited in a first execution audit record. The second batch of accounts will be audited when they are later approved and created. This goes to the second audit record. This situation may also happen even if there are no approvals, e.g. in case of resource dependencies or even complex inbound-outbound-template interactions.

Event Outcomes

The result of the executed operation. All the possible values are described in the following table.

Event Outcome

Outcome DB ID

Decritption

SUCCESS

0

Used when operation and sub operations finish successfully. The operation is completed and the result is final.

WARNING

1

Used when operation finish successfully, but minor problem occurred. For example operation code recovered from some error and after that operation finished successfully. The operation is completed and the result is final.

PARTIAL_ERROR

2

Used when operation contains at least one operation witch status SUCCESS/WARNING and at least one operation with status FATAL_ERROR. The operation is completed and the result is final.

FATAL_ERROR

3

Used when operation didn't finish correctly. The operation is completed and the result is final.

NOT_APPLICABLE

4

Result does not make any sense for the operation. This is useful in cases that the operation is not supported (e.g. an optional part of the interface). This is different than UNKNOWN, as in this case we really know that it result is not applicable. In UNKNOWN case we know nothing. The operation is completed and the result is final.

IN_PROGRESS

5

The operation is being executed. This is set for operations that are executed asynchronously or take a significant amount of time. Short synchronous operations do not need to set this status, they may go well with the default UNKNOWN status. The operation is in progress and the final result is not yet known.

UNKNOWN

6

No information about operation is present. Presence of this status usually means programming bug, e.g. someoneforgot to set or compute appropriate operation result.

HANDLED_ERROR

7

The operation didn't finish correctly but that was expected and handled. It is equivalent to success for all practicalcases except for displaying the result. But using success status for this situation might be misleading. The operation is completed and the result is final.

Initiator and Attorney

MidPoint 3.7 introduced a concept of attorney. Therefore there is possibility that one user acts on behalf of another user. Both users are recorded in the audit logs. The meaning is as follows:

Initiator is the (legal) entity on behalf of whom is the action executed. It is the subject of the operation. Authorizations of the initiator are used to evaluate access to the operation. This is the entity who is formally responsible for the operation. Although initiator is always a user in midPoint 3.7 and earlier, the initiator may be an organization in later midPoint versions.

Attorney is the (physical) user who have executed the action. This is the user that have logged-in to the user interface. This is the user that pressed the button to execute the action. This is always identity of a user and it will always be a user. It cannot be a company or any other virtual entity.

Audit Trails

The auditing subsystem in midPoint is designed to be pluggable. There are currently two auditing implementations: auditing to log files and to database table.

Logfile Auditing

Audit logs are recorded in a form of human-readable text records in the usual log files. This auditing goes to the default log file (idm.log) and is turned off by default. It is using a dedicated logger name:

Audit Logger Name

com.evolveum.midpoint.audit.log

This logger can be directed to a specific appender to a separate audit log file using the normal logging configuration mechanism.

Database Table Auditing

When using database table auditing, audit logs are stored in five tables whose structure is described in code block below (part of DB script for H2 database). You can find table structures for different DB vendors in out git, or in distribution packages in folder config/sql/midpoint/<version>.

id column in m_audit_event table is now generated by default (auto increment).

Columns delta and fullResult in m_audit_delta table are compressed using GZIP

Determining Remote Host Address

Normally, the remote host address is determined from the HTTP connection; as returned by the HttpServletRequest.getRemoteAddr() method. However, there are situations where a trustworthy proxy server is used, so the "real" client host address can be obtained from an HTTP header created by it. MidPoint can be set up to use such a header (if present) using the following configuration: