[Security-in-core] First-class route authorization

[legrego]

Our route authorization feature is not very discoverable today. Engineers have to know:

1. That authorization is something they need to know about
2. When to add authorization to a route
3. How to add authorization to a route (i.e., the cryptic access: tags)

I'd like to propose adding first-class support for route authorization, by exposing an additional set of properties within the route definition. These properties should:

1. Make it clear when routes are opted in/out of authorization
2. Which privileges are required to invoke the route
3. When applicable, describe why a route does not require authorization
4. Provide a mechanism for us to gain visibility into the authorization status of each route

In addition to the security benefits, I wonder if there is an opportunity to expose this information via OAS as well. Having our specification describe the required privileges would be a great DX win, in my opinion.

[elasticmachine]

Pinging @elastic/kibana-core (Team:Core)

[elasticmachine]

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

[pgayvallet]

I'm strongly in favor of this proposal, it would be way better than the current (hacky) way we're doing this with tags in numerous ways, and would be a great step for our security-in-core initiative.

I wonder if there is an opportunity to expose this information via OAS as well. Having our specification describe the required privileges would be a great DX win, in my opinion.

I'm not sure OAS specs have anything directly related to authorization. cc @jloleysens maybe you know better?

[jloleysens]

It is possible to represent some amount of security information at the route (or "operation") level (docs). But I'm guessing we want to capture some information about

"you need roles x:read, y:write and z:admin to access this route."

Which is ES/Kibana specific info. I think this could be auto-appended to route description (under description).

[pgayvallet]

Yeah, my gut feeling was that we would only be able to append something to the description, thanks for confirming.

[elena-shostak]

The RFC has been approved. Implementation will be carried out in the following issues:

• Extend KibanaRouteOptions to Include Security Config with authz Property #191710
• Deprecate authRequired in Favor of security.authc #191711
• Implement Validation Logic for Supported Authz Configurations #191712
• Update registerOnPostAuth Hook for Authorization Checks #191713
• Automatic Generation of Authorization Descriptions in OAS #191714
• Implement ESLint Check for Route Authorization Configuration #191715
• Hardening ApiAction Definition Standards #191716
• Explicitly Restrict API endpoints to Superusers and Operators #196271