Audit Logging

Find here information about the AuditLog service in CAP Java.

Content

• AuditLog Service
  • Overview
  • Use AuditLogService
  • Deferred AuditLog Events
• AuditLog Handlers
  • Default Handler
  • Custom AuditLog Handler

AuditLog Service

Overview

As of CAP Java 1.18.0, an AuditLog service is provided for CAP Java applications. The AuditLog service can be used to emit AuditLog related events to registered handlers.

The following events can be emitted with the AuditLogService to the registered handlers:

• Personal data accesses
• Personal data modifications
• Configuration changes
• Security events

AuditLog events typically are bound to business transactions. In order to handle the events transactionally and also to decouple the request from outbound calls to a consumer, for example a central audit log service, the AuditLog service leverages the outbox service internally which allows deferred sending of events.

Use AuditLogService

Get AuditLogService Instance

The AuditLogService can be injected into a custom handler class, if the CAP Java project uses Spring Boot:

import com.sap.cds.services.auditlog.AuditLogService;

@Autowired
private AuditLogService auditLogService;

Alternatively the AuditLog service can be retrieved from the ServiceCatalog:

ServiceCatalog catalog = context.getServiceCatalog();
auditLogService = (AuditLogService) catalog.getService(AuditLogService.DEFAULT_NAME);

See section Using Services for more details about retrieving services.

Emit Personal Data Access Event

To emit a personal data access event use method logDataAccess of the AuditLogService.

List<Access> accesses = new ArrayList<>();
Access access = Access.create();
// fill access object with data
accesses.add(access);
auditLogService.logDataAccess(accesses);

Emit Personal Data Modification Event

To emit a personal data modification event use method logDataModification of the AuditLogService.

List<DataModification> dataModifications = new ArrayList<>();
DataModification modification = DataModification.create();
// fill data modification object with data
dataModifications.add(modification);
auditLogService.logDataModification(dataModifications);

Emit Configuration Change Event

To emit a configuration change event use method logConfigChange of the AuditLogService.

List<ConfigChange> configChanges = new ArrayList<>();
ConfigChange configChange = ConfigChange.create();
// fill config change object with data
configChanges.add(configChange);
auditLogService.logConfigChange(Action.UPDATE, configChanges);

Emit Security Event

Use method logSecurityEvent of the AuditLogService to emit an security event.

String action = "login";
String data = "user-name";
auditLogService.logSecurityEvent(action, data);

Deferred AuditLog Events

Instead of processing the audit log events synchronously in the audit log handler, the AuditLogService can store the event in the outbox. This is done in the same transaction of the business request. Hence, a cancelled business transaction will not send any audit log events that are bound to it. To gain fine-grained control, for example to isolate a specific event from the current transaction, you may refine the transaction scope. See ChangeSetContext API for more information.

As the stored events are processed asynchronously, the business request is also decoupled from the audit log handler which typically sends the events synchronously to a central audit log service. This improves resilience and performance.

By default, the outbox comes in an in-memory flavour which has the drawback that it can’t guarantee that the all events are processed after the transaction has been successfully closed.

AuditLog Handlers

Default Handler

By default, the CAP Java SDK provides an AuditLog handler that writes the AuditLog messages to the application log. This default handler is registered on all AuditLog events, but the log entries are not written to the application log, as the corresponding log level is DEBUG. To enable audit logging to the application log, the log level of the default handler needs to be set to DEBUG level:

logging:
  level:
    com.sap.cds.auditlog: DEBUG

Custom AuditLog Handler

CAP Java applications can also provide their own AuditLog handlers to implement custom processing of AuditLog events. The custom handler class has to implement the interface EventHandler and needs to be annotated with @ServiceName(value = "*", type = AuditLogService.class). If the CAP Java project uses Spring Boot, the class can be annotated with @Component to register the handler at the CDS runtime.

For each of the four supported AuditLog events, a handler method can be registered. Depending on the event type, the method signature has to support the corresponding argument type:

With one of the annotations @Before, @On, and @After the handler method needs to be annotated to indicate in which phase of the event processing this method gets called.

The following example defines an AuditLog event handler class with methods for all event types:

import com.sap.cds.services.auditlog.*;
import com.sap.cds.services.handler.*;
import com.sap.cds.services.handler.annotations.*;
import org.springframework.stereotype.*;

@Component
@ServiceName(value = "*", type = AuditLogService.class)
class CustomAuditLogHandler implements EventHandler {

	@On
	public void handleDataAccessEvent(DataAccessLogContext context) {
		// custom handler code
	}

	@On
	public void handleDataModificationEvent(DataModificationLogContext context) {
		// custom handler code
	}

	@On
	public void handleConfigChangeEvent(ConfigChangeLogContext context) {
		// custom handler code
	}

	@On
	public void handleSecurityEvent(SecurityLogContext context) {
		// custom handler code
	}
}

Learn more about implementing an event handler in Event Handler Classes.