Clarify documentation for TLS encryption setup #55739
Conversation
Normalize columns and remove unnecessary whitespace.
jportner
force-pushed
the
issue-55512-docs-clarify-tls
branch
from
81f9248 to
053ed1e
Compare
jportner
force-pushed
the
issue-55512-docs-clarify-tls
branch
2 times, most recently
from
4a5febf to
2a701e5
Compare
jportner
force-pushed
the
issue-55512-docs-clarify-tls
branch
from
2a701e5 to
7726841
Compare
There was a problem hiding this comment.
Author's notes, round 1.1 (second time's the charm!)
I attempted to do several things:
- Align with general guidance and format from Elasticsearch documentation
- Standardize terminology across sections ("client certificate", "server certificate", "outbound", "inbound", etc.)
- Reformat the guides that shows different options but makes it easier to follow the the recommended steps to set up Kibana in a production environment
- Encourage the use of the
kibana-keystorefor storing passwords - Add/update references where appropriate
The setup guides do not attempt to show every possible permutation for configuration, they just show the recommended / most common scenario.
|
Pinging @elastic/kibana-docs (Team:Docs) |
jportner
added
release_note:skip
|
Pinging @elastic/kibana-security (Team:Security) |
|
I think some of these instructions might need to be revisited now that we have the "elasticsearch-certutil http" command in 7.6. I had added a tip in #55357, but I suspect it'll also affect the lower-level instructions in this PR (e.g. where you're describing how to generate a PEM file from a PKCS#12 file). |
docs/user/security/securing-communications/elasticsearch-mutual-tls.asciidoc
Outdated
Show resolved
Hide resolved
Oh, I got mixed up and thought that was an outdated tip, as I tried to use that command and it didn't work. I didn't realize it was added in ES 7.6. I was using an older version of |
Okay @lcawl, I've taken a look at it, and here are my thoughts:
I think it's another valid way of doing things, but I like how we currently have it written because it's clear-cut with command-line arguments and gives you exactly what you need. If you use the interactive prompt there's more room for error. I think either rewriting this guide with With that in mind, how do you think we should proceed? Are you OK with leaving this out? |
My PR for that is under review here, if that helps: elastic/elasticsearch#51241 |
Ah, yes that does help, thanks. I don't think the Kibana docs section for "Encrypting traffic between the browser and Kibana" needs any changes, based on that, but I do think that "Encrypting traffic between Kibana and Elasticsearch" needs changes. Let me rework that and let you take another look. |
| . 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], then 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: | ||
| .. 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. | ||
|
|
||
| .. 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,sh] | ||
| -------------------------------------------------------------------------------- | ||
| openssl pkcs12 -in elastic-certificates.p12 -cacerts -nokeys -out elasticsearch-ca.crt | ||
| openssl pkcs12 -in elastic-certificates.p12 -cacerts -nokeys -out elasticsearch-ca.pem | ||
| -------------------------------------------------------------------------------- | ||
|
|
||
| This will produce a PEM-formatted file named `elasticsearch-ca.crt` that contains all CA certificates from the PKCS#12 file. | ||
| This will produce a PEM-formatted file named `elasticsearch-ca.pem` that contains all CA certificates from the PKCS#12 file. |
There was a problem hiding this comment.
I changed this step to account for the new Elasticsearch documentation that will suggest using the elasticsearch-certutil http command. That command creates a ZIP file with a "kibana" directory, which may contain the CA cert (if the user did not choose to generate a CSR).
I also changed "elasticsearch-ca.crt to elasticsearch-ca.pem, since that's the same filename that the elasticsearch-certutil http command would produce.
Co-Authored-By: Thomas Watson <w@tson.dk>
[skip-ci]
Summary
With the addition of support for PKCS#12 keystores in Kibana 7.6+, the steps to configure TLS became even more convoluted than they were before.
The intent behind this PR is to make TLS configuration steps easier to understand, differentiate how to obtain the Kibana server certificate (via CSR) and the Elasticsearch server certificate (no CSR necessary), adhere to security best practices, and better align with the Elasticsearch documentation for TLS configuration.
I tried to avoid using the word "key store" and "trust store" as much as possible, because those are overloaded terms (and we also reference the Kibana keystore for secure settings).
Preview link: http://kibana_55739.docs-preview.app.elstc.co/diff
Closes #55112.