Update security docs #87215

jportner · 2021-01-04T19:19:59Z

Summary

Resolves several open docs issues: #81533, #81531, and #85702.

Docs preview: https://kibana_87215.docs-preview.app.elstc.co/diff

Notes:

P12 support was not added to Kibana until 7.6, but the master branch docs assumes that P12 is supported so the docs backports to 7.5 and prior will need to be tweaked a bit.
In the docs for 7.3 and prior, the Saved Objects page does not include a section for "Copy to other Kibana spaces", so the backports to 7.3 and prior will need to be tweaked a bit.

jportner

Added some comments with a few notes about the changes.

jportner · 2021-01-04T19:36:10Z

docs/management/managing-saved-objects.asciidoc

-the NDJSON includes related objects. Exported dashboards include their associated index patterns.
+the NDJSON includes related child objects. Exported dashboards include their associated index patterns.


We don't really say "related child objects" anywhere else in Kibana as far as I can tell. The only place where child/parent relations appear to be described is in the Saved Objects Management page (click a row action to view related objects).

I figure that for the purposes of docs, "related child objects" is fine, unless someone has a better idea?

How about:

By default, the NDJSON includes child objects that are related to the saved objects.

jportner · 2021-01-04T19:40:00Z

docs/user/security/securing-communications/index.asciidoc

-You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
+You may choose to generate a signed certificate and private key using the [`elasticsearch-certutil`] tool.


As suggested by Tim in the linked comment, I rewrote these instructions to simply generate a certificate for local usage, with an added note that it is not appropriate for a production environment. I think this suffices, but it's really not any less wordy.

To make this a bit more concise we could also consider changing the "Encrypt traffic between the browser and Kibana" section:

Move said note to the bottom of the section

Remove Step 2b for PEM certificates (since our example now explicitly generates a P12 file)

Edit: we could also change the "Encrypt traffic between Kibana and Elasticsearch" section and remove Step 3b completely, since we already mentioned how to extract the CA certificate from a P12 file (and that is likely a better option in the most common cases).

Thoughts?

I'm personally OK with the length, and I like the simpler steps to generate a certificate for local usage, too

jportner · 2021-01-04T19:41:13Z

docs/user/security/securing-kibana.asciidoc

-The password for the built-in `kibana_system` user is typically set as part of
-the security configuration process on {es}. For more information, see
-{ref}/built-in-users.html[Built-in users].
+NOTE: The password for the built-in `kibana_system` user is typically set as part of the security configuration process on {es}. For more
+information, see {ref}/built-in-users.html[Built-in users].


Changed this to a Note admonition, but didn't modify the text.

jportner · 2021-01-04T19:44:33Z

docs/user/security/securing-kibana.asciidoc

-. [[kibana-roles]]Choose an authentication mechanism and grant users the privileges they need to
-use {kib}.
+. Temporarily log into {kib} using the built-in `elastic` superuser so you can create new users and assign roles. If you are running {kib}
+locally, go to `https://localhost:5601` to view the login page.
 +
--
-For more information on Basic Authentication and additional methods of
-authenticating {kib} users, see <<kibana-authentication>>.
+NOTE: The password for the built-in `elastic` user is typically set as part of the security configuration process on {es}. For more
+information, see {ref}/built-in-users.html[Built-in users].

-To manage privileges, open the main menu, then click *Stack Management > Roles*.
+. [[kibana-roles]]Create roles and users to grant access to {kib}.
+
+--
+To manage privileges in {kib}, open the main menu, then click *Stack Management > Roles*. The built-in `kibana_admin` role will grant


I made two changes here:

Added a new bullet that clarifies the user should temporarily log into Kibana as the superuser

Changed the "Choose an authentication mechanism and grant users the privileges they need to use {kib}." bullet to "Create roles and users to grant access to {kib}.", keeping the anchor intact

It seems to me that "Choose an authentication mechanism" is out of place here and not really appropriate for a quick-start guide.

I like both of these changes, and I agree that choosing an authentication mechanism is a bit out of place

legrego

Thanks for taking these on, Joe! I like the changes you've made here.

@arisonl I know you recently configured a stack locally to use TLS, so the pain is fresh in your mind. What do you think about these doc improvements?

@lockewritesdocs FYSA - I know you were working on security docs as well

