Reference DOCS for proxied PKI

[albertzaharovits]

This commit contains the reference docs (xpack/docs) for the proxied PKI. Specifically, this contains PKI realm configuration instructions for delegation in x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc and docs for the newly introduced API in x-pack/docs/en/rest-api/security/delegate-pki-authentication.asciidoc

Stack overview docs are in another repo so there will be a follow-up PR. But, I am thinking to add them after Kibana also has a sketch of their docs, so I can link to them from Stack overview.

Relates #34396

[elasticmachine]

Pinging @elastic/es-docs

[elasticmachine]

Pinging @elastic/es-security

[lcawl]

It is unclear to me from the placement of the "only" what is prohibited here. Is one of these right?:

If clients must be authenticated by PKI in order to connect directly to {es} ...

If PKI authentication is required only by clients connecting directly to {es}...

[albertzaharovits]

Neither 🤦‍♂
I've rephrased it as:

IMPORTANT: You must enable SSL/TLS and enable client authentication, if you
only allow PKI authentication for clients connecting directly to {es}, but not
through {kib}.

[albertzaharovits]

@bizybot With the exception of the proposed new section for authz in the delegated use case I have made all the changes suggested. I wanted users reading this to remain with the idea that authz is the same in the delegated use case (even though it is possible to distinguish such delegated users) and I feel that a separate section goes against it. Hope this is OK with you. I don't feel strongly about it.

[bizybot]

LGTM, Thank you.

[tvernum]

When the Kibana docs exist, we should link to them here.

[azasypkin]

@albertzaharovits relevant Kibana docs are live now :) https://www.elastic.co/guide/en/kibana/7.4/kibana-authentication.html#pki-authentication

[tvernum]

Isn't this example backwards (or am I confused?)
This is saying:
The user has the "role_for_pki1_direct" role if they are authenticated by the "pki1" realm, unless they have a null delegation
That unless should be an and shouldn't it?

[albertzaharovits]

Oops, you're right! This is what I've changed it to:

{
  "roles" : [ "role_for_pki1_direct" ],
  "rules" : {
    "all": [
      {
        "field": {"realm.name": "pki1"}
      },
      {
        "field": {
          "metadata.pki_delegated_by_user": null <1>
        }
      }
    ]
  },
  "enabled": true
}

[tvernum]

True, but... if anonymous is enabled then all users have the anonymous role, so this sentence might confuse someone.
Perhaps, we need another NOTE (though I worry about overwhelming people with so many notes, so maybe just a regular sentence) that if anonymous is enabled, all users receive that role in addition to their mapped roles.

[albertzaharovits]

Nice catch! I did add another note:

NOTE: When {ref}/anonymous-access.html[anonymous access] is enabled the roles
of the anonymous user are mapped to all the other users as well.

This is important IMO.

[albertzaharovits]

Done addressing your review Tim! Appreciate it 👍 Please take another look.

[tvernum]

LGTM, with 1 minor bit to fix up.

[albertzaharovits]

@elasticmachine run elasticsearch-ci/bwc

[albertzaharovits]

@elasticmachine run elasticsearch-ci/default-distro

[albertzaharovits]

@elasticmachine run elasticsearch-ci/1