From 3d57042246c0184889e5656a615f7467d6581ea4 Mon Sep 17 00:00:00 2001 From: Joe Portner <5295965+jportner@users.noreply.github.com> Date: Tue, 5 Jan 2021 13:33:10 -0500 Subject: [PATCH] [7.1] Update security docs (#87215) (#87350) # Conflicts: # docs/management/managing-saved-objects.asciidoc # docs/user/security/securing-communications/index.asciidoc # docs/user/security/securing-kibana.asciidoc --- .../securing-communications/index.asciidoc | 53 +++++++++++-------- docs/user/security/securing-kibana.asciidoc | 44 +++++++-------- 2 files changed, 51 insertions(+), 46 deletions(-) diff --git a/docs/user/security/securing-communications/index.asciidoc b/docs/user/security/securing-communications/index.asciidoc index 36d3dcb3052341..7619eab4480b88 100644 --- a/docs/user/security/securing-communications/index.asciidoc +++ b/docs/user/security/securing-communications/index.asciidoc @@ -25,54 +25,62 @@ NOTE: You do not need to enable the {es} {security-features} for this type of en 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. +the FQDN in a production environment. +You may choose to generate a signed certificate 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 +bin/elasticsearch-certutil cert -name kibana-server -dns localhost,127.0.0.1 -------------------------------------------------------------------------------- -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. +This will produce a PKCS#12 file named `kibana-server.p12`, which contains the server certificate and private key. + +NOTE: In this example, the server certificate is signed by a locally-generated certificate authority (CA). This is not suitable for a +production environment, and it will result in warnings in your web browser until you configure your browser to trust the certificate. Steps +to configure certificate trust vary depending upon your browser and operating system. If you want to obtain a server certificate for a +production environment, you can instead generate a certificate signing request (CSR) with `elasticsearch-certutil` using +{ref}/certutil.html#certutil-csr[CSR mode]. -- . Configure {kib} to access the server certificate and private key. +.. 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 below. +-- + .. If your server certificate and private key are in PEM format: + -- 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 <>: + [source,yaml] -------------------------------------------------------------------------------- bin/kibana-keystore add server.ssl.keyPassphrase -------------------------------------------------------------------------------- -- -.. 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 <>. + . Configure {kib} to enable TLS for inbound connections. + -- @@ -83,7 +91,8 @@ server.ssl.enabled: true -------------------------------------------------------------------------------- -- . Restart {kib}. -After making these changes, you must always access {kib} via HTTPS. For example, `https://.com`. + +After making these changes, you must always access {kib} via HTTPS. For example, `https://localhost:5601`. [[configuring-tls-kib-es]] ==== Encrypting traffic between {kib} and {es} diff --git a/docs/user/security/securing-kibana.asciidoc b/docs/user/security/securing-kibana.asciidoc index 62968c04e8ddc1..59a0dd37c34b83 100644 --- a/docs/user/security/securing-kibana.asciidoc +++ b/docs/user/security/securing-kibana.asciidoc @@ -38,9 +38,8 @@ elasticsearch.password: "kibanapassword" The {kib} server submits requests as this user to access the cluster monitoring APIs and the `.kibana` index. The server does _not_ need access to user indices. -The password for the built-in `kibana` user is typically set as part of the -{security} configuration process on {es}. For more information, see -{stack-ov}/built-in-users.html[Built-in users]. +NOTE: The password for the built-in `kibana` 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]. -- . Set the `xpack.security.encryptionKey` property in the `kibana.yml` @@ -73,20 +72,21 @@ xpack.security.sessionTimeout: 600000 . Restart {kib}. -. [[kibana-roles]]Choose an authentication mechanism and grant users the privileges they need to -use {kib}. +. Temporarily log in to {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 <>. +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]. -You can manage privileges on the *Management / Security / Roles* page in {kib}. +. [[kibana-roles]]Create roles and users to grant access to {kib}. ++ +-- +To manage privileges in {kib}, open the main menu, then click *Management / Security / Roles*. The built-in `kibana_user` role will grant +access to {kib} with administrator privileges. Alternatively, you can create additional roles that grant limited access to {kib}. -If you're using the native realm with Basic Authentication, you can assign roles -using the *Management / Security / Users* page in {kib} or the -{ref}/security-api.html#security-user-apis[user management APIs]. For example, -the following creates a user named `jacknich` and assigns it the `kibana_user` -role: +If you're using the default native realm with Basic Authentication, open the main menu, then click *Management / Security / Users* to create +users and assign roles, or use the {es} {ref}/security-api.html#security-user-apis[user management APIs]. For example, the following creates +a user named `jacknich` and assigns it the `kibana_user` role: [source,js] -------------------------------------------------------------------------------- @@ -97,6 +97,8 @@ POST /_security/user/jacknich } -------------------------------------------------------------------------------- // CONSOLE + +TIP: For more information on Basic Authentication and additional methods of authenticating {kib} users, see <>. -- . Grant users access to the indices that they will be working with in {kib}. @@ -110,17 +112,11 @@ on specific index patterns. For more information, see -- -. Verify that you can log in as a user. If you are running -{kib} locally, go to `https://localhost:5601` and enter the credentials for a -user you've assigned a {kib} user role. For example, you could log in as the -`jacknich` user created above. +. Log out of {kib} and verify that you can log in as a normal user. If you are running {kib} locally, go to `https://localhost:5601` and +enter the credentials for a user you've assigned a {kib} user role. For example, you could log in as the user `jacknich`. + --- - -NOTE: This must be a user who has been assigned the `kibana_user` role. -{kib} server credentials should only be used internally by the {kib} server. - --- +NOTE: This must be a user who has been assigned the `kibana_user` role. {kib} server credentials (the built-in `kibana` user) should only be +used internally by the {kib} server. include::authentication/index.asciidoc[] include::securing-communications/index.asciidoc[]