Audit Logging​

Find here information about the AuditLog service in CAP Java.

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 theAuditLogService 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 theoutbox service internally which allowsdeferred sending of events.

Use AuditLogService​

Get AuditLogService Instance​

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

import com.sap.cds.services.auditlog.AuditLogService;@Autowiredprivate AuditLogService auditLogService;

Alternatively the AuditLog service can be retrieved from theServiceCatalog:

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

See sectionUsing Services for more details about retrieving services.

Emit Personal Data Access Event​

To emit a personal data access event use methodlogDataAccess of theAuditLogService.

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

Emit Personal Data Modification Event​

To emit a personal data modification event use methodlogDataModification of theAuditLogService.

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

Emit Configuration Change Event​

To emit a configuration change event use methodlogConfigChange of theAuditLogService.

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

Emit Security Event​

Use methodlogSecurityEvent of theAuditLogService 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 theaudit log handler, theAuditLogService can store the event in theoutbox. This is done in thesame 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. SeeChangeSetContext 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 anin-memory flavour which has the drawback that it can't guarantee that the all events are processed after the transaction has been successfully closed.

To close this gap, a sophisticatedpersistent outbox service can be configured.

By default, not all events are send asynchronously via (persistent) outbox.

• Security events are always send synchronously.
• All other events are stored to persistent outbox, if available. The in-memory outbox acts as a fallback otherwise.

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 and writesDEBUG log entries. However, the application log does not logDEBUG entries by default. To enable audit logging to the application log, the log level of the default handler needs to be set toDEBUG level:

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

AuditLog v2 Handler​

Additionally, the CAP Java SDK provides anAuditLog v2 handler that writes the audit messages to the SAP Audit Log service via its API version 2. To enable this handler, an additional feature dependency must be added to thesrv/pom.xml of the CAP Java project:

<dependency>  <groupId>com.sap.cds</groupId>  <artifactId>cds-feature-auditlog-v2</artifactId>  <scope>runtime</scope></dependency>

Also a service binding to the AuditLog v2 service has to be added to the CAP Java application, then this handler is activated. The Auditlog v2 handler supports thepremium plan of the AuditLog Service as describedhere.

If it's required to disable the AuditLog v2 handler for some reason, this can be achieved by setting the CDS propertycds.auditLog.v2.enabled tofalse inapplication.yaml:

cds:  auditlog.v2.enabled:false

The default value of this parameter istrue and the AuditLog v2 handler is automatically enabled, if all other requirements are fulfilled.

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 interfaceEventHandler 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 {@Onpublic void handleDataAccessEvent(DataAccessLogContextcontext) {// custom handler code}@Onpublic void handleDataModificationEvent(DataModificationLogContextcontext) {// custom handler code}@Onpublic void handleConfigChangeEvent(ConfigChangeLogContextcontext) {// custom handler code}@Onpublic void handleSecurityEvent(SecurityLogContextcontext) {// custom handler code}}

Learn more about implementing an event handler inEvent Handler Classes.