[DOCS] Update Kibana install docs for security ON by default Beta #118770

lockewritesdocs · 2021-11-16T18:37:33Z

Summary

In 8.0, security is enabled and configured when users start Elasticsearch. An enrollment token is generated for Kibana, which users can copy and paste to enroll Kibana with Elasticsearch. This PR:

Adds a new section for starting Elasticsearch and enrolling Kibana (tar.gz, Windows, Deb, RPM)
Updates the section for Running Kibana from the command line to include steps for copying/pasting the enrollment token (tar.gz, Windows)

Preview links:

Note: Security ON by default currently does not support Homebrew, but hopefully will for 8.0.

jportner

Looks good, a couple of suggestions below. I'd also like @thomheymann to weigh in.

docs/setup/install/start-es-and-enroll.asciidoc

jportner · 2021-11-16T19:18:32Z

docs/setup/install/auto-enroll.asciidoc

+If this is the first time you're starting {kib}, this command generates a 
+unique link to enroll your {kib} instance with {es}.
+
+. In your terminal, click the generated link to open {kib} in your browser.
+
+. In your browser, paste the enrollment token for {kib} and click the
+button to connect your {kib} instance with {es}.


I think this sort of glosses over the difference between the Kibana auth code and the Elastic enrollment token.

Maybe we could use a couple of screenshots here? Or maybe we could clarify this text a bit more? I'm not sure what the best approach is.

So even if I go to http://0.0.0.0:5601/ (without the unique part of the URL), Kibana prompts me to enter the enrollment token because it’s the first time I’ve configured it. That’s cool!

If I click Configure manually and then enter http://0.0.0.0:9200, Kibana indicates that it can't connect to my cluster.

If I then go back and enter the enrollment code that Elasticsearch generated, I get this prompt to enter a verification code. I looked back in the Kibana terminal, and sure enough, there was a verification code!

@jportner, is this the behavior that you mentioned?

@thomheymann, are users only prompted for this verification code if they attempt to configure manually? Also, do you know why I received an error when trying to connect to http://0.0.0.0:9200 manually?

Joe's description is correct but I would call the code "verification code". We ask for it whenever someone attempts to configure Kibana using interactive setup UI without having followed the link that was generated when starting Kibana. It doesn't matter whether they do that using the enrollment token or using the manual configuration mode. Keep in mind that we only ask for the verification code when required (i.e. the user did not follow the interactive setup link and the user has entered the enrollment token / manual connection details and clicked "Configure Elastic") so you will not see it simply by viewing the enrollment token screen or the manual configuration screen.

For clarification: The "Check address" step does not require the verification code so it is expected that you don't see it at that stage.

I'm not sure if we need to go into too much detail regarding this step in the docs since most users will (hopefully) never see it. Might be worth adding a note to the docs but I would try and keep it simple since the popup does explain what to do.

lockewritesdocs · 2021-11-16T21:09:52Z

Ok, I think that I unlocked the manual configuration workflow (achievement unlocked 🔓)

Go to http://0.0.0.0:9200 (with or without the unique ID in the URL), which shows this in the terminal:

Click Configure manually and try to enter http://localhost:9200, followed by http://0.0.0.0:9200. Neither of these works, and I see the errors in the terminal. I find the correct URL where Elasticsearch is running, which is https://172.18.0.2:9200.

Enter the new URL and click Configure manually -- this produces a new login screen I've not seen previously that asks for the kibana_system password. We don't print this password to the terminal, which means that users have to run elasticsearch-reset-password -u kibana_system to set a new password for that user. Correct me if I'm wrong, but I don't know anywhere else where this password is available.

thomheymann

Thanks for putting this together Adam. Looks great!

I've added a couple comments suggestions below but happy to go with what you recommend.

docs/setup/install/auto-enroll.asciidoc

docs/setup/install/start-es-and-enroll.asciidoc

thomheymann · 2021-11-17T09:40:00Z

@lockewritesdocs Sorry you had to struggle through this, I didn't realise you hadn't seen the manual configuration screen.

We don't print this password to the terminal, which means that users have to run elasticsearch-reset-password -u kibana_system to set a new password for that user. Correct me if I'm wrong, but I don't know anywhere else where this password is available.

Good point - it might be worth adding some more guidance around this in the UI. I'll add a note to #118654

kibana-ci · 2021-11-18T15:40:03Z

💚 Build Succeeded

Buildkite Build
Commit: 8d35558

History

💚 Build #7415 succeeded 80673e5
💚 Build #7158 succeeded caf2d70

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @lockewritesdocs

jportner

LGTM!

…astic#118770) * [DOCS] Update install docs for security ON by default * Incorporating reviewer feedback and expanding RPM + Debian steps * Update Debian and RPM enrollment token process

