From 7fa4860e372b0c0cf81afde1cb17b80f4653af86 Mon Sep 17 00:00:00 2001 From: Aleh Zasypkin Date: Fri, 30 Aug 2019 19:33:23 +0200 Subject: [PATCH] Document PKI authentication provider. (#43572) --- docs/security/authentication/index.asciidoc | 31 +++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/security/authentication/index.asciidoc b/docs/security/authentication/index.asciidoc index 19a2f5ec4b3a..1b326c95e20b 100644 --- a/docs/security/authentication/index.asciidoc +++ b/docs/security/authentication/index.asciidoc @@ -9,6 +9,7 @@ - <> - <> +- <> - <> - <> @@ -44,6 +45,36 @@ The token authentication provider can be used in conjunction with the basic auth xpack.security.authc.providers: [token, basic] -------------------------------------------------------------------------------- +[[pki-authentication]] +==== Public Key Infrastructure (PKI) Authentication + +[IMPORTANT] +============================================================================ +PKI authentication will not work if {kib} is hosted behind a TLS termination reverse proxy. In this configuration, {kib} does not have direct access to the client certificates and cannot authenticate the user. +============================================================================ + +PKI authentication allows users to log into {kib} using X.509 client certificates that must be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer, and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on the {es} {ref}/security-api-delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. All subsequent requests to {es} APIs on behalf of users will be authenticated using these access tokens. + +Prior to configuring {kib}, ensure that the PKI realm is enabled in {es} and configured to permit delegation. See {ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information. + +To enable the PKI authentication provider in {kib}, you must first <>. You must also enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into a list of CAs trusted by {kib} in your `kibana.yml`: + +[source,yaml] +-------------------------------------------------------------------------------- +server.ssl.certificateAuthorities: /path/to/your/cacert.pem +server.ssl.clientAuthentication: required +xpack.security.authc.providers: [pki] +-------------------------------------------------------------------------------- + +PKI support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both PKI and Basic authentication for the same {kib} instance: + +[source,yaml] +-------------------------------------------------------------------------------- +xpack.security.authc.providers: [pki, basic] +-------------------------------------------------------------------------------- + +Note that with `server.ssl.clientAuthentication` set to `required`, users are asked to provide a valid client certificate, even if they want to authenticate with username and password. Depending on the security policies, it may or may not be desired. If not, `server.ssl.clientAuthentication` can be set to `optional`. In this case, {kib} still requests a client certificate, but the client won't be required to present one. The `optional` client authentication mode might also be needed in other cases, for example, when PKI authentication is used in conjunction with Reporting. + [[saml]] ==== SAML Single Sign-On