Auditing

Auditing is a core module that can be enabled by setting the following property:

ipf.business-operations.audit.enabled = true

To audit a method you need to add the @Auditable annotation to the method signature. The annotation takes a parameter called type which indicates the action you are auditing.

Example:

@GetMapping("auth/basic")
@Auditable(type = "LOGIN_BASIC")
public void loginBasic() {}

An audit record consists of the following data fields:

public class AuditRecord {
    @Id
    String id;
    String userId;
    String clientIpAddress;
    String processingEntity;
    String transactionId;
    String action;
    Instant time;
    Map<String, Object> request;
    Map<String, Object> response;
}

To be able to populate the request and response Map you need to implement an AuditRequestExtractor and AuditResponseExtractor respectively:

import java.util.Map;
import java.util.Set;

/**
 * This class can be extended to implement a custom request extractor for a particular
 * type of audited method.
 */
public interface AuditRequestExtractor {
    /**
     * Return the extractor type that should match the corresponding
     * @Auditable types
     *
     * @return The types of extractor
     */
    Set<String> types();

    /**
     * Here you can extract the fields from the request parameters
     * you would like to be audited
     *
     * @param args The method arguments from the annotated method
     * @return A map representing the key value params extracted from the request method arguments
     */
    Map<String, Object> extractRequestData(Object[] args);
}
import java.util.Map;
import java.util.Set;

/**
 * This class can be extended to implement a custom response extractor for a particular
 * type of audited method.
 */
public interface AuditResponseExtractor {
    /**
     * Return the extractor type that should match the corresponding
     * @Auditable types
     *
     * @return The type of extractor
     */
    Set<String> types();

    /**
     * Here you can extract the fields from the response message
     * you would like to be audited
     *
     * @param responseData The response data from the annotated method
     * @return A map representing the key value params extracted from the response
     */
    Map<String, Object> extractResponseData(Object responseData);
}

The type of the extractor must match the annotated @Auditable type so we know which extractor to use for the audited method. Multiple extractors can be defined to cover all audited types. By default, no fields are extracted unless you implement a custom extractor.

Custom Types

Sometimes it is not possible to use the annotation for things like SAML/OAUTH which require special processing. In these types of cases it is possible to register custom action types that will then appear as action types in the UI for filtering purposes. To do this register a bean of type CustomAuditable which returns a set of strings representing the action types.

Example:

@Bean
public CustomAuditable getCustomAuthAuditables(SamlProperties samlProperties, OAuthProperties oAuthProperties) {
    return new CustomAuditable() {
        @Override
        public Set<String> actionTypes() {
            Set<String> actionTypes = new HashSet<>();
            if(samlProperties.isEnabled()) {
                actionTypes.add("SAML_LOGIN_SUCCESS");
                actionTypes.add("SAML_LOGIN_FAILURE");
            }
            if(oAuthProperties.isEnabled()) {
                actionTypes.add("OAUTH_LOGIN_SUCCESS");
                actionTypes.add("OAUTH_LOGIN_FAILURE");
            }
            return actionTypes;
        }
    };
}

Built-in audited action types

The audit module ships with a predefined set of action type constants. These are intended to be referenced by the @Auditable(type = …​) annotation and by request/response extractors.

You can use any of these values in your controllers/services; they will be surfaced as action types in the Audit UI.

Approvals

  • APPROVE_AGENT_SETTINGS

  • APPROVE_AGENT_CLEARING_SETTINGS

  • APPROVE_CS_AGENT_SELECTION_SETTINGS

  • APPROVE_AGENT_SETTLEMENT_SETTINGS

  • APPROVE_GENERIC_PROCESSING_SETTINGS

  • APPROVE_PROCESSING_ENTITY

  • APPROVE_BANK_FILTERING_RULE

  • APPROVE_HTM_TASK

Assign/Execute/Reject HTM tasks

  • ASSIGN_HTM_TASK

  • EXECUTE_HTM_TASK

  • EXECUTE_BULK_HTM_TASKS

  • REJECT_HTM_TASK

Create actions

  • CREATE_AGENT_SETTINGS

  • CREATE_AGENT_CLEARING_SETTINGS

  • CREATE_CS_AGENT_SELECTION_SETTINGS

  • CREATE_AGENT_SETTLEMENT_SETTINGS

  • CREATE_GENERIC_PROCESSING_SETTINGS

  • CREATE_PROCESSING_ENTITY

  • CREATE_BANK_FILTERING_RULE

Modify actions

  • MODIFY_AGENT_SETTINGS

  • MODIFY_AGENT_CLEARING_SETTINGS

  • MODIFY_CS_AGENT_SELECTION_SETTINGS

  • MODIFY_AGENT_SETTLEMENT_SETTINGS

  • MODIFY_GENERIC_PROCESSING_SETTINGS

  • MODIFY_PROCESSING_ENTITY

  • MODIFY_BANK_FILTERING_RULE

Reject actions

  • REJECT_AGENT_SETTINGS

  • REJECT_AGENT_CLEARING_SETTINGS

  • REJECT_CS_AGENT_SELECTION_SETTINGS

  • REJECT_AGENT_SETTLEMENT_SETTINGS

  • REJECT_GENERIC_PROCESSING_SETTINGS

  • REJECT_PROCESSING_ENTITY

  • REJECT_BANK_FILTERING_RULE

Delete actions

  • DELETE_AGENT_SETTINGS

  • DELETE_AGENT_CLEARING_SETTINGS

  • DELETE_CS_AGENT_SELECTION_SETTINGS

  • DELETE_AGENT_SETTLEMENT_SETTINGS

  • DELETE_GENERIC_PROCESSING_SETTINGS

  • DELETE_PROCESSING_ENTITY

  • DELETE_BANK_FILTERING_RULE

Response access denied types

These are recorded when a response is denied for the given domain area.

  • AGENT_SETTINGS_RESPONSE_ACCESS_DENIED

  • AGENT_CLEARING_SETTINGS_RESPONSE_ACCESS_DENIED

  • CS_AGENT_SELECTION_SETTINGS_RESPONSE_ACCESS_DENIED

  • AGENT_SETTLEMENT_SETTINGS_RESPONSE_ACCESS_DENIED

  • GENERIC_PROCESSING_SETTINGS_RESPONSE_ACCESS_DENIED

  • HTM_RESPONSE_ACCESS_DENIED

  • ODS_SUMMARY_RESPONSE_ACCESS_DENIED

  • PROCESSING_ENTITY_RESPONSE_ACCESS_DENIED

  • BANK_FILTERING_RESPONSE_ACCESS_DENIED

Other actions

  • EXPORT_PAYMENT_SUMMARIES

  • CANCEL_PAYMENT_REQUEST

  • LOGIN_BASIC

  • DEFAULT

If you need actions not covered above (e.g., SAML/OAUTH logins), define them via a CustomAuditable bean as described earlier. They will appear as additional action types in the UI. When adding new audited actions in code, prefer importing and referencing the constants from AuditableType to keep the taxonomy consistent.