From f3f6d1d910f9bad430e2fcbf669dc64d3a10176e Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 22 May 2018 10:51:25 -0700 Subject: [PATCH] [DOCS] Clarifies encrypting communications in Kibana (#19155) --- docs/setup/production.asciidoc | 37 +------- docs/setup/settings.asciidoc | 3 +- .../en/security/authentication/index.asciidoc | 3 + .../securing-communications/index.asciidoc | 91 +++++++++++++++++++ .../docs/en/security/securing-kibana.asciidoc | 48 +--------- 5 files changed, 99 insertions(+), 83 deletions(-) create mode 100644 x-pack/docs/en/security/securing-communications/index.asciidoc diff --git a/docs/setup/production.asciidoc b/docs/setup/production.asciidoc index 149c658187762..db1373f5e5d00 100644 --- a/docs/setup/production.asciidoc +++ b/docs/setup/production.asciidoc @@ -40,42 +40,7 @@ For information about setting up Kibana users, see [[enabling-ssl]] === Enabling SSL -Kibana supports TLS/SSL encryption for both client requests and the requests the -Kibana server sends to Elasticsearch. - -To encrypt communications between the browser and the Kibana server, you configure the `server.ssl.enabled`, -`server.ssl.certificate` and `server.ssl.key` properties in `kibana.yml`: - -[source,text] ----- -# SSL for outgoing requests from the Kibana Server (PEM formatted) -server.ssl.enabled: true -server.ssl.key: /path/to/your/server.key -server.ssl.certificate: /path/to/your/server.crt ----- - -If you are using {security} or a proxy that provides an HTTPS endpoint for Elasticsearch, -you can configure Kibana to access Elasticsearch via HTTPS so communications between -the Kibana server and Elasticsearch are encrypted. - -To do this, you specify the HTTPS -protocol when you configure the Elasticsearch URL in `kibana.yml`: - -[source,text] ----- -elasticsearch.url: "https://.com:9200" ----- - -If you are using a self-signed certificate for Elasticsearch, set the `certificateAuthorities` property in -`kibana.yml` to specify the location of the PEM file. Setting the `certificateAuthorities` property lets you use the -default `verificationMode` option of `full`. - -[source,text] ----- -# If you need to provide a CA certificate for your Elasticsearch instance, put -# the path of the pem file here. -elasticsearch.ssl.certificateAuthorities: [ "/path/to/your/ca/cacert.pem" ] ----- +See <>. [float] [[load-balancing]] diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 3286bf6449743..7ca1fe4df05ff 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -5,7 +5,8 @@ The Kibana server reads properties from the `kibana.yml` file on startup. The de on `localhost:5601`. To change the host or port number, or connect to Elasticsearch running on a different machine, you'll need to update your `kibana.yml` file. You can also enable SSL and set a variety of other options. Finally, environment variables can be injected into configuration using `${MY_ENV_VAR}` syntax. -Kibana Configuration Settings +.Kibana Configuration Settings + `console.enabled:`:: *Default: true* Set to false to disable Console. Toggling this will cause the server to regenerate assets on the next startup, which may cause a delay before pages start being served. `cpu.cgroup.path.override:`:: Override for cgroup cpu path when mounted in manner that is inconsistent with `/proc/self/cgroup` diff --git a/x-pack/docs/en/security/authentication/index.asciidoc b/x-pack/docs/en/security/authentication/index.asciidoc index f0b78779dd24b..9839975eaee14 100644 --- a/x-pack/docs/en/security/authentication/index.asciidoc +++ b/x-pack/docs/en/security/authentication/index.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[kibana-authentication]] === Authentication in Kibana +++++ +Authentication +++++ {kib} supports the following authentication mechanisms: diff --git a/x-pack/docs/en/security/securing-communications/index.asciidoc b/x-pack/docs/en/security/securing-communications/index.asciidoc new file mode 100644 index 0000000000000..e6b3987b36014 --- /dev/null +++ b/x-pack/docs/en/security/securing-communications/index.asciidoc @@ -0,0 +1,91 @@ +[[configuring-tls]] +=== Encrypting communications in {kib} +++++ +Encrypting communications +++++ + +{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? + +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. + +. Configure {kib} to encrypt communications between the browser and the {kib} +server: ++ +-- +NOTE: You do not need to enable {security} for this type of encryption. + +-- + +.. Generate a server certificate for {kib}. ++ +-- +//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. +-- + +.. Set the `server.ssl.enabled`, `server.ssl.key`, and `server.ssl.certificate` +properties 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 <>. +-- + +. Configure {kib} to connect to {es} via HTTPS: ++ +-- +NOTE: To perform this step, you must +{ref}/configuring-security.html[enable the {security} feature in {es}] or you +must have a proxy that provides an HTTPS endpoint for {es}. + +-- + +.. Specify the HTTPS protocol in the `elasticsearch.url` setting in the {kib} +configuration file, `kibana.yml`: ++ +-- +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.url: "https://.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 <>. +-- diff --git a/x-pack/docs/en/security/securing-kibana.asciidoc b/x-pack/docs/en/security/securing-kibana.asciidoc index b8c1e7aa1285f..2c1a760c8491a 100644 --- a/x-pack/docs/en/security/securing-kibana.asciidoc +++ b/x-pack/docs/en/security/securing-kibana.asciidoc @@ -69,52 +69,7 @@ xpack.security.sessionTimeout: 600000 -------------------------------------------------------------------------------- -- -[[configure-kibana-cert]] -. Configure {kib} to encrypt communications between the browser and the {kib} -server: - -.. Generate a server certificate for {kib}. 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. - -.. Set the `server.ssl.key` and `server.ssl.certificate` properties in `kibana.yml`: -+ --- -[source,yaml] --------------------------------------------------------------------------------- -server.ssl.key: /path/to/your/server.key -server.ssl.certificate: /path/to/your/server.crt --------------------------------------------------------------------------------- - -Once you enable SSL encryption between the browser and the {kib} server, -access {kib} via HTTPS. For example, `https://localhost:5601`. --- - -[[configure-kibana-ssl]] -. If you have enabled SSL encryption in {security}, configure {kib} to connect -to {es} via HTTPS: - -.. Specify the HTTPS protocol in the `elasticsearch.url` setting in the {kib} -configuration file, `kibana.yml`: -+ --- -[source,yaml] --------------------------------------------------------------------------------- -elasticsearch.url: "https://.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 --------------------------------------------------------------------------------- --- +. Optional: <>. . Restart {kib}. @@ -171,4 +126,5 @@ For more information about the settings in these steps, see <>. include::authentication/index.asciidoc[] +include::securing-communications/index.asciidoc[] include::{xkb-repo-dir}/settings/security-settings.asciidoc[]