Publish rest API spec for SAML, OIDC and PKI service-provider oriented APIs

[albertzaharovits]

We have a couple of APIs that are not intended to be used by regular clients, i.e. clients that are interested in accessing or administering ES.
The following APIs are low level in the sense that they are used by Kibana, in cases where the responsibilities of authentication flows are divided between Kibana and Elasticsearch. Elasticsearch cannot assume all responsibilities in those cases because it is not a HTTP Server.

Delegate PKI authentication

OpenID Connect Prepare Authentication API
OpenID Connect authenticate API
OpenID Connect logout API

SAML prepare authentication API
SAML authenticate API
SAML logout API
SAML invalidate API
SAML service provider metadata API

In general, a client that calls such APIs takes the role of the smart HTTP proxy to Elasticsearch.

Given the limited use cases of such APIs, we initially made the conscious decision to not publish the REST spec which is the template for language client's request objects. This way, language clients don't expose dedicated methods for low level actions.

But we do document the APIs, and internal APIs such as autoscaling also publish their rest spec.

On consistency grounds, should we backtrack on the original decision, and expose the rest spec for the above APIs?

[elasticmachine]

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

[albertzaharovits]

CC @azasypkin

[azasypkin]

Hey! Have you made any decision on that one already?

[jkakavas]

Hi @azasypkin , we discussed this in a team meeting recently and we agree we need to do this. I will take care of the SAML APIs and @albertzaharovits will write the OIDC APIs specs.