mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
* [DOCS] Adds instructions to extract files from a .p12 keystore * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <5295965+jportner@users.noreply.github.com> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <5295965+jportner@users.noreply.github.com> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <5295965+jportner@users.noreply.github.com> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <5295965+jportner@users.noreply.github.com> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <5295965+jportner@users.noreply.github.com> * Revised section to make it consistent with 7.6 * Format URL so it doesn't appear as a link Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com> Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com>
This commit is contained in:
Melori Arellano
GitHub
parent
95422e6449
commit
9aeda5377d
1 changed files with 97 additions and 88 deletions
|
|
@ -3,122 +3,131 @@
|
|||
++++
|
||||
<titleabbrev>Encrypting communications</titleabbrev>
|
||||
++++
|
||||
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.
|
||||
|
||||
{kib} supports Transport Layer Security (TLS/SSL) encryption for client
|
||||
requests.
|
||||
//TBD: It is unclear what "client requests" are in this context. Is it just
|
||||
// communication between the browser and the Kibana server or are we talking
|
||||
// about other types of clients connecting to the Kibana server?
|
||||
Browsers send traffic to {kib} and {kib} sends traffic to {es}. These communication channels are configured separately to use TLS.
|
||||
|
||||
If you are using {security} or a proxy that provides an HTTPS endpoint for {es},
|
||||
you can configure {kib} to access {es} via HTTPS. Thus, communications between
|
||||
{kib} and {es} are also encrypted.
|
||||
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 format.
|
||||
|
||||
. Configure {kib} to encrypt communications between the browser and the {kib}
|
||||
server:
|
||||
[[configuring-tls-browser-kib]]
|
||||
==== Encrypting traffic between the browser and {kib}
|
||||
|
||||
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}.
|
||||
+
|
||||
--
|
||||
NOTE: You do not need to enable {security} for this type of encryption.
|
||||
{kib} will need to use this "server certificate" and corresponding private key when receiving connections from web browsers.
|
||||
|
||||
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.
|
||||
|
||||
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 csr -name kibana-server -dns some-website.com,www.some-website.com
|
||||
--------------------------------------------------------------------------------
|
||||
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.
|
||||
--
|
||||
|
||||
.. Generate a server certificate for {kib}.
|
||||
. Configure {kib} to access the server certificate and private key.
|
||||
|
||||
.. If your server certificate and private key are in PEM format:
|
||||
+
|
||||
--
|
||||
//TBD: Can we provide more information about how they generate the certificate?
|
||||
//Would they be able to use something like the elasticsearch-certutil command?
|
||||
You must either set the certificate's
|
||||
`subjectAltName` to the hostname, fully-qualified domain name (FQDN), or IP
|
||||
address of the {kib} server, or set the CN to the {kib} server's hostname
|
||||
or FQDN. Using the server's IP address as the CN does not work.
|
||||
Specify your server certificate and private key in `kibana.yml`:
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
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 <<secure-settings,{kib} keystore>>:
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
bin/kibana-keystore add server.ssl.keyPassphrase
|
||||
--------------------------------------------------------------------------------
|
||||
--
|
||||
|
||||
.. Set the `server.ssl.enabled`, `server.ssl.key`, and `server.ssl.certificate`
|
||||
properties in `kibana.yml`:
|
||||
.. Otherwise, if your server certificate and private key are contained in a PKCS#12 file:
|
||||
+
|
||||
--
|
||||
You will need to extract the server certificate and private key in PEM format.
|
||||
[source,shell]
|
||||
----------------------------------------------------------
|
||||
openssl pkcs12 -in kibana-server.p12 -clcerts -nokeys -out kibana-server.crt
|
||||
openssl pkcs12 -in kibana-server.p12 -nocerts -nodes -out kibana-server.key
|
||||
----------------------------------------------------------
|
||||
This will produce a PEM-formatted server certificate (`kibana-server.crt`) and unencrypted private key (`kibana-server.key`). Then, specify
|
||||
these files in `kibana.yml` as described above.
|
||||
--
|
||||
+
|
||||
For more information about settings for certificates and keys, see <<settings,{kib} configuration settings>>.
|
||||
. Configure {kib} to enable TLS for inbound connections.
|
||||
+
|
||||
--
|
||||
Specify that TLS is used in `kibana.yml`:
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
server.ssl.enabled: true
|
||||
server.ssl.key: /path/to/your/server.key
|
||||
server.ssl.certificate: /path/to/your/server.crt
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
After making these changes, you must always access {kib} via HTTPS. For example,
|
||||
https://localhost:5601.
|
||||
|
||||
// TBD: The reference information for server.ssl.enabled says it "enables SSL for
|
||||
// outgoing requests from the Kibana server to the browser". Do we need to
|
||||
// reiterate here that only one side of the communications is encrypted?
|
||||
|
||||
For more information, see <<settings,{kib} configuration settings>>.
|
||||
--
|
||||
. Restart {kib}.
|
||||
After making these changes, you must always access {kib} via HTTPS. For example, `https://<your_kibana_host>.com`.
|
||||
|
||||
. Configure {kib} to connect to {es} via HTTPS:
|
||||
[[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}.
|
||||
|
||||
. {ref}/configuring-tls.html#tls-http[Enable TLS on the HTTP layer in {es}].
|
||||
|
||||
. Obtain the certificate authority (CA) certificate chain 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}.
|
||||
{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], you likely have a
|
||||
PKCS#12 file for each of your {es} nodes. You can extract the CA certificate chain from one of these files.
|
||||
|
||||
[source,shell]
|
||||
--------------------------------------------------------------------------------
|
||||
openssl pkcs12 -in elastic-certificates.p12 -cacerts -nokeys -out elasticsearch-ca.pem
|
||||
--------------------------------------------------------------------------------
|
||||
This will produce a PEM-formatted file named `elasticsearch-ca.pem` that contains all CA certificates from the PKCS#12 file.
|
||||
--
|
||||
|
||||
.. Specify the HTTPS protocol in the `elasticsearch.hosts` setting in the {kib}
|
||||
configuration file, `kibana.yml`:
|
||||
. Configure {kib} to trust the {es} CA certificate chain for the HTTP layer.
|
||||
+
|
||||
--
|
||||
Specify one or more PEM-formatted CA certificates in `kibana.yml`:
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
elasticsearch.ssl.certificateAuthorities: ["/path/to/elasticsearch-ca.pem"]
|
||||
--------------------------------------------------------------------------------
|
||||
For more information about settings for certificates and keys, see <<settings,{kib} configuration settings>>.
|
||||
--
|
||||
. Configure {kib} to enable TLS for outbound connections to {es}.
|
||||
+
|
||||
--
|
||||
Specify the HTTPS URL for {es} in `kibana.yml`:
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
elasticsearch.hosts: ["https://<your_elasticsearch_host>.com:9200"]
|
||||
--------------------------------------------------------------------------------
|
||||
--
|
||||
|
||||
.. If you are using your own CA to sign certificates for {es}, set the
|
||||
`elasticsearch.ssl.certificateAuthorities` setting in `kibana.yml` to specify
|
||||
the location of the PEM file.
|
||||
+
|
||||
--
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
Setting the `certificateAuthorities` property lets you use the default
|
||||
`verificationMode` option of `full`.
|
||||
//TBD: Is this still true? It isn't mentioned in https://www.elastic.co/guide/en/kibana/master/settings.html
|
||||
|
||||
For more information, see <<settings,{kib} configuration settings>>.
|
||||
--
|
||||
|
||||
. (Optional) If the Elastic {monitor-features} are enabled, configure {kib} to
|
||||
connect to the {es} monitoring cluster via HTTPS:
|
||||
+
|
||||
--
|
||||
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: 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 <<settings,{kib} configuration settings>>.
|
||||
|
||||
--
|
||||
|
||||
.. Specify the HTTPS URL in the `xpack.monitoring.elasticsearch.hosts` setting in
|
||||
the {kib} configuration file, `kibana.yml`
|
||||
+
|
||||
--
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
xpack.monitoring.elasticsearch.hosts: ["https://<your_monitoring_cluster>:9200"]
|
||||
--------------------------------------------------------------------------------
|
||||
--
|
||||
|
||||
.. Specify the `xpack.monitoring.elasticsearch.ssl.*` settings in the
|
||||
`kibana.yml` file.
|
||||
+
|
||||
--
|
||||
For example, if you are using your own certificate authority to sign
|
||||
certificates, specify the location of the PEM file in the `kibana.yml` file:
|
||||
|
||||
[source,yaml]
|
||||
--------------------------------------------------------------------------------
|
||||
xpack.monitoring.elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
|
||||
--------------------------------------------------------------------------------
|
||||
--
|
||||
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.certificateAuthorities`, etc.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue