feat(security, authc): implement optional "minimal" authentication mode (elastic#251119)

## Summary

This PR introduces a **"minimal" authentication mode** for Kibana HTTP
routes and updates the authentication provider interfaces to pass full
session objects instead of raw provider state.

### Minimal authentication mode

Adds a new `'minimal'` option for `security.authc.enabled` on route
definitions. When a route opts into minimal authentication, Kibana
**skips the Elasticsearch `_authenticate` API call** and instead returns
a lightweight user proxy constructed from session data already stored in
the Kibana session document.

This is useful for high-frequency or performance-sensitive endpoints
where:
- The session has already been fully authenticated on login
- Credential validation will happen naturally when the request reaches
Elasticsearch
- The overhead of an extra `_authenticate` round-trip is unnecessary

The minimal user proxy provides `username`, `authentication_provider`,
`profile_uid`, and `enabled`, but deliberately **throws** if code tries
to access properties that require a real ES authenticate call
(`authentication_realm`, `lookup_realm`, `authentication_type`,
`elastic_cloud_user`).

### Route type system changes

The `RouteAuthc` type is expanded from `AuthcEnabled | AuthcDisabled` to
`AuthcEnabled | AuthcMinimal | AuthcOptional | AuthcDisabled`:

- **`AuthcEnabled`** (`enabled: true`) - full authentication (default,
unchanged)
- **`AuthcMinimal`** (`enabled: 'minimal'`) - new, session-only
authentication, no ES call, requires `reason`
- **`AuthcOptional`** (`enabled: 'optional'`) - existing behavior, now
requires an explicit `reason`
- **`AuthcDisabled`** (`enabled: false`) - no authentication (unchanged)

Both `'minimal'` and `'optional'` now require a `reason` string
explaining why the route deviates from the default. Existing
`'optional'` routes are migrated to the new shape with explicit reasons.

### Provider interface refactoring

All authentication provider methods (`login`, `authenticate`, `logout`)
now receive the full `SessionValue<TState>` object instead of raw
`state`:

- `BaseAuthenticationProvider` becomes generic:
`BaseAuthenticationProvider<TState>`
- `logout(request, state?)` → `logout(request, session?)`
- Providers extract `state` from `session?.state` internally when needed
- The `Authenticator` passes `sessionValue` (not `sessionValue.state`)
to providers
- This gives providers access to session metadata (`username`,
`provider`, `userProfileId`) needed for minimal auth

### Route migrations

Existing routes using `options.authRequired: 'optional'` are migrated to
the new `security.authc` config:

- `GET /api/status` - status endpoint (k8s probes)
- `GET /api/banners/info` - banner info on login page
- `GET /api/custom_branding/info` - custom branding on login page
- `GET /bootstrap-anonymous.js` - anonymous bootstrap script
- `POST /internal/security/analytics/_record_violations` - CSP violation
reports
- `POST /login` - login page view route (reason added)
- Mock IDP plugin routes (testing)

### Integration tests

Every authentication provider (anonymous, basic/token, SAML, OIDC, PKI,
Kerberos) gets a `'should support minimal authentication'` integration
test that:

1. Authenticates and obtains a session cookie via the provider's normal
flow
2. Hits **both** `/authentication/fast/me` (minimal) and
`/internal/security/me` (default)
3. Asserts that `username` and `authentication_provider` match between
both responses
4. Asserts the key behavioral difference: minimal mode does **not**
return `authentication_realm` (since ES `_authenticate` is skipped),
while default mode does

__Assisted by:__ Claude Opus 4.6 (via OpenCode and GitHub Copilot).

Closes elastic#244928

Author: azasypkin

packages/kbn-mock-idp-plugin/server/plugin.ts

@@ -262,7 +262,7 @@ export const plugin: PluginInitializer<void, void, PluginSetupDependencies> = as
             }),
           },
           security: {
-            authc: { enabled: 'optional' },
+            authc: { enabled: 'optional', reason: 'Mock IDP plugin for testing' },
             authz: { enabled: false, reason: 'Mock IDP plugin for testing' },
           },
         },
@@ -312,8 +312,13 @@ export const plugin: PluginInitializer<void, void, PluginSetupDependencies> = as
               credential: schema.string(),
             }),
           },