kibanamachine · 2021-11-18T16:45:47Z

💚 Backport successful

Status	Branch	Result
✅	8.0

This backport PR will be merged automatically after passing CI.

…18770) (#119053) * [DOCS] Update install docs for security ON by default * Incorporating reviewer feedback and expanding RPM + Debian steps * Update Debian and RPM enrollment token process Co-authored-by: Adam Locke <adam.locke@elastic.co>

…astic#118770) * [DOCS] Update install docs for security ON by default * Incorporating reviewer feedback and expanding RPM + Debian steps * Update Debian and RPM enrollment token process

…18770) * [DOCS] Update install docs for security ON by default * Incorporating reviewer feedback and expanding RPM + Debian steps * Update Debian and RPM enrollment token process

…astic#118770) * [DOCS] Update install docs for security ON by default * Incorporating reviewer feedback and expanding RPM + Debian steps * Update Debian and RPM enrollment token process

[DOCS] Update install docs for security ON by default

caf2d70

lockewritesdocs added v8.0.0 release_note:skip Skip the PR/issue when compiling release notes docs v8.1.0 Feature:Security/Interactive Setup Platform Security - Interactive setup mode labels Nov 16, 2021

lockewritesdocs self-assigned this Nov 16, 2021

lockewritesdocs requested a review from jportner November 16, 2021 19:09

jportner reviewed Nov 16, 2021

View reviewed changes

jportner requested a review from thomheymann November 16, 2021 19:20

lockewritesdocs mentioned this pull request Nov 16, 2021

[DOCS] Documentation for security ON by default [beta+] elastic/elasticsearch#80170

Closed

31 tasks

thomheymann reviewed Nov 17, 2021

View reviewed changes

docs/setup/install/auto-enroll.asciidoc Outdated Show resolved Hide resolved

docs/setup/install/auto-enroll.asciidoc Outdated Show resolved Hide resolved

docs/setup/install/start-es-and-enroll.asciidoc Outdated Show resolved Hide resolved

thomheymann mentioned this pull request Nov 17, 2021

Provide more guidance on enrollment token #118654

Closed

lockewritesdocs changed the title ~~[DOCS] Update install docs for security ON by default Beta~~ [DOCS] Update Kibana install docs for security ON by default Beta Nov 17, 2021

Incorporating reviewer feedback and expanding RPM + Debian steps

80673e5

lockewritesdocs requested a review from jportner November 17, 2021 16:54

Update Debian and RPM enrollment token process

8d35558

jportner approved these changes Nov 18, 2021

View reviewed changes

lockewritesdocs added the auto-backport Deprecated - use backport:version if exact versions are needed label Nov 18, 2021

lockewritesdocs merged commit a578bea into elastic:main Nov 18, 2021

lockewritesdocs deleted the docs__update-install-archive branch November 18, 2021 16:42

kibanamachine mentioned this pull request Nov 18, 2021

[8.0] [DOCS] Update Kibana install docs for security ON by default Beta (#118770) #119053

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Update Kibana install docs for security ON by default Beta #118770

[DOCS] Update Kibana install docs for security ON by default Beta #118770

lockewritesdocs commented Nov 16, 2021 •

edited

Loading

jportner left a comment

jportner Nov 16, 2021

lockewritesdocs Nov 16, 2021

thomheymann Nov 17, 2021 •

edited

Loading

lockewritesdocs commented Nov 16, 2021

thomheymann left a comment

thomheymann commented Nov 17, 2021

kibana-ci commented Nov 18, 2021

jportner left a comment

kibanamachine commented Nov 18, 2021

[DOCS] Update Kibana install docs for security ON by default Beta #118770

[DOCS] Update Kibana install docs for security ON by default Beta #118770

Conversation

lockewritesdocs commented Nov 16, 2021 • edited Loading

Summary

jportner left a comment

Choose a reason for hiding this comment

jportner Nov 16, 2021

Choose a reason for hiding this comment

lockewritesdocs Nov 16, 2021

Choose a reason for hiding this comment

thomheymann Nov 17, 2021 • edited Loading

Choose a reason for hiding this comment

lockewritesdocs commented Nov 16, 2021

thomheymann left a comment

Choose a reason for hiding this comment

thomheymann commented Nov 17, 2021

kibana-ci commented Nov 18, 2021

💚 Build Succeeded

History

jportner left a comment

Choose a reason for hiding this comment

kibanamachine commented Nov 18, 2021

💚 Backport successful

lockewritesdocs commented Nov 16, 2021 •

edited

Loading

thomheymann Nov 17, 2021 •

edited

Loading