Skip to main content
Version: 7.2405.x.x LTS

Using Audit functionality

Audit functionality can be used to log data related to entities handled by nevisDP. For example: logging the parameters a User has been created with, in nevisIDM.

Two types of auditing is possible, depending on the value of audit.backend in nevisdp-audit.properties.

  • text: Text-based Auditing writes audit messages to a log file.
  • jpa: JPA-based Auditing writes audit messages into a database.

Audit elements

The following elements are stored/logged by auditing.

Audit Record

Contains information about the audit record(s):

  • AUDIT_TYPE: type of the entity Possible values: USER, ROLE, APPL, CRED, PROF, OTHER.
  • SUBTYPE: more specific type of the entity that can be set in the dataporter.xml to any string which can be used to identify the current import/export process.
  • TIME_STAMP: Date and time when the log is written. In case of text based logging the format is Mon DD, YYYY HH:MM:SS

Target System

Information about the system, where the data is imported to or exported from. It is related to the DataSink that consumes the entities.

  • OPERATION: In case of JDBCDataSink or LDAPDataSink a given operation is performed. Possible values: INSERT, UPDATE, DELTE or NULL.
  • STATUS: Status of the operation. Possible values: OK, SKIP, ERROR.

Audit Message

Contains a message related to an audited entity, and some closely related information.

  • TYPE : Information about the reason of the audit message. Possible values: INFO, WARNING, ERROR.
  • MESSAGE : The audit message.

Setting up auditing

If Auditing will be jpa based, the steps written in Audit log database setup has to be followed.

Creating audit record

In the module an audit definition is required to define the Audit Record for the messages we want to write. This can be done with the following xml tag:

entityId fields defines an externally visible id of this import/export process.

<audit type="USER" subtype="Student" entityId="newlyCreatedUserImport"/>

Creating audit message

Audit messages can be defined by

  • creating one in a DataFilter with the following xml child tag:

    <audit onPass="Filter passed the following user #{in.user.values.extId}" onSkip="Filter skipped the following user #{in.user.values.extId}"/>
  • or creating one within dataSink:

    <audit targetSystem="ldap" onSuccess="User #{in.user.values.extId} exported to ldap" onError="User export failed" />

If there is no targetSystem defined in dataSink, then one will be generated with the name copied from the name of the entity.

State transfers referenced by audit messages when used with DataFilter and DataSink implementations

DataFilter
Field's name in xmlFunction
onPassMessage to write to DataFilter passed the entity.
onSkipMessage to write to DataFilter skipped the entity.
onSkipChainMessage to write to DataFilter skipped the entity and the DataFilter's skipScope is set to CHAIN.
DataSink
Field's name in xmlFunction
onSuccessMessage to write to audit log if the DataSink's exporting is successful.
onErrorMessage to write to audit log if the DataSink's exporting is failed.

Text based Auditing

To use text based auditing, the value of audit.backend has to be set to text in the nevisdp-audit.properties file.

The file can also contain the following two properties:

audit.filename

Location of the auditing log can be set with audit.filename with path starting from the instance directory of nevisdp. Default value is audit.log.

audit.maxfilesize

Size to roll over the log file can be set with audit.maxfilesize. Default value 1MB.

JPA Auditing

Database description

Audit Record

It can be found under tndpc_audit_record table in the target databse

FieldDetails
IDUnique identifier of the Audit Record.
SUBTYPEMore specific description of the audited records type.
CONFIG_PATHCreated with concatenation of module and entity names.
AUDIT_TYPEGeneral description of the audited records type. Possible values: USER, ROLE, APPL, CRED, PROF, OTHER.
EXT_IDUnique external ID of the audit record type, not necessarily related to ID.
TIME_STAMPDate and time of the Audit Record type's creation.

Target System

It can be found under tndpc_targat_system table in the target database

FieldDetails
IDUnique identifier of the Target System.
TARGET_SYSTEMName of the Target System.
CONFIG_PATHCreated with concatenation of module and entity names and from a counter.
AUDIT_RECORDID of the type of the audit record to which the target system belongs.
OPERATIONIn case of JDBCDataSink or LDAPDataSink the operation performed. Possible values: INSERT, UPDATE, DELTE.
STATUSStatus of the operation Possible values: OK, SKIP, ERROR

Audit Message

It can be found under tndpc_audit_message table in the target database