-          options: { authRequired: 'optional' },
-          security: { authz: { enabled: false, reason: 'Mock IDP plugin for testing' } },
+          security: {
+            authc: {
+              enabled: 'optional',
+              reason: 'Mock IDP plugin for testing UIAM operations',
+            },
+            authz: { enabled: false, reason: 'Mock IDP plugin for testing' },
+          },
         },
         async (context, request, response) => {
           try {
@@ -366,8 +371,13 @@ export const plugin: PluginInitializer<void, void, PluginSetupDependencies> = as
               keys: schema.arrayOf(schema.string(), { minSize: 1 }),
             }),
           },
-          options: { authRequired: 'optional' },
-          security: { authz: { enabled: false, reason: 'Mock IDP plugin for testing' } },
+          security: {
+            authc: {
+              enabled: 'optional',
+              reason: 'Mock IDP plugin for testing UIAM operations',
+            },
+            authz: { enabled: false, reason: 'Mock IDP plugin for testing' },
+          },
         },
         async (context, request, response) => {
           try {

src/core/packages/capabilities/server-internal/src/capabilities_service.test.ts

@@ -59,6 +59,7 @@ describe('CapabilitiesService', () => {
             },
             authc: {
               enabled: 'optional',
+              reason: expect.any(String),
             },
           },
         }),

src/core/packages/capabilities/server-internal/src/routes/resolve_capabilities.ts

