[Audit Logging] Add AuditTrail service (#69278)

* add generic audit_trail service in core

* expose auditTraik service to plugins

* add auditTrail x-pack plugin

* fix type errors

* update mocks

* expose asScoped interface via start. auditor via  request context

* use type from audit trail service

* wrap getActiveSpace in safeCall only. it throws exception for non-authz

* pass message to log explicitly

* update docs

* create one auditor per request

* wire es client up to auditor

* update docs

* withScope accepts only one scope

* use scoped client in context for callAsInternalUser

* use auditor in scoped cluster client

* adopt auditTrail plugin to new interface. configure log from config

* do not log audit events in console by default

* add audit trail functional tests

* cleanup

* add example

* add mocks for spaces plugin

* add unit tests

* update docs

* test description

* Apply suggestions from code review

apply @jportner suggestions

Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com>

* add unit tests

* more robust tests

* make spaces optional

* address comments

* update docs

* fix WebStorm refactoring

Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com>

Author: mshustov

docs/development/core/server/kibana-plugin-core-server.auditableevent.md

@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditableEvent](./kibana-plugin-core-server.auditableevent.md)
+
+## AuditableEvent interface
+
+Event to audit.
+
+<b>Signature:</b>
+
+```typescript
+export interface AuditableEvent 
+```
+
+## Remarks
+
+Not a complete interface.
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [message](./kibana-plugin-core-server.auditableevent.message.md) | <code>string</code> |  |
+|  [type](./kibana-plugin-core-server.auditableevent.type.md) | <code>string</code> |  |
+

docs/development/core/server/kibana-plugin-core-server.auditableevent.message.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditableEvent](./kibana-plugin-core-server.auditableevent.md) &gt; [message](./kibana-plugin-core-server.auditableevent.message.md)
+
+## AuditableEvent.message property
+
+<b>Signature:</b>
+
+```typescript
+message: string;
+```

docs/development/core/server/kibana-plugin-core-server.auditableevent.type.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditableEvent](./kibana-plugin-core-server.auditableevent.md) &gt; [type](./kibana-plugin-core-server.auditableevent.type.md)
+
+## AuditableEvent.type property
+
+<b>Signature:</b>
+
+```typescript
+type: string;
+```

docs/development/core/server/kibana-plugin-core-server.auditor.add.md

@@ -0,0 +1,36 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [Auditor](./kibana-plugin-core-server.auditor.md) &gt; [add](./kibana-plugin-core-server.auditor.add.md)
+
+## Auditor.add() method
+
+Add a record to audit log. Service attaches to a log record: - metadata about an end-user initiating an operation - scope name, if presents
+
+<b>Signature:</b>
+
+```typescript
+add(event: AuditableEvent): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  event | <code>AuditableEvent</code> |  |
+
+<b>Returns:</b>
+
+`void`
+
+## Example
+
+How to add a record in audit log:
+
+```typescript
+router.get({ path: '/my_endpoint', validate: false }, async (context, request, response) => {
+  context.core.auditor.withAuditScope('my_plugin_operation');
+  const value = await context.core.elasticsearch.legacy.client.callAsCurrentUser('...');
+  context.core.add({ type: 'operation.type', message: 'perform an operation in ... endpoint' });
+
+```
+

docs/development/core/server/kibana-plugin-core-server.auditor.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [Auditor](./kibana-plugin-core-server.auditor.md)
+
+## Auditor interface
+
+Provides methods to log user actions and access events.
+
+<b>Signature:</b>
+
+```typescript
+export interface Auditor 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [add(event)](./kibana-plugin-core-server.auditor.add.md) | Add a record to audit log. Service attaches to a log record: - metadata about an end-user initiating an operation - scope name, if presents |
+|  [withAuditScope(name)](./kibana-plugin-core-server.auditor.withauditscope.md) | Add a high-level scope name for logged events. It helps to identify the root cause of low-level events. |
+

docs/development/core/server/kibana-plugin-core-server.auditor.withauditscope.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [Auditor](./kibana-plugin-core-server.auditor.md) &gt; [withAuditScope](./kibana-plugin-core-server.auditor.withauditscope.md)
+
+## Auditor.withAuditScope() method
+
+Add a high-level scope name for logged events. It helps to identify the root cause of low-level events.
+
+<b>Signature:</b>
+
+```typescript
+withAuditScope(name: string): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  name | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`void`
+

docs/development/core/server/kibana-plugin-core-server.auditorfactory.asscoped.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) &gt; [asScoped](./kibana-plugin-core-server.auditorfactory.asscoped.md)
+
+## AuditorFactory.asScoped() method
+
+<b>Signature:</b>
+
+```typescript
+asScoped(request: KibanaRequest): Auditor;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  request | <code>KibanaRequest</code> |  |
+
+<b>Returns:</b>
+
+`Auditor`
+

docs/development/core/server/kibana-plugin-core-server.auditorfactory.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md)
+
+## AuditorFactory interface
+
+Creates [Auditor](./kibana-plugin-core-server.auditor.md) instance bound to the current user credentials.
+
+<b>Signature:</b>
+
+```typescript
+export interface AuditorFactory 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [asScoped(request)](./kibana-plugin-core-server.auditorfactory.asscoped.md) |  |
+

docs/development/core/server/kibana-plugin-core-server.audittrailsetup.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md)
+
+## AuditTrailSetup interface
+
+<b>Signature:</b>
+
+```typescript
+export interface AuditTrailSetup 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [register(auditor)](./kibana-plugin-core-server.audittrailsetup.register.md) | Register a custom [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) implementation. |
+

docs/development/core/server/kibana-plugin-core-server.audittrailsetup.register.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [AuditTrailSetup](./kibana-plugin-core-server.audittrailsetup.md) &gt; [register](./kibana-plugin-core-server.audittrailsetup.register.md)
+
+## AuditTrailSetup.register() method
+
+Register a custom [AuditorFactory](./kibana-plugin-core-server.auditorfactory.md) implementation.
+
+<b>Signature:</b>
+
+```typescript
+register(auditor: AuditorFactory): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  auditor | <code>AuditorFactory</code> |  |
+
+<b>Returns:</b>
+
+`void`
+