legrego · 2021-01-04T19:57:20Z

docs/user/security/securing-communications/index.asciidoc

 --------------------------------------------------------------------------------
+
+TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set


Just tell me I'm being lazy and I'll test it myself, but does the PKCS#12 file generated by
elasticsearch-certutil require the empty string when no password is provided, or is it more nuanced than that? If the one we generate requires the empty string, then we might want to make that more explicit here

Good question! I alluded to the difference here, but didn't specify what elasticsearch-certutil itself does when you don't enter a password.

I was pretty sure that would result in a keystore with an empty password, but I wanted to test and make sure. By manually replacing the files in packages/kbn-dev-utils/certs and rerunning the unit tests in src/core/server/utils/crypto/pkcs12.test.ts, I verified that is indeed the case.

How do you feel about changing the tip to this?

TIP: If you used elasticsearch-certutil to generate a PKCS#12 file and you did not specify a password, the file is encrypted, and you need to set server.ssl.keystore.password to an empty string.

There are other ways this would be needed (such as using OpenSSL, as described in the link above) but I figure we should keep it concise here.

Edit: changed in 11c2685.

Thanks for taking the time to verify this. I'm happy with the updated tip text

docs/user/security/securing-communications/index.asciidoc

docs/user/security/securing-kibana.asciidoc

docs/user/security/securing-communications/index.asciidoc

legrego · 2021-01-04T20:09:02Z

docs/user/security/securing-communications/index.asciidoc

-You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
+You may choose to generate a signed certificate and private key using the [`elasticsearch-certutil`] tool.


I'm personally OK with the length, and I like the simpler steps to generate a certificate for local usage, too

legrego · 2021-01-04T20:10:02Z

docs/user/security/securing-kibana.asciidoc

-. [[kibana-roles]]Choose an authentication mechanism and grant users the privileges they need to
-use {kib}.
+. Temporarily log into {kib} using the built-in `elastic` superuser so you can create new users and assign roles. If you are running {kib}
+locally, go to `https://localhost:5601` to view the login page.
 +
--
-For more information on Basic Authentication and additional methods of
-authenticating {kib} users, see <<kibana-authentication>>.
+NOTE: The password for the built-in `elastic` user is typically set as part of the security configuration process on {es}. For more
+information, see {ref}/built-in-users.html[Built-in users].

-To manage privileges, open the main menu, then click *Stack Management > Roles*.
+. [[kibana-roles]]Create roles and users to grant access to {kib}.
+
+--
+To manage privileges in {kib}, open the main menu, then click *Stack Management > Roles*. The built-in `kibana_admin` role will grant


I like both of these changes, and I agree that choosing an authentication mechanism is a bit out of place

gchaps

LGTM, with a few minor comments.

gchaps · 2021-01-04T21:32:32Z

docs/management/managing-saved-objects.asciidoc

-the NDJSON includes related objects. Exported dashboards include their associated index patterns.
+the NDJSON includes related child objects. Exported dashboards include their associated index patterns.


How about:

By default, the NDJSON includes child objects that are related to the saved objects.

docs/user/security/securing-communications/index.asciidoc

docs/user/security/securing-kibana.asciidoc

legrego

LGTM once Gail's comments are addressed. Thanks for taking the time to fix these docs issues!

jportner · 2021-01-05T15:21:57Z

docs/user/security/securing-communications/index.asciidoc

-TIP: If you used `elasticsearch-certutil` to generate a PKCS#12 file and you did not specify a password, the file is encrypted, and you need
-to set server.ssl.keystore.password to an empty string.
+NOTE: If you used `elasticsearch-certutil` to generate a PKCS#12 file and you did not specify a password, the file is encrypted, and you
+need to set `server.ssl.truststore.password` to an empty string.


While I was adding the code tags I noticed that server.ssl.keystore.password was wrong, it should have been server.ssl.truststore.password this whole time 😅

# Conflicts: # docs/user/security/securing-kibana.asciidoc

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

# Conflicts: # docs/user/security/securing-kibana.asciidoc

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added 3 commits January 4, 2021 12:45

Clarify user login in "Configure security" page

cc54792

Clarify that "Copy to space" includes child objects

6d8acb3

Clarify docs for configuring TLS

e94ddb1