FieldDetails
IDUnique identifier of the Audit Message.
TYPEInformation about the reason of the audit message. Possible values: INFO, WARNING, ERROR.
MESSAGEThe audit message.
CONFIG_PATHCreated from the CONFIG_PATH of the Target System and a counter.
TARGET_SYSTEMId of the Target System.

Example

Configuration

    <export>
<module name="default">
<entity name="user">
<audit type="USER" subtype="Employee" entityId="testJms"/>
<dataSource type="NevisIDMSource">
<dp:paraVal name="service" value="${inst.adminService}"/>
<dp:paraVal name="queryType" value="user"/>
</dataSource>

<dataFilter type="ELMappingFilter">
<dp:attrVal name="objectClass" value="top person" separator=" "/>
<dp:attrVal name="cn" value="#{in.user.values.name}"/>
<dp:attrVal name="sn" value="#{in.user.values.firstName}"/>
<audit onPass="Filter passed the following user #{in.user.values.extId}" onSkip="Filter skipped the following user #{in.user.values.extId}"/>
</dataFilter>

<dataSink type="LDAPDataSink">
<dp:paraVal name="ldapContext" value="${inst.ldapConnection}"/>
<dp:paraVal name="operation" value="createOrUpdate"/>
<dp:paraVal name="basedn" value="ou=people,o=NEVIS Security AG,dc=nevisdp,dc=dev"/>
<dp:paraVal name="rdn" value="cn=#{out.user.cn}"/>
<audit targetSystem="ldap" onSuccess="User #{in.user.values.extId} exported to ldap" onError="User export failed" />
</dataSink>
</entity>
</module>
</export>

Output

Text-based auditing

Record        [default_user] - May 4, 2023 13:23:14, Type: 'USER', Subtype: 'Employee', ExtID: 'admin'
Target System [default_user_0] - 'ldap' Operation: UPDATE - OK
Message [default_user_0_0] - Filter passed the following user 02658932-5097-4305-beae-4a394c5f69c6
Message [default_user_0] - User 02658932-5097-4305-beae-4a394c5f69c6 exported to ldap
Record [default_user] - May 4, 2023 13:23:14, Type: 'USER', Subtype: 'Employee', ExtID: 'batchjob'
Target System [default_user_0] - 'ldap' Operation: UPDATE - OK
Message [default_user_0_0] - Filter passed the following user 98
Message [default_user_0] - User 98 exported to ldap
Record [default_user] - May 4, 2023 13:23:14, Type: 'USER', Subtype: 'Employee', ExtID: 'bootstrap'
Target System [default_user_0] - 'ldap' Operation: UPDATE - OK
Message [default_user_0_0] - Filter passed the following user 100
Message [default_user_0] - User 100 exported to ldap
Record [default_user] - May 4, 2023 13:23:14, Type: 'USER', Subtype: 'Employee', ExtID: 'dani'
Target System [default_user_0] - 'ldap' Operation: UPDATE - OK
Message [default_user_0_0] - Filter passed the following user d2c79388-9965-4f1b-86f4-44ad96bb7293
Message [default_user_0] - User d2c79388-9965-4f1b-86f4-44ad96bb7293 exported to ldap
Record [default_user] - May 4, 2023 13:23:14, Type: 'USER', Subtype: 'Employee', ExtID: 'dataporter_user1'
Target System [default_user_0] - 'ldap' Operation: UPDATE - OK

JPA-based auditing

tndpc_targat_system

IDTARGET_SYSTEMCONFIG_PATHAUDIT_RECORDOPERATIONSTATUS
1005ldapdefault_user_01005UPDATEOK

tndpc_audit_record

IDSUBTYPECONFIG_PATHEXT_IDTIMESTAMPAUDIT_TYPE
1005Employeedefault_usertestJms2023-05-04 13:27:02USER

tndpc_audit_message

IDTYPEMESSAGECONFIG_PATHTARGET_SYSTEM
1052INFOFilter passed the following user 02658932-5097-4305-beae-4a394c5f69c6default_user_0_01005
1053INFOUser 02658932-5097-4305-beae-4a394c5f69c6 exported to ldapdefault_user_01005
1054INFOFilter passed the following user 98default_user_0_01005
1055INFOUser 98 exported to ldapdefault_user_01005
1056INFOFilter passed the following user 100default_user_0_01005
1057INFOUser 100 exported to ldapdefault_user_01005
1058INFOFilter passed the following user d2c79388-9965-4f1b-86f4-44ad96bb7293default_user_0_01005
1059INFOUser d2c79388-9965-4f1b-86f4-44ad96bb7293 exported to ldapdefault_user_01005