|
| 1 | +[[auditing]] |
| 2 | += Auditing |
| 3 | + |
| 4 | +[[auditing.basics]] |
| 5 | +== Basics |
| 6 | +Spring Data provides sophisticated support to transparently keep track of who created or changed an entity and when the change happened.To benefit from that functionality, you have to equip your entity classes with auditing metadata that can be defined either using annotations or by implementing an interface. |
| 7 | +Additionally, auditing has to be enabled either through Annotation configuration or XML configuration to register the required infrastructure components. |
| 8 | +Please refer to the store-specific section for configuration samples. |
| 9 | + |
| 10 | +[NOTE] |
| 11 | +==== |
| 12 | +Applications that only track creation and modification dates are not required do make their entities implement xref:auditing.adoc#auditing.auditor-aware[`AuditorAware`]. |
| 13 | +==== |
| 14 | + |
| 15 | +[[auditing.annotations]] |
| 16 | +=== Annotation-based Auditing Metadata |
| 17 | +We provide `@CreatedBy` and `@LastModifiedBy` to capture the user who created or modified the entity as well as `@CreatedDate` and `@LastModifiedDate` to capture when the change happened. |
| 18 | + |
| 19 | +.An audited entity |
| 20 | +[source,java] |
| 21 | +---- |
| 22 | +class Customer { |
| 23 | +
|
| 24 | + @CreatedBy |
| 25 | + private User user; |
| 26 | +
|
| 27 | + @CreatedDate |
| 28 | + private Instant createdDate; |
| 29 | +
|
| 30 | + // … further properties omitted |
| 31 | +} |
| 32 | +---- |
| 33 | + |
| 34 | +As you can see, the annotations can be applied selectively, depending on which information you want to capture. |
| 35 | +The annotations, indicating to capture when changes are made, can be used on properties of type JDK8 date and time types, `long`, `Long`, and legacy Java `Date` and `Calendar`. |
| 36 | + |
| 37 | +Auditing metadata does not necessarily need to live in the root level entity but can be added to an embedded one (depending on the actual store in use), as shown in the snippet below. |
| 38 | + |
| 39 | +.Audit metadata in embedded entity |
| 40 | +[source,java] |
| 41 | +---- |
| 42 | +class Customer { |
| 43 | +
|
| 44 | + private AuditMetadata auditingMetadata; |
| 45 | +
|
| 46 | + // … further properties omitted |
| 47 | +} |
| 48 | +
|
| 49 | +class AuditMetadata { |
| 50 | +
|
| 51 | + @CreatedBy |
| 52 | + private User user; |
| 53 | +
|
| 54 | + @CreatedDate |
| 55 | + private Instant createdDate; |
| 56 | +
|
| 57 | +} |
| 58 | +---- |
| 59 | + |
| 60 | +[[auditing.interfaces]] |
| 61 | +=== Interface-based Auditing Metadata |
| 62 | +In case you do not want to use annotations to define auditing metadata, you can let your domain class implement the `Auditable` interface. It exposes setter methods for all of the auditing properties. |
| 63 | + |
| 64 | +[[auditing.auditor-aware]] |
| 65 | +=== `AuditorAware` |
| 66 | + |
| 67 | +In case you use either `@CreatedBy` or `@LastModifiedBy`, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an `AuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be. |
| 68 | + |
| 69 | +The following example shows an implementation of the interface that uses Spring Security's `Authentication` object: |
| 70 | + |
| 71 | +.Implementation of `AuditorAware` based on Spring Security |
| 72 | +[source, java] |
| 73 | +---- |
| 74 | +class SpringSecurityAuditorAware implements AuditorAware<User> { |
| 75 | +
|
| 76 | + @Override |
| 77 | + public Optional<User> getCurrentAuditor() { |
| 78 | +
|
| 79 | + return Optional.ofNullable(SecurityContextHolder.getContext()) |
| 80 | + .map(SecurityContext::getAuthentication) |
| 81 | + .filter(Authentication::isAuthenticated) |
| 82 | + .map(Authentication::getPrincipal) |
| 83 | + .map(User.class::cast); |
| 84 | + } |
| 85 | +} |
| 86 | +---- |
| 87 | + |
| 88 | +The implementation accesses the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance that you have created in your `UserDetailsService` implementation. We assume here that you are exposing the domain user through the `UserDetails` implementation but that, based on the `Authentication` found, you could also look it up from anywhere. |
| 89 | + |
| 90 | +[[auditing.reactive-auditor-aware]] |
| 91 | +=== `ReactiveAuditorAware` |
| 92 | + |
| 93 | +When using reactive infrastructure you might want to make use of contextual information to provide `@CreatedBy` or `@LastModifiedBy` information. |
| 94 | +We provide an `ReactiveAuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be. |
| 95 | + |
| 96 | +The following example shows an implementation of the interface that uses reactive Spring Security's `Authentication` object: |
| 97 | + |
| 98 | +.Implementation of `ReactiveAuditorAware` based on Spring Security |
| 99 | +[source, java] |
| 100 | +---- |
| 101 | +class SpringSecurityAuditorAware implements ReactiveAuditorAware<User> { |
| 102 | +
|
| 103 | + @Override |
| 104 | + public Mono<User> getCurrentAuditor() { |
| 105 | +
|
| 106 | + return ReactiveSecurityContextHolder.getContext() |
| 107 | + .map(SecurityContext::getAuthentication) |
| 108 | + .filter(Authentication::isAuthenticated) |
| 109 | + .map(Authentication::getPrincipal) |
| 110 | + .map(User.class::cast); |
| 111 | + } |
| 112 | +} |
| 113 | +---- |
| 114 | + |
| 115 | +The implementation accesses the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance that you have created in your `UserDetailsService` implementation. We assume here that you are exposing the domain user through the `UserDetails` implementation but that, based on the `Authentication` found, you could also look it up from anywhere. |
0 commit comments