jportner added release_note:skip Skip the PR/issue when compiling release notes v8.0.0 v7.0.3 v7.1.3 v7.10.2 v7.11.0 v7.12.0 v7.2.3 v7.3.3 v7.4.3 v7.5.2 v7.6.3 v7.7.2 v7.8.2 v7.9.4 labels Jan 4, 2021

jportner commented Jan 4, 2021

View reviewed changes

jportner marked this pull request as ready for review January 4, 2021 19:47

jportner requested review from gchaps and legrego January 4, 2021 19:47

legrego reviewed Jan 4, 2021

View reviewed changes

PR review feedback

11c2685

gchaps approved these changes Jan 4, 2021

View reviewed changes

legrego approved these changes Jan 5, 2021

View reviewed changes

jportner added 2 commits January 5, 2021 10:11

Merge branch 'master' into update-security-docs

99bd614

More PR review feedback

af83361

jportner commented Jan 5, 2021

View reviewed changes

Add code tags around localhost URL

b67d7c2

jportner added a commit to jportner/kibana that referenced this pull request Jan 5, 2021

Update security docs (elastic#87215)

eebcbbe

# Conflicts: # docs/user/security/securing-kibana.asciidoc

jportner mentioned this pull request Jan 5, 2021

[7.6] Update security docs (#87215) #87342

Merged

jportner added a commit to jportner/kibana that referenced this pull request Jan 5, 2021

Update security docs (elastic#87215)

5351c1a

# Conflicts: # docs/user/security/securing-kibana.asciidoc

jportner mentioned this pull request Jan 5, 2021

[7.5] Update security docs (#87215) #87346

Merged

jportner mentioned this pull request Jan 5, 2021

[7.4] Update security docs (#87215) #87347

Merged

jportner mentioned this pull request Jan 5, 2021

[7.3] Update security docs (#87215) #87348

Merged

jportner mentioned this pull request Jan 5, 2021

[7.2] Update security docs (#87215) #87349

Merged

jportner mentioned this pull request Jan 5, 2021

[7.1] Update security docs (#87215) #87350

Merged

jportner mentioned this pull request Jan 5, 2021

[7.0] Update security docs (#87215) #87354

Merged

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87334)

497383d

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87335)

980035c

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87336)

d89a8db

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87337)

11008cf

# Conflicts: # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87338)

3b05b93

# Conflicts: # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87339)

1ddd187

# Conflicts: # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

[7.6] Update security docs (#87215) (#87342)

cc2fd8e

# Conflicts: # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

[7.5] Update security docs (#87215) (#87346)

062f846

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87347)

ab9fcf3

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87348)

a840a95

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87349)

346978d

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

[7.1] Update security docs (#87215) (#87350)

3d57042

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added a commit that referenced this pull request Jan 5, 2021

Update security docs (#87215) (#87354)

8e3d2b4

# Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc

jportner added backported and removed backport pending labels Jan 5, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update security docs #87215

Update security docs #87215

jportner commented Jan 4, 2021 •

edited

Loading

jportner left a comment

jportner Jan 4, 2021

gchaps Jan 4, 2021

jportner Jan 4, 2021 •

edited

Loading

legrego Jan 4, 2021

jportner Jan 4, 2021

jportner Jan 4, 2021

legrego Jan 4, 2021

legrego left a comment

legrego Jan 4, 2021

jportner Jan 4, 2021 •

edited

Loading

legrego Jan 5, 2021

legrego Jan 4, 2021

legrego Jan 4, 2021

gchaps left a comment

gchaps Jan 4, 2021

legrego left a comment

jportner Jan 5, 2021

		the NDJSON includes related objects. Exported dashboards include their associated index patterns.
		the NDJSON includes related child objects. Exported dashboards include their associated index patterns.

		You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
		You may choose to generate a signed certificate and private key using the [`elasticsearch-certutil`] tool.

		--------------------------------------------------------------------------------

		TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set

Update security docs #87215

Update security docs #87215

Conversation

jportner commented Jan 4, 2021 • edited Loading

Summary

jportner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jportner Jan 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

legrego left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jportner Jan 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gchaps left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

legrego left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jportner commented Jan 4, 2021 •

edited

Loading

jportner Jan 4, 2021 •

edited

Loading

jportner Jan 4, 2021 •

edited

Loading