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".
Audit Record Structure
The exact moment in time that the audit record was generated
Unique identification of an audit event. It is a Lightweight Identifier.
Type of audit event. It describes what kind of operation was executed (adding an object, modification, user login, ...)
Stage of event processing: request of execution. See below.
Identifier of the interactive session in which the event have taken place. For security reason this is different than the content of the session cookie.
Unique identification of a task that this event is a part. It is a Lightweight Identifier.
OID of a task that this event is part of (if the task is persistent).
Identifier of a host that generated the audit record. This is the host name corresponding to a network interface that accepted the HTTP request.
|Node Identifier||Identifier of a node in a midPoint cluster that generated the audit record.|
|Remote Host Address||Network address of a remote host that originated the request causing this event.|
User that initiated ("caused") the event. It may the user that started the operation from a GUI or web service interface, the user that is owner of the task that recorded the event, etc.
Object that is a primary target of an operation (if applicable). In case that operation targets more than one object, the "primary" or the most important is recorded (e.g. the user object)
Owner of the object that is a target of this operation (if applicable). E.g. a owner of a task that is being stopped, owner of an account that is being modified, etc.
The changes that are being made to the targets. Deltas contain detailed information about the operation.
The channel that was the source of the operation that this record describes
Result of the operation: success, failure, partial failure, etc.
Event type defines the kind of operation that was executed. Currently defined event types are defined in the table below.
|Event DB ID|
Creating a new object (e.g adding a user, account, resource, ...)
Modification of an existing object
Removing an object
|4||Executing changes directly in the repository, e.g. changes made via debug pages.|
Synchronizing a change notification. This type should only be present in
Creating a new session, e.g. user login.
End of a session, e.g. user logout.
|8||Creation or completion of a work item (e.g. a request to approve particular assignment). See Workflow Auditing.|
|9||Creation or completion of a workflow process instance (may include 0, 1 or many work items). See Workflow Auditing.|
|10||Initiation or completion of reconciliation|
Other event types may be added in the future (including custom event types).
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.
|Stage DB ID|
The operation is requested. The record shows operation details (e.g. deltas) in the form as originally intended by the user or client.
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.
The result of the executed operation. All the possible values are described in the following table.
|Event Outcome||Outcome DB ID||Decritption|
Used when operation and sub operations finish successfully. The operation is completed and the result is final.
Used when operation finish successfully, but minor problem occurred. For example operation code recovered
Used when operation contains at least one operation witch status SUCCESS/WARNING and at least one
Used when operation didn't finish correctly. The operation is completed and the result is final.
Result does not make any sense for the operation. This is useful in cases that the operation is not supported
The operation is being executed. This is set for operations that are executed asynchronously or take a significant
No information about operation is present. Presence of this status usually means programming bug, e.g. someone
The operation didn't finish correctly but that was expected and handled. It is equivalent to success for all practical
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.
The auditing subsystem in midPoint is designed to be pluggable. There are currently two auditing implementations: auditing to log files and to database table.
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:
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 two 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
Auditing implementation in midPoint was inspired by XDAS and it is conceptually compatible with XDAS. The actual XDAS support in midPoint is planned for the future.
The XDAS specification asks for a common audit log format and a common taxonomy of audit log events.
The XDAS system is composed from several components. The components can be placed inside a single system or distributed across an organization.
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:
If there's no such header, network-level client address is used.
If the header contains more values (separated by commas), the first i.e. leftmost one is used.