63 lines
2.8 KiB
Plaintext
63 lines
2.8 KiB
Plaintext
|
--
|
||
|
|
:api: delegate-pki
|
||
|
|
:request: DelegatePkiAuthenticationRequest
|
||
|
|
:response: DelegatePkiAuthenticationResponse
|
||
|
|
--
|
||
|
|
|
||
|
|
[id="{upid}-{api}"]
|
||
|
|
=== Delegate PKI Authentication API
|
||
|
|
|
||
|
|
This API is called by *smart* proxies to Elasticsearch, such as Kibana, that
|
||
|
|
terminate the user's TLS session but that still wish to authenticate the user
|
||
|
|
on the Elasticsearch side using a PKI realm, which normally requires users to
|
||
|
|
authenticate over TLS directly to Elasticsearch. It implements the exchange of
|
||
|
|
the client's {@code X509Certificate} chain from the TLS authentication into an
|
||
|
|
Elasticsearch access token.
|
||
|
|
|
||
|
|
IMPORTANT: The association between the subject public key in the target
|
||
|
|
certificate and the corresponding private key is *not* validated. This is part
|
||
|
|
of the TLS authentication process and it is delegated to the proxy calling this
|
||
|
|
API. The proxy is *trusted* to have performed the TLS authentication, and this
|
||
|
|
API translates that authentication into an Elasticsearch access token.
|
||
|
|
|
||
|
|
[id="{upid}-{api}-request"]
|
||
|
|
==== Delegate PKI Authentication Request
|
||
|
|
|
||
|
|
The request contains the client's {@code X509Certificate} chain. The
|
||
|
|
certificate chain is represented as a list where the first element is the
|
||
|
|
target certificate containing the subject distinguished name that is requesting
|
||
|
|
access. This may be followed by additional certificates, with each subsequent
|
||
|
|
certificate being the one used to certify the previous one. The certificate
|
||
|
|
chain is validated according to RFC 5280, by sequentially considering the trust
|
||
|
|
configuration of every installed {@code PkiRealm} that has {@code
|
||
|
|
PkiRealmSettings#DELEGATION_ENABLED_SETTING} set to {@code true} (default is
|
||
|
|
{@code false}). A successfully trusted target certificate is also subject to
|
||
|
|
the validation of the subject distinguished name according to that respective's
|
||
|
|
realm {@code PkiRealmSettings#USERNAME_PATTERN_SETTING}.
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SecurityDocumentationIT.java[delegate-pki-request]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
include::../execution.asciidoc[]
|
||
|
|
|
||
|
|
[id="{upid}-{api}-response"]
|
||
|
|
==== Delegate PKI Authentication Response
|
||
|
|
|
||
|
|
The returned +{response}+ contains the following properties:
|
||
|
|
|
||
|
|
`accessToken`:: This is the newly created access token.
|
||
|
|
It can be used to authenticate to the Elasticsearch cluster.
|
||
|
|
`type`:: The type of the token, this is always `"Bearer"`.
|
||
|
|
`expiresIn`:: The length of time (in seconds) until the token will expire.
|
||
|
|
The token will be considered invalid after that time.
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SecurityDocumentationIT.java[delegate-pki-response]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The `accessToken` can be used to authentication to Elasticsearch.
|
||
|
|
|
||
|
|
|