@@ -24,6 +24,7 @@ export function registerCapabilitiesRoutes(router: IRouter, resolver: Capabiliti
         },
         authc: {
           enabled: 'optional',
+          reason: 'This route can be accessed by both authenticated and unauthenticated users',
         },
       },
       validate: {

src/core/packages/http/router-server-internal/src/security_route_config_validator.test.ts

@@ -8,7 +8,8 @@
  */
 
 import { validRouteSecurity } from './security_route_config_validator';
-import { ReservedPrivilegesSet } from '@kbn/core-http-server';
+import { ReservedPrivilegesSet, type RouteSecurity } from '@kbn/core-http-server';
+import type { DeepPartial } from '@kbn/utility-types';
 
 describe('RouteSecurity validation', () => {
   it('should pass validation for valid route security with authz enabled and valid required privileges', () => {
@@ -19,6 +20,7 @@ describe('RouteSecurity validation', () => {
         },
         authc: {
           enabled: 'optional',
+          reason: 'some reason',
         },
       })
     ).not.toThrow();
@@ -161,6 +163,40 @@ describe('RouteSecurity validation', () => {
     );
   });
 
+  it('should fail validation when authc is minimal but reason is missing', () => {
+    const routeSecurity = {
+      authz: {
+        requiredPrivileges: ['read'],
+      },
+      authc: {
+        enabled: 'minimal',
+      },
+    };
+
+    expect(() =>
+      validRouteSecurity(routeSecurity as DeepPartial<RouteSecurity>)
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"[authc.reason]: expected value of type [string] but got [undefined]"`
+    );
+  });
+
+  it('should fail validation when authc is optional but reason is missing', () => {
+    const routeSecurity = {
+      authz: {
+        requiredPrivileges: ['read'],
+      },
+      authc: {
+        enabled: 'optional',
+      },
+    };
+
+    expect(() =>
+      validRouteSecurity(routeSecurity as DeepPartial<RouteSecurity>)
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"[authc.reason]: expected value of type [string] but got [undefined]"`
+    );
+  });
+
   it('should fail validation when authc is disabled but reason is missing', () => {
     const routeSecurity = {
       authz: {
@@ -193,6 +229,20 @@ describe('RouteSecurity validation', () => {
     );
   });
 
+  it('should pass validation when authc is minimal', () => {
+    expect(() =>
+      validRouteSecurity({
+        authz: {
+          requiredPrivileges: ['read'],
+        },
+        authc: {
+          enabled: 'minimal',
+          reason: 'some reason',
+        },
+      })
+    ).not.toThrow();
+  });
+
   it('should pass validation when authc is optional', () => {
     expect(() =>
       validRouteSecurity({
@@ -201,6 +251,7 @@ describe('RouteSecurity validation', () => {
         },
         authc: {
           enabled: 'optional',
+          reason: 'some reason',
         },
       })
     ).not.toThrow();

src/core/packages/http/router-server-internal/src/security_route_config_validator.ts

@@ -149,12 +149,17 @@ const authzSchema = schema.object({
 });
 
 const authcSchema = schema.object({
-  enabled: schema.oneOf([schema.literal(true), schema.literal('optional'), schema.literal(false)]),
+  enabled: schema.oneOf([
+    schema.literal(true),
+    schema.literal('optional'),
+    schema.literal('minimal'),
+    schema.literal(false),
+  ]),
   reason: schema.conditional(
     schema.siblingRef('enabled'),
-    schema.literal(false),
-    schema.string(),
-    schema.never()
+    schema.literal(true),
+    schema.never(),
+    schema.string()
   ),
 });
 

src/core/packages/http/router-server-internal/src/versioned_router/core_versioned_route.test.ts

@@ -667,6 +667,7 @@ describe('Versioned route', () => {
       },
       authc: {
         enabled: 'optional',
+        reason: 'some reason',
       },
     };
     const securityConfig2: RouteSecurity = {
@@ -813,6 +814,7 @@ describe('Versioned route', () => {
       },
       authc: {
         enabled: 'optional',
+        reason: 'some reason',
       },
     };
 
@@ -863,6 +865,7 @@ describe('Versioned route', () => {
       },
       authc: {
         enabled: 'optional',
+        reason: 'some reason',
       },
     };
 
@@ -888,7 +891,7 @@ describe('Versioned route', () => {
     // @ts-expect-error for test purpose
     const security = route.getSecurity({ headers: { [ELASTIC_HTTP_VERSION_HEADER]: '1' } });
 
-    expect(security.authc).toEqual({ enabled: 'optional' });
+    expect(security.authc).toEqual({ enabled: 'optional', reason: 'some reason' });
 
     expect(security.authz).toEqual({ requiredPrivileges: ['foo', 'bar'] });
   });

src/core/packages/http/server-internal/src/http_server.test.ts

@@ -2139,7 +2139,7 @@ test('exposes authentication details of incoming request to a route handler', as
       path: '/foo',
       validate: false,
       security: {
-        authc: { enabled: 'optional' },
+        authc: { enabled: 'optional', reason: 'test' },
         authz: { enabled: false, reason: 'test' },
       },
     },
@@ -2181,7 +2181,48 @@ test('exposes authentication details of incoming request to a route handler', as
         tags: [],
         timeout: {},
         security: {
-          authc: { enabled: 'optional' },
+          authc: { enabled: 'optional', reason: 'test' },
+          authz: { enabled: false, reason: 'test' },
+        },
+      },
+    });
+});
+
+test('properly treats minimal authentication as required', async () => {
+  const { registerRouter, registerAuth, server: innerServer } = await server.setup({ config$ });
+
+  const router = new Router('', logger, enhanceWithContext, routerOptions);
+  router.get(
+    {
+      path: '/',
+      validate: false,
+      security: {
+        authc: { enabled: 'minimal', reason: 'test' },
+        authz: { enabled: false, reason: 'test' },
+      },
+    },
+    (context, req, res) => res.ok({ body: req.route })
+  );
+
+  // mocking to have `authRegistered` filed set to true
+  registerAuth((req, res, auth) => auth.authenticated({ state: { alpha: 'beta' } }));
+  registerRouter(router);
+
+  await server.start();
+  await supertest(innerServer.listener)
+    .get('/')
+    .expect(200, {
+      method: 'get',
+      path: '/',
+      routePath: '/',
+      options: {
+        authRequired: true,
+        xsrfRequired: false,
+        access: 'internal',
+        tags: [],
+        timeout: {},
+        security: {
+          authc: { enabled: 'minimal', reason: 'test' },
           authz: { enabled: false, reason: 'test' },
         },
       },

src/core/packages/http/server-internal/src/http_server.ts

@@ -396,11 +396,12 @@ export class HttpServer {
   }
 
   private getAuthOption(
-    authRequired: RouteConfigOptions<any>['authRequired'] = true
+    authRequired: RouteConfigOptions<any>['authRequired'] | 'minimal' = true
   ): undefined | false | { mode: 'required' | 'try' } {
     if (this.authRegistered === false) return undefined;
 
-    if (authRequired === true) {
+    // Minimal authentication still should go through the authentication handler.
+    if (authRequired === true || authRequired === 'minimal') {
       return { mode: 'required' };
     }
     if (authRequired === 'optional') {

src/core/packages/http/server/index.ts

@@ -117,6 +117,8 @@ export type {
   RouteAuthc,
   AuthcDisabled,
   AuthcEnabled,
+  AuthcMinimal,
+  AuthcOptional,
   Privilege,
   PrivilegeSet,
   AllRequiredCondition,

src/core/packages/http/server/src/router/index.ts

@@ -62,6 +62,8 @@ export type {
   RouteAuthc,
   AuthcDisabled,
   AuthcEnabled,
+  AuthcMinimal,
+  AuthcOptional,
   RouteSecurity,
   AllRequiredCondition,
   AnyRequiredCondition,