Security/document audit deprecation (#104685)

docs/settings/security-settings.asciidoc

@@ -337,24 +337,12 @@ For more details and a reference of audit events, refer to <<xpack-security-audi
 [cols="2*<"]
 |======
 | `xpack.security.audit.enabled` {ess-icon}
-| Set to `true` to enable audit logging for security events. *Default:* `false`
-|======
-
-[float]
-[[ecs-audit-logging-settings]]
-==== ECS audit logging settings
-
-To enable the <<xpack-security-ecs-audit-logging, ECS audit logger>>, specify where you want to write the audit events using `xpack.security.audit.appender`.
-
-[cols="2*<,*50"]
-|======
-| `xpack.security.audit.appender`
-| Optional. Specifies where audit logs should be written to and how they should be formatted.
+| Set to `true` _and_ configure an appender with `xpack.security.audit.appender` to enable ECS audit logging`. *Default:* `false`
 
 2+a| For example:
-
 [source,yaml]
 ----------------------------------------
+xpack.security.audit.enabled: true
 xpack.security.audit.appender:
   type: rolling-file
   fileName: ./audit.log
@@ -370,7 +358,31 @@ xpack.security.audit.appender:
 <1> Rotates log files every 24 hours.
 <2> Keeps maximum of 10 log files before deleting older ones.
 
-| `xpack.security.audit.appender.type`
+[NOTE]
+============
+{ess} does not support custom log file policies. To enable audit logging on {ess} only specify:
+
+[source,yaml]
+----------------------------------------
+xpack.security.audit.enabled: true
+xpack.security.audit.appender.type: rolling-file
+----------------------------------------
+============
+
+[NOTE]
+============
+deprecated:[7.15.0,"In 8.0 and later, the legacy audit logger will be removed, and this setting will enable the ECS audit logger with a default appender."] To enable the legacy audit logger only specify:
+
+[source,yaml]
+----------------------------------------
+xpack.security.audit.enabled: true
+----------------------------------------
+============
+
+| `xpack.security.audit.appender` {ess-icon}
+| Optional. Specifies where audit logs should be written to and how they should be formatted.
+
+| `xpack.security.audit.appender.type` {ess-icon}
 | Required. Specifies where audit logs should be written to. Allowed values are `console`, `file`, or `rolling-file`. 
 
 Refer to <<audit-logging-file-appender>> and <<audit-logging-rolling-file-appender>> for appender specific settings.

docs/user/security/audit-logging.asciidoc

@@ -14,16 +14,24 @@ by cluster-wide privileges. For more information on enabling audit logging in
 
 [IMPORTANT]
 ============================================================================
+Kibana offers two audit logs: a **deprecated** legacy audit logger, and a new
+ECS-compliant audit logger. We strongly advise using the <<xpack-security-ecs-audit-logging, ECS audit logger>>,
+as the legacy audit logger will be removed in an upcoming version.
+============================================================================
+
+[NOTE]
+============================================================================
 Audit logs are **disabled** by default. To enable this functionality, you must
-set `xpack.security.audit.enabled` to `true` in `kibana.yml`.
+set `xpack.security.audit.enabled` to `true` in `kibana.yml`, and configure
+an <<audit-logging-settings, appender>> to write the audit log to a location of your choosing.
 ============================================================================
 
-The current version of the audit logger uses the standard {kib} logging output,
+The legacy audit logger uses the standard {kib} logging output,
 which can be configured in `kibana.yml`. For more information, refer to <<settings>>.
-The audit logger uses a separate logger and can be configured using
+The <<xpack-security-ecs-audit-logging, ECS audit logger>> uses a separate logger and can be configured using
 the options in <<audit-logging-settings>>. 
 
-==== Audit event types
+==== Legacy audit event types
 
 When you are auditing security events, each request can generate multiple audit
 events. The following is a list of the events that can be generated:
@@ -42,7 +50,7 @@ events. The following is a list of the events that can be generated:
 ============================================================================
 The following events are only logged if the ECS audit logger is enabled.
 For information on how to configure `xpack.security.audit.appender`, refer to
-<<ecs-audit-logging-settings>>.
+<<audit-logging-settings>>.
 ============================================================================
 
 Refer to the table of events that can be logged for auditing purposes. 

x-pack/plugins/security/server/config_deprecations.test.ts

@@ -165,6 +165,68 @@ describe('Config Deprecations', () => {
     `);
   });
 
+  it('warns when using the legacy audit logger', () => {
+    const config = {
+      xpack: {
+        security: {
+          audit: {
+            enabled: true,
+          },
+        },
+      },
+    };
+    const { messages, migrated } = applyConfigDeprecations(cloneDeep(config));
+    expect(migrated.xpack.security.audit.appender).not.toBeDefined();
+    expect(messages).toMatchInlineSnapshot(`
+      Array [
+        "The legacy audit logger is deprecated in favor of the new ECS-compliant audit logger.",
+      ]
+    `);
+  });
+
+  it('does not warn when using the ECS audit logger', () => {
+    const config = {
+      xpack: {
+        security: {
+          audit: {
+            enabled: true,
+            appender: {
+              type: 'file',
+              fileName: './audit.log',
+            },
+          },
+        },
+      },
+    };
+    const { messages, migrated } = applyConfigDeprecations(cloneDeep(config));
+    expect(migrated).toEqual(config);
+    expect(messages).toHaveLength(0);
+  });
+
+  it('does not warn about using the legacy logger when using the ECS audit logger, even when using the deprecated ECS appender config', () => {
+    const config = {
+      xpack: {
+        security: {
+          audit: {
+            enabled: true,
+            appender: {
+              type: 'file',
+              path: './audit.log',
+            },
+          },
+        },
+      },
+    };
+    const { messages, migrated } = applyConfigDeprecations(cloneDeep(config));
+    expect(migrated.xpack.security.audit.appender.path).not.toBeDefined();
+    expect(migrated.xpack.security.audit.appender.fileName).toEqual('./audit.log');
+    expect(messages).toMatchInlineSnapshot(`
+      Array [
+        "\\"xpack.security.audit.appender.path\\" is deprecated and has been replaced by \\"xpack.security.audit.appender.fileName\\"",
+      ]
+    `);
+  });
+
   it(`warns that 'authorization.legacyFallback.enabled' is unused`, () => {
     const config = {
       xpack: {

x-pack/plugins/security/server/config_deprecations.ts

@@ -21,6 +21,23 @@ export const securityConfigDeprecationProvider: ConfigDeprecationProvider = ({
 
   unused('authorization.legacyFallback.enabled'),
   unused('authc.saml.maxRedirectURLSize'),
+  // Deprecation warning for the legacy audit logger.
+  (settings, fromPath, addDeprecation) => {
+    const auditLoggingEnabled = settings?.xpack?.security?.audit?.enabled ?? false;
+    const legacyAuditLoggerEnabled = !settings?.xpack?.security?.audit?.appender;
+    if (auditLoggingEnabled && legacyAuditLoggerEnabled) {
+      addDeprecation({
+        message: `The legacy audit logger is deprecated in favor of the new ECS-compliant audit logger.`,
+        documentationUrl:
+          'https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-settings',
+        correctiveActions: {
+          manualSteps: [
+            `Declare an audit logger "appender" via "xpack.security.audit.appender" to enable the ECS audit logger.`,
+          ],
+        },
+      });
+    }
+  },
   // Deprecation warning for the old array-based format of `xpack.security.authc.providers`.
   (settings, fromPath, addDeprecation) => {
     if (Array.isArray(settings?.xpack?.security?.authc?.providers)) {