From d0c6e7de84d40c80677747b96dbd3fdfe496866d Mon Sep 17 00:00:00 2001 From: Joe Portner <5295965+jportner@users.noreply.github.com> Date: Wed, 29 Jan 2020 12:59:50 -0500 Subject: [PATCH] Clarify documentation for TLS encryption setup (#55739) --- docs/setup/settings.asciidoc | 137 +++++++------- .../monitoring/monitoring-kibana.asciidoc | 29 +-- .../elasticsearch-mutual-tls.asciidoc | 130 +++++++++---- .../securing-communications/index.asciidoc | 174 ++++++++++++------ 4 files changed, 281 insertions(+), 189 deletions(-) diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 6fdb81c780a7d..3212cdfafd876 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -42,9 +42,10 @@ when `csp.strict` is enabled. to Elasticsearch. Any custom headers cannot be overwritten by client-side headers, regardless of the `elasticsearch.requestHeadersWhitelist` configuration. -`elasticsearch.hosts:`:: *Default: "http://localhost:9200"* The URLs of the -Elasticsearch instances to use for all your queries. All nodes listed here must -be on the same cluster. +`elasticsearch.hosts:`:: *Default: `[ "http://localhost:9200" ]`* The URLs of the {es} instances to use for all your queries. All nodes +listed here must be on the same cluster. ++ +To enable SSL/TLS for outbound connections to {es}, use the `https` protocol in this setting. `elasticsearch.logQueries:`:: *Default: `false`* Logs queries sent to Elasticsearch. Requires `logging.verbose` set to `true`. This is useful for @@ -82,52 +83,59 @@ Elasticsearch nodes on startup. `elasticsearch.sniffOnConnectionFault:`:: *Default: false* Update the list of Elasticsearch nodes immediately following a connection fault. -`elasticsearch.ssl.alwaysPresentCertificate:`:: *Default: false* Controls whether to always present the certificate specified by -`elasticsearch.ssl.certificate` or `elasticsearch.ssl.keystore.path` when requested. This setting applies to all requests to Elasticsearch, -including requests that are proxied for end users. Setting this to `true` when Elasticsearch is using certificates to authenticate users can -lead to proxied requests for end users being executed as the identity tied to the configured certificate. +`elasticsearch.ssl.alwaysPresentCertificate:`:: *Default: false* Controls {kib}'s behavior in regard to presenting a client certificate when +requested by {es}. This setting applies to all outbound SSL/TLS connections to {es}, including requests that are proxied for end users. ++ +WARNING: If {es} uses certificates to authenticate end users with a PKI realm and `elasticsearch.ssl.alwaysPresentCertificate` is `true`, +proxied requests may be executed as the identity that is tied to the {kib} server. -`elasticsearch.ssl.certificate:` and `elasticsearch.ssl.key:`:: Paths to a PEM-encoded X.509 certificate and its private key, respectively. -When `xpack.security.http.ssl.client_authentication` in Elasticsearch is set to `required` or `optional`, the certificate and key are used -to prove Kibana's identity when it makes an outbound request to your Elasticsearch cluster. +`elasticsearch.ssl.certificate:` and `elasticsearch.ssl.key:`:: Paths to a PEM-encoded X.509 client certificate and its corresponding +private key. These are used by {kib} to authenticate itself when making outbound SSL/TLS connections to {es}. For this setting to take +effect, the `xpack.security.http.ssl.client_authentication` setting in {es} must be also be set to `"required"` or `"optional"` to request a +client certificate from {kib}. + --- NOTE: These settings cannot be used in conjunction with `elasticsearch.ssl.keystore.path`. --- -`elasticsearch.ssl.certificateAuthorities:`:: Paths to one or more PEM-encoded X.509 certificates. These certificates may consist of a root -certificate authority (CA), and one or more intermediate CAs, which make up a trusted certificate chain for Kibana. This chain is used to -establish trust when Kibana creates an SSL connection with your Elasticsearch cluster. In addition to this setting, trusted certificates may -be specified via `elasticsearch.ssl.keystore.path` and/or `elasticsearch.ssl.truststore.path`. +`elasticsearch.ssl.certificateAuthorities:`:: Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates which make up a +trusted certificate chain for {es}. This chain is used by {kib} to establish trust when making outbound SSL/TLS connections to {es}. ++ +In addition to this setting, trusted certificates may be specified via `elasticsearch.ssl.keystore.path` and/or +`elasticsearch.ssl.truststore.path`. -`elasticsearch.ssl.keyPassphrase:`:: The passphrase that will be used to decrypt the private key that is specified via +`elasticsearch.ssl.keyPassphrase:`:: The password that will be used to decrypt the private key that is specified via `elasticsearch.ssl.key`. This value is optional, as the key may not be encrypted. -`elasticsearch.ssl.keystore.path:`:: Path to a PKCS #12 file that contains an X.509 certificate with its private key. When -`xpack.security.http.ssl.client_authentication` in Elasticsearch is set to `required` or `optional`, the certificate and key are used to -prove Kibana's identity when it makes an outbound request to your Elasticsearch cluster. If the file contains any additional certificates, -those will be used as a trusted certificate chain for your Elasticsearch cluster. This chain is used to establish trust when Kibana creates -an SSL connection with your Elasticsearch cluster. In addition to this setting, trusted certificates may be specified via -`elasticsearch.ssl.certificateAuthorities` and/or `elasticsearch.ssl.truststore.path`. +`elasticsearch.ssl.keystore.path:`:: Path to a PKCS#12 keystore that contains an X.509 client certificate and its corresponding private key. +These are used by {kib} to authenticate itself when making outbound SSL/TLS connections to {es}. For this setting to take effect, the +`xpack.security.http.ssl.client_authentication` setting in {es} must also be set to `"required"` or `"optional"` to request a client +certificate from {kib}. + -- +If the keystore contains any additional certificates, those will be used as a trusted certificate chain for {es}. This chain is used by +{kib} to establish trust when making outbound SSL/TLS connections to {es}. In addition to this setting, trusted certificates may be +specified via `elasticsearch.ssl.certificateAuthorities` and/or `elasticsearch.ssl.truststore.path`. + NOTE: This setting cannot be used in conjunction with `elasticsearch.ssl.certificate` or `elasticsearch.ssl.key`. -- -`elasticsearch.ssl.keystore.password:`:: The password that will be used to decrypt the key store and its private key. If your key store has -no password, leave this unset. If your key store has an empty password, set this to `""`. +`elasticsearch.ssl.keystore.password:`:: The password that will be used to decrypt the keystore that is specified via +`elasticsearch.ssl.keystore.path`. If the keystore has no password, leave this unset. If the keystore has an empty password, set this to +`""`. -`elasticsearch.ssl.truststore.path:`:: Path to a PKCS #12 trust store that contains one or more X.509 certificates. This may consist of a -root certificate authority (CA) and one or more intermediate CAs, which make up a trusted certificate chain for your Elasticsearch cluster. -This chain is used to establish trust when Kibana creates an SSL connection with your Elasticsearch cluster. In addition to this setting, -trusted certificates may be specified via `elasticsearch.ssl.certificateAuthorities` and/or `elasticsearch.ssl.keystore.path`. +`elasticsearch.ssl.truststore.path:`:: Path to a PKCS#12 trust store that contains one or more X.509 certificate authority (CA) certificates +which make up a trusted certificate chain for {es}. This chain is used by {kib} to establish trust when making outbound SSL/TLS connections +to {es}. ++ +In addition to this setting, trusted certificates may be specified via `elasticsearch.ssl.certificateAuthorities` and/or +`elasticsearch.ssl.keystore.path`. -`elasticsearch.ssl.truststore.password:`:: The password that will be used to decrypt the trust store. If your trust store has no password, -leave this unset. If your trust store has an empty password, set this to `""`. +`elasticsearch.ssl.truststore.password:`:: The password that will be used to decrypt the trust store specified via +`elasticsearch.ssl.truststore.path`. If the trust store has no password, leave this unset. If the trust store has an empty password, set +this to `""`. -`elasticsearch.ssl.verificationMode:`:: *Default: full* Controls the verification of certificates presented by Elasticsearch. Valid values -are `none`, `certificate`, and `full`. `full` performs hostname verification and `certificate` does not. This setting is used only when -traffic to Elasticsearch is encrypted, which is specified by using the HTTPS protocol in `elasticsearch.hosts`. +`elasticsearch.ssl.verificationMode:`:: *Default: `"full"`* Controls the verification of the server certificate that {kib} receives when +making an outbound SSL/TLS connection to {es}. Valid values are `"full"`, `"certificate"`, and `"none"`. Using `"full"` will perform +hostname verification, using `"certificate"` will skip hostname verification, and using `"none"` will skip verification entirely. `elasticsearch.startupTimeout:`:: *Default: 5000* Time in milliseconds to wait for Elasticsearch at Kibana startup before retrying. @@ -348,58 +356,57 @@ default is `true`. `server.socketTimeout:`:: *Default: "120000"* The number of milliseconds to wait before closing an inactive socket. -`server.ssl.certificate:` and `server.ssl.key:`:: Paths to a PEM-encoded X.509 certificate and its private key, respectively. These are used -when enabling SSL for inbound requests from web browsers to the Kibana server. +`server.ssl.certificate:` and `server.ssl.key:`:: Paths to a PEM-encoded X.509 server certificate and its corresponding private key. These +are used by {kib} to establish trust when receiving inbound SSL/TLS connections from end users. + --- NOTE: These settings cannot be used in conjunction with `server.ssl.keystore.path`. --- -`server.ssl.certificateAuthorities:`:: Paths to one or more PEM-encoded X.509 certificates. These certificates may consist of a root -certificate authority (CA) and one or more intermediate CAs, which make up a trusted certificate chain for Kibana. This chain is used when a -web browser creates an SSL connection with the Kibana server; the certificate chain is sent to the browser along with the end-entity -certificate to establish trust. This chain is also used to determine whether client certificates should be trusted when PKI authentication -is enabled. In addition to this setting, trusted certificates may be specified via `server.ssl.keystore.path` and/or -`server.ssl.truststore.path`. +`server.ssl.certificateAuthorities:`:: Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates which make up a +trusted certificate chain for {kib}. This chain is used by {kib} to establish trust when receiving inbound SSL/TLS connections from end +users. If PKI authentication is enabled, this chain is also used by {kib} to verify client certificates from end users. ++ +In addition to this setting, trusted certificates may be specified via `server.ssl.keystore.path` and/or `server.ssl.truststore.path`. `server.ssl.cipherSuites:`:: *Default: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-GCM-SHA384, DHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, DHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, DHE-RSA-AES256-SHA384, ECDHE-RSA-AES256-SHA256, DHE-RSA-AES256-SHA256, HIGH,!aNULL, !eNULL, !EXPORT, !DES, !RC4, !MD5, !PSK, !SRP, !CAMELLIA*. Details on the format, and the valid options, are available via the https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT[OpenSSL cipher list format documentation]. -`server.ssl.clientAuthentication:`:: *Default: none* Controls the server’s behavior in regard to requesting a certificate from client -connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` -requests a client certificate but the client is not required to present one. +`server.ssl.clientAuthentication:`:: *Default: `"none"`* Controls {kib}’s behavior in regard to requesting a certificate from client +connections. Valid values are `"required"`, `"optional"`, and `"none"`. Using `"required"` will refuse to establish the connection unless a +client presents a certificate, using `"optional"` will allow a client to present a certificate if it has one, and using `"none"` will +prevent a client from presenting a certificate. -`server.ssl.enabled:`:: *Default: "false"* Enables SSL for inbound requests from the browser to the Kibana server. When set to `true`, a -certificate and private key must be provided. These can be specified via `server.ssl.keystore.path` or the combination of +`server.ssl.enabled:`:: *Default: `false`* Enables SSL/TLS for inbound connections to {kib}. When set to `true`, a certificate and its +corresponding private key must be provided. These can be specified via `server.ssl.keystore.path` or the combination of `server.ssl.certificate` and `server.ssl.key`. -`server.ssl.keyPassphrase:`:: The passphrase that will be used to decrypt the private key that is specified via `server.ssl.key`. This value +`server.ssl.keyPassphrase:`:: The password that will be used to decrypt the private key that is specified via `server.ssl.key`. This value is optional, as the key may not be encrypted. -`server.ssl.keystore.path:`:: Path to a PKCS #12 file that contains an X.509 certificate with its private key. These are used when enabling -SSL for inbound requests from web browsers to the Kibana server. If the file contains any additional certificates, those will be used as a -trusted certificate chain for Kibana. This chain is used when a web browser creates an SSL connection with the Kibana server; the -certificate chain is sent to the browser along with the end-entity certificate to establish trust. This chain is also used to determine -whether client certificates should be trusted when PKI authentication is enabled. In addition to this setting, trusted certificates may be -specified via `server.ssl.certificateAuthorities` and/or `server.ssl.truststore.path`. +`server.ssl.keystore.path:`:: Path to a PKCS#12 keystore that contains an X.509 server certificate and its corresponding private key. If the +keystore contains any additional certificates, those will be used as a trusted certificate chain for {kib}. All of these are used by {kib} +to establish trust when receiving inbound SSL/TLS connections from end users. The certificate chain is also used by {kib} to verify client +certificates from end users when PKI authentication is enabled. + -- +In addition to this setting, trusted certificates may be specified via `server.ssl.certificateAuthorities` and/or +`server.ssl.truststore.path`. + NOTE: This setting cannot be used in conjunction with `server.ssl.certificate` or `server.ssl.key`. -- -`server.ssl.keystore.password:`:: The password that will be used to decrypt the key store and its private key. If your key store has no -password, leave this unset. If your key store has an empty password, set this to `""`. +`server.ssl.keystore.password:`:: The password that will be used to decrypt the keystore specified via `server.ssl.keystore.path`. If the +keystore has no password, leave this unset. If the keystore has an empty password, set this to `""`. -`server.ssl.truststore.path:`:: Path to a PKCS #12 trust store that contains one or more X.509 certificates. These certificates may consist -of a root certificate authority (CA) and one or more intermediate CAs, which make up a trusted certificate chain for Kibana. This chain is -used when a web browser creates an SSL connection with the Kibana server; the certificate chain is sent to the browser along with the -end-entity certificate to establish trust. This chain is also used to determine whether client certificates should be trusted when PKI -authentication is enabled. In addition to this setting, trusted certificates may be specified via `server.ssl.certificateAuthorities` and/or +`server.ssl.truststore.path:`:: Path to a PKCS#12 trust store that contains one or more X.509 certificate authority (CA) certificates which +make up a trusted certificate chain for {kib}. This chain is used by {kib} to establish trust when receiving inbound SSL/TLS connections +from end users. If PKI authentication is enabled, this chain is also used by {kib} to verify client certificates from end users. ++ +In addition to this setting, trusted certificates may be specified via `server.ssl.certificateAuthorities` and/or `server.ssl.keystore.path`. -`server.ssl.truststore.password:`:: The password that will be used to decrypt the trust store. If your trust store has no password, leave -this unset. If your trust store has an empty password, set this to `""`. +`server.ssl.truststore.password:`:: The password that will be used to decrypt the trust store specified via `server.ssl.truststore.path`. If +the trust store has no password, leave this unset. If the trust store has an empty password, set this to `""`. `server.ssl.redirectHttpFromPort:`:: Kibana will bind to this port and redirect all http requests to https over the port configured as `server.port`. diff --git a/docs/user/monitoring/monitoring-kibana.asciidoc b/docs/user/monitoring/monitoring-kibana.asciidoc index b5d263aed8346..d0f2bd6acd901 100644 --- a/docs/user/monitoring/monitoring-kibana.asciidoc +++ b/docs/user/monitoring/monitoring-kibana.asciidoc @@ -93,34 +93,7 @@ valid user ID and password in the `elasticsearch.username` and `elasticsearch.password` settings in the `kibana.yml` file. These values are used when {kib} sends monitoring data to the production cluster. -.. Configure {kib} to encrypt communications between the {kib} server and the -production cluster. This set up involves generating a server certificate and -setting `server.ssl.*` and `elasticsearch.ssl.certificateAuthorities` settings -in the `kibana.yml` file on the {kib} server. For example, using a PEM-formatted -certificate and private key: -+ --- -[source,yaml] --------------------------------------------------------------------------------- -server.ssl.key: /path/to/your/server.key -server.ssl.certificate: /path/to/your/server.crt --------------------------------------------------------------------------------- - -If you are using your own certificate authority (CA) to sign certificates, -specify the location of the PEM file in the `kibana.yml` file: - -[source,yaml] --------------------------------------------------------------------------------- -elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem --------------------------------------------------------------------------------- - -NOTE: Alternatively, the PKCS #12 format can be used for the Kibana certificate -and key, along with any included CA certificates, by setting -`server.ssl.keystore.path`. If your CA certificate chain is in a separate trust -store, you can also use `server.ssl.truststore.path`. - -For more information, see <>. --- +.. <>. . <>. diff --git a/docs/user/security/securing-communications/elasticsearch-mutual-tls.asciidoc b/docs/user/security/securing-communications/elasticsearch-mutual-tls.asciidoc index 1c7e7080e676b..8d64a0e6e0c11 100644 --- a/docs/user/security/securing-communications/elasticsearch-mutual-tls.asciidoc +++ b/docs/user/security/securing-communications/elasticsearch-mutual-tls.asciidoc @@ -5,70 +5,90 @@ Mutual TLS with {es} ++++ -In a standard Transport Layer Security (TLS/SSL) configuration, the server presents a signed certificate to authenticate itself to the -client. In a mutual TLS configuration, the client also presents a signed certificate to authenticate itself to the server. +Secure Sockets Layer (SSL) and Transport Layer Security (TLS) provide encryption for data-in-transit. While these terms are often used +interchangeably, {kib} supports only TLS, which supersedes the old SSL protocols. -When {security} is enabled on your cluster, each request that {kib} makes to {es} must be authenticated. Most requests made through {kib} to -{es} are authenticated by using the credentials of the logged-in user. There are, however, a few internal requests that the {kib} server -needs to make to the {es} cluster. For this reason, you must configure credentials for the {kib} server to use for those requests. +TLS requires X.509 certificates to authenticate the communicating parties and perform encryption of data-in-transit. Each certificate +contains a public key and has and an associated -- but separate -- private key; these keys are used for cryptographic operations. {kib} +supports certificates and private keys in PEM or PKCS#12 format. + +In a standard TLS configuration, the server presents a signed certificate to authenticate itself to the client. In a mutual TLS +configuration, the client also presents a signed certificate to authenticate itself to the server. + +When {es} {security-features} is enabled on your cluster, each request that {kib} (the client) makes to {es} (the server) must be +authenticated. Most requests made by end users through {kib} to {es} are authenticated by using the credentials of the logged-in user. There +are, however, a few internal requests that {kib} needs to make to {es}. For this reason, you must configure credentials for {kib} to use for +those requests. If {kib} has `elasticsearch.username` and `elasticsearch.password` configured, it will attempt to use these to authenticate to {es} via the -{ref}/native-realm.html[Native realm]. However, {kib} also supports mutual TLS authentication with {es} via a {ref}/pki-realm.html[Public +{ref}/native-realm.html[native realm]. However, {kib} also supports mutual TLS authentication with {es} via a {ref}/pki-realm.html[Public Key Infrastructure (PKI) realm]. To do so, {es} needs to verify the signature on the {kib} client certificate, and it also needs to map the -certificate's distinguished name (DN) to the appropriate `kibana_system` role. +client certificate's distinguished name (DN) to the appropriate `kibana_system` role. NOTE: Using a PKI realm is a gold feature. For a comparison of the Elastic license levels, see https://www.elastic.co/subscriptions[the subscription page]. To configure {kib} and {es} to use mutual TLS authentication: -. <> with a username and password. +. <>. -. <>. At a minimum, this requires a server certificate for {es}. +. <>. ++ +This entails generating a "server certificate" for {es} to use on the HTTP layer. -. Create a client certificate and private key for {kib} to use when connecting to {es}. -+ +. Obtain a client certificate and private key for {kib}. ++ -- +{kib} must this "client certificate" and corresponding private key when connecting to {es}. + NOTE: This is not the same as the <> that {kib} will present to web browsers. -You may choose to generate a certificate and private key using {ref}/certutil.html[the {es} certutil tool]. At this point, you will have -already set up a certificate authority (CA) to sign the {es} server certificate. You may choose to use the same CA to sign the {kib} client -certificate. You would do this like so: +You may choose to generate a client certificate and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool. If you +followed the {es} documentation for {ref}/configuring-tls.html#node-certificates[generating node certificates], then you likely have already +set up a certificate authority (CA) to sign the {es} server certificate. You may choose to use the same CA to sign the {kib} client +certificate. For example: [source,sh] -------------------------------------------------------------------------------- -bin/elasticsearch-certutil cert -ca elastic-stack-ca.p12 -name kibana-client +bin/elasticsearch-certutil cert -ca elastic-stack-ca.p12 -name kibana-client -dns -------------------------------------------------------------------------------- -This will generate a certificate and private key in a PKCS #12 keystore named `kibana-client.p12`. The certificate has a Common Name (CN) of -"kibana-client". +This will generate a client certificate and private key in a PKCS#12 file named `kibana-client.p12`. In this example, the client certificate +has a Common Name (CN) of `"kibana-client"` and a subject alternative name (SAN) of `""`. The SAN may be required if +you have hostname verification enabled on {es}. +-- + +. Obtain the certificate authority (CA) certificate chain for {kib}. ++ +-- +{es} needs the appropriate CA certificate chain to properly establish trust when receiving connections from {kib}. -You will also need to use the CA certificate when setting up the PKI realm in {es}. While you could use the CA keystore in the above example -for this purpose, it is bad practice to expose the CA's private key in such a manner. Instead, you can extract the CA certificate (without -its private key) like so: +If you followed the instructions above to generate a client certificate, then you will have a PKCS#12 file for {kib}. You can extract the CA +certificate chain from this file. For example: [source,sh] -------------------------------------------------------------------------------- -openssl pkcs12 -in kibana-client.p12 -cacerts -nokeys -out ca.crt +openssl pkcs12 -in kibana-client.p12 -cacerts -nokeys -out kibana-ca.crt -------------------------------------------------------------------------------- + +This will produce a PEM-formatted file named `kibana-ca.crt` that contains the CA certificate from the PKCS#12 file. -- -. Configure a PKI realm and a Native realm in your {es} cluster: +. Configure {es} with a PKI realm and a native realm. + -- -By default, {es} provides a Native realm. However, to support both a PKI realm (for {kib}) and a Native realm (for end users), you must -configure each realm in `elasticsearch.yml`: +By default, {es} provides a native realm for authenticating with a username and password. However, to support both a PKI realm (for {kib}) +and a native realm (for end users), you must configure each realm in `elasticsearch.yml`: [source,yaml] -------------------------------------------------------------------------------- xpack.security.authc.realms.pki.realm1.order: 1 -xpack.security.authc.realms.pki.realm1.certificate_authorities: "/path/to/ca.crt" +xpack.security.authc.realms.pki.realm1.certificate_authorities: "/path/to/kibana-ca.crt" xpack.security.authc.realms.native.realm2.order: 2 -------------------------------------------------------------------------------- - -- -. Configure your {es} cluster to request client certificates: +. Configure {es} to request client certificates. + -- By default, {es} will not request a client certificate when establishing a TLS connection. To change this, you must set up optional client @@ -80,9 +100,9 @@ xpack.security.http.ssl.client_authentication: "optional" -------------------------------------------------------------------------------- -- -. Restart your {es} cluster. +. Restart {es}. -. Use {kib} to create a <> for your new client certificate: +. Use {kib} to create a role mapping in {es} for the client certificate. + -- This role mapping will assign the `kibana_system` role to any user that matches the included mapping rule, which is set to equal the client @@ -90,31 +110,61 @@ certificate's DN attribute: [role="screenshot"] image:user/security/images/mutual-tls-role-mapping.png["Role mapping for the {kib} client certificate"] + +For more information, see <>. -- -. Configure {kib} to use the client certificate: +. Configure {kib} to use the client certificate and private key. ++ +You need to specify the information required to access your client certificate and corresponding private key. + +.. If your certificate and private key are contained in a PKCS#12 file: + -- -Assuming you used the {es} certutil tool to generate a certificate and private key in a PKCS #12 keystore, add the following values to -`kibana.yml`: +Specify your PKCS#12 file in `kibana.yml`: [source,yaml] -------------------------------------------------------------------------------- elasticsearch.ssl.keystore.path: "/path/to/kibana-client.p12" -elasticsearch.ssl.keystore.password: "decryption password" -------------------------------------------------------------------------------- -The decryption password should match what you entered when prompted by the {es} certutil tool. +If your PKCS#12 file is encrypted, add the decryption password to your <>: + +[source,yaml] +-------------------------------------------------------------------------------- +bin/kibana-keystore add elasticsearch.ssl.keystore.password +-------------------------------------------------------------------------------- + +TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set +`elasticsearch.ssl.keystore.password` to an empty string. +-- + +.. Otherwise, if your certificate and private key are in PEM format: ++ +-- +Specify your certificate and private key in `kibana.yml`: + +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.ssl.certificate: "/path/to/kibana-client.crt" +elasticsearch.ssl.key: "/path/to/kibana-client.key" +-------------------------------------------------------------------------------- -You must also remove the `elasticsearch.username` and `elasticsearch.password` values from the configuration file. Otherwise, {kib} will -attempt to use those to authenticate via the Native realm. +If your private key is encrypted, add the decryption password to your <>: -TIP: Alternatively, {kib} also supports using a client certificate and private key in PEM format with the `elasticsearch.ssl.certificate` -and `elasticsearch.ssl.key` settings. For more information, see <>. +[source,yaml] +-------------------------------------------------------------------------------- +bin/kibana-keystore add elasticsearch.ssl.keyPassphrase +-------------------------------------------------------------------------------- -- +. Configure {kib} _not_ to use a username and password for {es}. ++ +You must remove the `elasticsearch.username` and `elasticsearch.password` settings from `kibana.yml`. If these are present, {kib} will +attempt to use them to authenticate to {es} via the native realm. + . Restart {kib}. NOTE: The steps above enable {kib} to authenticate to {es} using a certificate. However, end users will only be able to authenticate to -{kib} with a username and password. To allow end users to authenticate to {kib} using certificates, see <>. +{kib} with a username and password. To allow end users to authenticate to {kib} using a client certificate, see <>. diff --git a/docs/user/security/securing-communications/index.asciidoc b/docs/user/security/securing-communications/index.asciidoc index 3e022315a4d84..2ac08a4fab5ee 100644 --- a/docs/user/security/securing-communications/index.asciidoc +++ b/docs/user/security/securing-communications/index.asciidoc @@ -4,127 +4,189 @@ Encrypting communications ++++ -{kib} supports Transport Layer Security (TLS/SSL) encryption for all forms of -data-in-transit. Browsers send traffic to {kib} and {kib} sends traffic to {es}. -These communications are configured separately. +Secure Sockets Layer (SSL) and Transport Layer Security (TLS) provide encryption for data-in-transit. While these terms are often used +interchangeably, {kib} supports only TLS, which supersedes the old SSL protocols. + +Browsers send traffic to {kib} and {kib} sends traffic to {es}. These communication channels are configured separately to use TLS. + +TLS requires X.509 certificates to authenticate the communicating parties and perform encryption of data-in-transit. Each certificate +contains a public key and has an associated -- but separate -- private key; these keys are used for cryptographic operations. {kib} +supports certificates and private keys in PEM or PKCS#12 format. [[configuring-tls-browser-kib]] ==== Encrypting traffic between the browser and {kib} -NOTE: You do not need to enable {security-features} for this type of encryption. +NOTE: You do not need to enable the {es} {security-features} for this type of encryption. . Obtain a server certificate and private key for {kib}. + -- -{kib} supports certificates/keys in both PKCS #12 key stores and PEM format. +{kib} will need to use this "server certificate" and corresponding private key when receiving connections from web browsers. -When you obtain a certificate, you must do at least one of the following: +When you obtain a server certificate, you must set its subject alternative name (SAN) correctly to ensure that modern web browsers with +hostname verification will trust it. You can set one or more SANs to the {kib} server's fully-qualified domain name (FQDN), hostname, or IP +address. When choosing the SAN, you should pick whichever attribute you will be using to connect to {kib} in your browser, which is likely +the FQDN. -.. Set the certificate's `subjectAltName` to the hostname, fully-qualified domain name (FQDN), or IP address of the {kib} server. -.. Set the certificate's Common Name (CN) to the {kib} server's hostname or FQDN. Using the server's IP address as the CN does not work. - -You may choose to generate a certificate and private key using {ref}/certutil.html[the {es} certutil tool]. If you already used certutil to -generate a certificate authority (CA), you would generate a certificate/key for Kibana like so (using the `--dns` param to set the -`subjectAltName`): +You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool. +For example: [source,sh] -------------------------------------------------------------------------------- -bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 --name kibana --dns localhost +bin/elasticsearch-certutil csr -name kibana-server -dns some-website.com,www.some-website.com -------------------------------------------------------------------------------- -This will generate a certificate and private key in a PKCS #12 keystore named `kibana.p12`. +This will produce a ZIP archive named `kibana-server.zip`. Extract that archive to obtain the PEM-formatted CSR (`kibana-server.csr`) and +unencrypted private key (`kibana-server.key`). In this example, the CSR has a common name (CN) of `kibana-server`, a SAN of +`some-website.com`, and another SAN of `www.some-website.com`. +NOTE: You will need to use a certificate authority (CA) to sign your CSR to obtain your server certificate. This certificate's signature +will be verified by web browsers that are configured to trust the CA. -- -. Enable TLS/SSL in `kibana.yml`: +. Configure {kib} to access the server certificate and private key. + +.. If your server certificate and private key are in PEM format: + -- +Specify your server certificate and private key in `kibana.yml`: + [source,yaml] -------------------------------------------------------------------------------- -server.ssl.enabled: true +server.ssl.certificate: "/path/to/kibana-server.crt" +server.ssl.key: "/path/to/kibana-server.key" +-------------------------------------------------------------------------------- + +If your private key is encrypted, add the decryption password to your <>: + +[source,yaml] +-------------------------------------------------------------------------------- +bin/kibana-keystore add server.ssl.keyPassphrase -------------------------------------------------------------------------------- -- -. Specify your server certificate and private key in `kibana.yml`: +.. Otherwise, if your server certificate and private key are contained in a PKCS#12 file: + -- -If your certificate and private key are in a PKCS #12 keystore, specify it like so: +Specify your PKCS#12 file in `kibana.yml`: [source,yaml] -------------------------------------------------------------------------------- -server.ssl.keystore.path: "/path/to/your/keystore.p12" -server.ssl.keystore.password: "optional decryption password" +server.ssl.keystore.path: "/path/to/kibana-server.p12" -------------------------------------------------------------------------------- -Otherwise, if your certificate/key are in PEM format, specify them like so: +If your PKCS#12 file is encrypted, add the decryption password to your <>: [source,yaml] -------------------------------------------------------------------------------- -server.ssl.certificate: "/path/to/your/server.crt" -server.ssl.key: "/path/to/your/server.key" -server.ssl.keyPassphrase: "optional decryption password" +bin/kibana-keystore add server.ssl.keystore.password -------------------------------------------------------------------------------- -After making these changes, you must always access {kib} via HTTPS. For example, -https://localhost:5601. +TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set +`server.ssl.keystore.password` to an empty string. +-- -For more information, see <>. ++ +For more information about settings for certificates and keys, see <>. + +. Configure {kib} to enable TLS for inbound connections. ++ +-- +Specify that TLS is used in `kibana.yml`: + +[source,yaml] +-------------------------------------------------------------------------------- +server.ssl.enabled: true +-------------------------------------------------------------------------------- -- +. Restart {kib}. + +After making these changes, you must always access {kib} via HTTPS. For example, https://.com. + [[configuring-tls-kib-es]] ==== Encrypting traffic between {kib} and {es} -NOTE: To perform this step, you must -{ref}/configuring-security.html[enable the {es} {security-features}] or you -must have a proxy that provides an HTTPS endpoint for {es}. +NOTE: To perform this step, you must {ref}/configuring-security.html[enable the {es} {security-features}] or you must have a proxy that +provides an HTTPS endpoint for {es}. + +. {ref}/configuring-tls.html#tls-http[Enable TLS on the HTTP layer in {es}]. + +. Obtain the certificate authority (CA) certificate chain for {es}. ++ +{kib} needs the appropriate CA certificate chain to properly establish trust when connecting to {es}. + +.. If you followed the {es} documentation for {ref}/configuring-tls.html#node-certificates[generating node certificates] and used the +`elasticsearch-certutil http` command, check the `kibana` directory in its output. Depending on what options you chose, the output may +include the CA certificate chain in PEM format. -. Specify the HTTPS URL in the `elasticsearch.hosts` setting in the {kib} -configuration file, `kibana.yml`: +.. Otherwise, you likely have a PKCS#12 file for each your {es} nodes. You can extract the CA certificate chain from one of these files. For +example: + -- -[source,yaml] +[source,sh] -------------------------------------------------------------------------------- -elasticsearch.hosts: ["https://.com:9200"] +openssl pkcs12 -in elastic-certificates.p12 -cacerts -nokeys -out elasticsearch-ca.pem -------------------------------------------------------------------------------- -Using the HTTPS protocol results in a default -`elasticsearch.ssl.verificationMode` option of `full`, which utilizes hostname -verification. +This will produce a PEM-formatted file named `elasticsearch-ca.pem` that contains all CA certificates from the PKCS#12 file. +-- + +. Configure {kib} to trust the {es} CA certificate chain for the HTTP layer. -For more information, see <>. +.. If your CA certificate chain is in PEM format: ++ +-- +Specify one or more CA certificates in `kibana.yml`: + +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.ssl.certificateAuthorities: ["/path/to/elasticsearch-ca.pem"] +-------------------------------------------------------------------------------- -- -. Specify the {es} cluster's CA certificate chain in `kibana.yml`: +.. Otherwise, if your CA certificate chain is contained in a PKCS#12 file: + -- +WARNING: You should not use a PKCS#12 file that contains a private key. This is an unnecessary security risk. If you only have a PKCS#12 +file that contains a private key, a safer approach is to extract the CA certificate chain in PEM format as described above. -If you are using your own CA to sign certificates for {es}, then you need to -specify the CA certificate chain in {kib} to properly establish trust in TLS -connections. If your CA certificate chain is contained in a PKCS #12 trust store, -specify it like so: +Specify your PKCS#12 file in `kibana.yml`: [source,yaml] -------------------------------------------------------------------------------- -elasticsearch.ssl.truststore.path: "/path/to/your/truststore.p12" -elasticsearch.ssl.truststore.password: "optional decryption password" +elasticsearch.ssl.truststore.path: "/path/to/elasticsearch-ca.p12" -------------------------------------------------------------------------------- -Otherwise, if your CA certificate chain is in PEM format, specify each -certificate like so: +If your PKCS#12 file is encrypted, add the decryption password to your <>: [source,yaml] -------------------------------------------------------------------------------- -elasticsearch.ssl.certificateAuthorities: ["/path/to/your/cacert1.pem", "/path/to/your/cacert2.pem"] +bin/kibana-keystore add elasticsearch.ssl.truststore.password +-------------------------------------------------------------------------------- + +TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set +`elasticsearch.ssl.truststore.password` to an empty string. +-- + ++ +For more information about settings for certificates and keys, see <>. + +. Configure {kib} to enable TLS for outbound connections to {es}. ++ +-- +Specify the HTTPS URL for {es} in `kibana.yml`: + +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.hosts: ["https://.com:9200"] -------------------------------------------------------------------------------- -TIP: You can use the {ref}/certutil.html[`elasticsearch-certutil http` command] -to generate a PEM format x.509 certificate for the {es} CA. It also provides -detailed configuration details in readme files. - +NOTE: Using the HTTPS protocol results in a default `elasticsearch.ssl.verificationMode` option of `full`, which utilizes hostname +verification. For more information about this setting, see <>. -- -. (Optional) If the Elastic {monitor-features} are enabled, configure {kib} to -connect to the {es} monitoring cluster via HTTPS. The steps are the same as -above, but each setting is prefixed by `xpack.monitoring.`. For example, `xpack.monitoring.elasticsearch.hosts`, -`xpack.monitoring.elasticsearch.ssl.truststore.path`, etc. +If the Elastic {monitor-features} are enabled and you have set up a separate {es} monitoring cluster, you can also configure {kib} to +connect to the monitoring cluster via HTTPS. The steps are the same as above, but each setting is prefixed by `xpack.monitoring.`. For +example, `xpack.monitoring.elasticsearch.hosts`, `xpack.monitoring.elasticsearch.ssl.truststore.path`, etc.