Specify internal and external notes when opting out of route authorization

[legrego]

Routes that out-out of authorization are required to provide a justification for doing so:

kibana/packages/core/http/core-http-server/src/router/route.ts

Lines 178 to 187 in 71c0d75

	/**
	* Describes the state when authorization is disabled.
	*
	* - `enabled`: A boolean indicating that authorization is not enabled (`false`).
	* - `reason`: A string explaining why authorization is disabled.
	*/
	export interface AuthzDisabled {
	enabled: false;
	reason: string;
	}

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

Lines 98 to 106 in 71c0d75

	const authcSchema = schema.object({
	enabled: schema.oneOf([schema.literal(true), schema.literal('optional'), schema.literal(false)]),
	reason: schema.conditional(
	schema.siblingRef('enabled'),
	schema.literal(false),
	schema.string(),
	schema.never()
	),
	});

These justifications are designed for internal consumption, and do not provide value to external API consumers.

We should update this schema to support two types of notes:

1. The internal justification for disabling route authorization (e.g. "Route delegates authorization to the scoped ES Client")
2. An external description that allows the route author to tell consumers the required privileges (e.g. "Route requires read access to the logs-* data stream).

The internal justification should remain a required field.
The new external description should be an optional field.

The new external description should be surfaced in the OAS documentation, similar to what we do for routes that have opted-in to authorization (#197001)

[elasticmachine]

Pinging @elastic/kibana-security (Team:Security)

[jeramysoucy]

@legrego Will this be complete once we update and merge #198334? Or is this intended more as a cross-team meta issue?

[legrego]

Will this be complete once we update and merge #198334? Or is this intended more as a cross-team meta issue?

@jeramysoucy neither. This is tracking an enhancement to the new security.authz interface that we expose on Core's router. It will allow teams to specify both internal and external notes when opting out of route authorization. We currently only support the former.