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 xml	Function
onPass	Message to write to DataFilter passed the entity.
onSkip	Message to write to DataFilter skipped the entity.
onSkipChain	Message to write to DataFilter skipped the entity and the DataFilter's skipScope is set to CHAIN.

DataSink

Field's name in xml	Function
onSuccess	Message to write to audit log if the DataSink's exporting is successful.
onError	Message 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

Field	Details
ID	Unique identifier of the Audit Record.
SUBTYPE	More specific description of the audited records type.
CONFIG_PATH	Created with concatenation of module and entity names.
AUDIT_TYPE	General description of the audited records type. Possible values: USER, ROLE, APPL, CRED, PROF, OTHER.
EXT_ID	Unique external ID of the audit record type, not necessarily related to ID.
TIME_STAMP	Date and time of the Audit Record type's creation.

Target System

It can be found under tndpc_targat_system table in the target database

Field	Details
ID	Unique identifier of the Target System.
TARGET_SYSTEM	Name of the Target System.
CONFIG_PATH	Created with concatenation of module and entity names and from a counter.
AUDIT_RECORD	ID of the type of the audit record to which the target system belongs.
OPERATION	In case of JDBCDataSink or LDAPDataSink the operation performed. Possible values: INSERT, UPDATE, DELTE.
STATUS	Status of the operation Possible values: OK, SKIP, ERROR

Audit Message

It can be found under tndpc_audit_message table in the target database

Field	Details
ID	Unique identifier of the Audit Message.
TYPE	Information about the reason of the audit message. Possible values: INFO, WARNING, ERROR.
MESSAGE	The audit message.
CONFIG_PATH	Created from the CONFIG_PATH of the Target System and a counter.
TARGET_SYSTEM	Id 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

ID	TARGET_SYSTEM	CONFIG_PATH	AUDIT_RECORD	OPERATION	STATUS
1005	ldap	default_user_0	1005	UPDATE	OK

tndpc_audit_record

ID	SUBTYPE	CONFIG_PATH	EXT_ID	TIMESTAMP	AUDIT_TYPE
1005	Employee	default_user	testJms	2023-05-04 13:27:02	USER

tndpc_audit_message

ID	TYPE	MESSAGE	CONFIG_PATH	TARGET_SYSTEM
1052	INFO	Filter passed the following user 02658932-5097-4305-beae-4a394c5f69c6	default_user_0_0	1005
1053	INFO	User 02658932-5097-4305-beae-4a394c5f69c6 exported to ldap	default_user_0	1005
1054	INFO	Filter passed the following user 98	default_user_0_0	1005
1055	INFO	User 98 exported to ldap	default_user_0	1005
1056	INFO	Filter passed the following user 100	default_user_0_0	1005
1057	INFO	User 100 exported to ldap	default_user_0	1005
1058	INFO	Filter passed the following user d2c79388-9965-4f1b-86f4-44ad96bb7293	default_user_0_0	1005
1059	INFO	User d2c79388-9965-4f1b-86f4-44ad96bb7293 exported to ldap	default_user_0	1005