From 79b647ee6236d5edb0df56e74deb5602b93838d5 Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 9 Jul 2021 15:33:35 -0700 Subject: [PATCH 1/5] Add SSL configuration for Dashboards --- .gitignore | 1 + _dashboards/install/ssl.md | 41 +++++++++++++++++++++++++ _security-plugin/configuration/index.md | 12 ++++---- index.md | 7 +++-- 4 files changed, 53 insertions(+), 8 deletions(-) create mode 100644 _dashboards/install/ssl.md diff --git a/.gitignore b/.gitignore index ba3d9259..ae2249e7 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ _site .DS_Store Gemfile.lock .idea +.jekyll-cache diff --git a/_dashboards/install/ssl.md b/_dashboards/install/ssl.md new file mode 100644 index 00000000..412a5e7b --- /dev/null +++ b/_dashboards/install/ssl.md @@ -0,0 +1,41 @@ +--- +layout: default +title: Configure SSL +parent: Install OpenSearch Dashboards +nav_order: 40 +--- + +# Configure SSL for OpenSearch Dashboards + +By default, for ease of testing and getting started, OpenSearch Dashboards runs over HTTP. To enable SSL, update the following settings in `opensearch_dashboards.yml`. + +Setting | Description +:--- | :--- +opensearch.ssl.verificationMode | This setting is for communications between OpenSearch and OpenSearch Dashboards. Valid values are `full`, `certificate`, or `none`. We recommend `full` if you enable SSL, which enables hostname verification. `certificate` just checks the certificate, not the hostname, and `none` performs no checks (suitable for HTTP). Default is `full`. +opensearch.ssl.certificateAuthorities | If `opensearch.ssl.verificationMode` is `full` or `certificate`, specify the full path (e.g. `[ "/usr/share/opensearch-dashboards-1.0.0/config/root-ca.pem" ]` to the certificate authority for your OpenSearch cluster. +server.ssl.enabled | This setting is for communications between OpenSearch Dashboards and the web browser. Set to true for HTTPS, false for HTTP. +server.ssl.certificate | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert.pem` to a valid client certificate for your OpenSearch cluster. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority. +server.ssl.key | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert-key.pem` to the key for your client certificate. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority. +opensearch_security.cookie.secure | If you enable SSL for OpenSearch Dashboards, change this setting to `true`. For HTTP, set it to `false`. + +This `opensearch_dashboards.yml` configuration shows OpenSearch and OpenSearch Dashboards running on the same machine with the demo configuration: + +```yml +opensearch.hosts: ["https://localhost:9200"] +opensearch.ssl.verificationMode: full +opensearch.username: "kibanaserver" +opensearch.password: "kibanaserver" +opensearch.requestHeadersWhitelist: [ authorization,securitytenant ] +server.ssl.enabled: true +server.ssl.certificate: /usr/share/opensearch-1.0.0/config/client-cert.pem +server.ssl.key: /usr/share/opensearch-1.0.0/config/client-cert-key.pem +opensearch.ssl.certificateAuthorities: [ "/usr/share/opensearch-1.0.0/config/root-ca.pem" ] +opensearch_security.multitenancy.enabled: true +opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] +opensearch_security.readonly_mode.roles: ["kibana_read_only"] +opensearch_security.cookie.secure: true +``` + +If you use the Docker install, you can pass a custom `opensearch_dashboards.yml` to the container. To learn more, see the [Docker installation page]({{site.url}}{{site.baseurl}}/opensearch/install/docker/). + +After enabling these settings and starting OpenSearch Dashboards, you can connect to it at `https://localhost:5601`. You might have to acknowledge a browser warning if your certificates are self-signed. diff --git a/_security-plugin/configuration/index.md b/_security-plugin/configuration/index.md index 702fe685..6ce2565f 100644 --- a/_security-plugin/configuration/index.md +++ b/_security-plugin/configuration/index.md @@ -13,12 +13,12 @@ redirect_from: The plugin includes demo certificates so that you can get up and running quickly, but before using OpenSearch in a production environment, you must configure it manually: -1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker-security) -1. [Reconfigure opensearch.yml to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls) -1. [Reconfigure config.yml to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database) -1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml) -1. [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin) +1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker-security). +1. [Reconfigure opensearch.yml to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls). +1. [Reconfigure config.yml to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database). +1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). +1. [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin). 1. Start OpenSearch. -1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/) +1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). If you don't want to use the plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security-plugin/configuration/disable). diff --git a/index.md b/index.md index 625020ba..253e246d 100755 --- a/index.md +++ b/index.md @@ -37,7 +37,7 @@ Component | Purpose [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/) | Identify atypical data and receive automatic notifications [Asynchronous Search]({{site.url}}{{site.baseurl}}/search-plugins/async/) | Run search requests in the background -You can install OpenSearch plugins [individually]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) or use the [all-in-one packages]({{site.url}}{{site.baseurl}}/opensearch/install/). Most of these OpenSearch plugins have corresponding OpenSearch Dashboards plugins that provide a convenient, unified user interface. +Most of OpenSearch plugins have a corresponding OpenSearch Dashboards plugin that provide a convenient, unified user interface. For specifics around the project, see the [FAQ](https://opensearch.org/faq/). @@ -65,7 +65,10 @@ Docker To learn more, see [Install and configure OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/install/) and [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/). ---- +## The secure path forward + +OpenSearch includes a demo configuration so that you can get up and running quickly, but before using OpenSearch in a production environment, you must [configure the security plugin manually]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/): your own certificates, your own authentication method, your own users, and your own passwords. + ## Looking for the Javadoc? From cf769012cadebcd00c12454c50d9b1e032b8ce4e Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 9 Jul 2021 15:59:42 -0700 Subject: [PATCH 2/5] Change file name, add some extra bits --- _dashboards/install/{ssl.md => tls.md} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename _dashboards/install/{ssl.md => tls.md} (87%) diff --git a/_dashboards/install/ssl.md b/_dashboards/install/tls.md similarity index 87% rename from _dashboards/install/ssl.md rename to _dashboards/install/tls.md index 412a5e7b..52cc0502 100644 --- a/_dashboards/install/ssl.md +++ b/_dashboards/install/tls.md @@ -5,18 +5,18 @@ parent: Install OpenSearch Dashboards nav_order: 40 --- -# Configure SSL for OpenSearch Dashboards +# Configure TLS for OpenSearch Dashboards -By default, for ease of testing and getting started, OpenSearch Dashboards runs over HTTP. To enable SSL, update the following settings in `opensearch_dashboards.yml`. +By default, for ease of testing and getting started, OpenSearch Dashboards runs over HTTP. To enable TLS for HTTPS, update the following settings in `opensearch_dashboards.yml`. Setting | Description :--- | :--- -opensearch.ssl.verificationMode | This setting is for communications between OpenSearch and OpenSearch Dashboards. Valid values are `full`, `certificate`, or `none`. We recommend `full` if you enable SSL, which enables hostname verification. `certificate` just checks the certificate, not the hostname, and `none` performs no checks (suitable for HTTP). Default is `full`. +opensearch.ssl.verificationMode | This setting is for communications between OpenSearch and OpenSearch Dashboards. Valid values are `full`, `certificate`, or `none`. We recommend `full` if you enable TLS, which enables hostname verification. `certificate` just checks the certificate, not the hostname, and `none` performs no checks (suitable for HTTP). Default is `full`. opensearch.ssl.certificateAuthorities | If `opensearch.ssl.verificationMode` is `full` or `certificate`, specify the full path (e.g. `[ "/usr/share/opensearch-dashboards-1.0.0/config/root-ca.pem" ]` to the certificate authority for your OpenSearch cluster. server.ssl.enabled | This setting is for communications between OpenSearch Dashboards and the web browser. Set to true for HTTPS, false for HTTP. server.ssl.certificate | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert.pem` to a valid client certificate for your OpenSearch cluster. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority. server.ssl.key | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert-key.pem` to the key for your client certificate. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority. -opensearch_security.cookie.secure | If you enable SSL for OpenSearch Dashboards, change this setting to `true`. For HTTP, set it to `false`. +opensearch_security.cookie.secure | If you enable TLS for OpenSearch Dashboards, change this setting to `true`. For HTTP, set it to `false`. This `opensearch_dashboards.yml` configuration shows OpenSearch and OpenSearch Dashboards running on the same machine with the demo configuration: @@ -38,4 +38,4 @@ opensearch_security.cookie.secure: true If you use the Docker install, you can pass a custom `opensearch_dashboards.yml` to the container. To learn more, see the [Docker installation page]({{site.url}}{{site.baseurl}}/opensearch/install/docker/). -After enabling these settings and starting OpenSearch Dashboards, you can connect to it at `https://localhost:5601`. You might have to acknowledge a browser warning if your certificates are self-signed. +After enabling these settings and starting OpenSearch Dashboards, you can connect to it at `https://localhost:5601`. You might have to acknowledge a browser warning if your certificates are self-signed. To avoid this sort of warning (or outright browser incompatibility), best practice is to use certificates from trusted certificate authority. From 92b3b49ee2a74d808cb288a0b932c2eeffb6f8aa Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 9 Jul 2021 15:59:58 -0700 Subject: [PATCH 3/5] Update tls.md --- _dashboards/install/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_dashboards/install/tls.md b/_dashboards/install/tls.md index 52cc0502..d576ed84 100644 --- a/_dashboards/install/tls.md +++ b/_dashboards/install/tls.md @@ -1,6 +1,6 @@ --- layout: default -title: Configure SSL +title: Configure TLS parent: Install OpenSearch Dashboards nav_order: 40 --- From b8bf7a2f1d5bee3c5d6550589119c5d8aa996de4 Mon Sep 17 00:00:00 2001 From: aetter Date: Sun, 11 Jul 2021 18:10:36 -0700 Subject: [PATCH 4/5] Add link recommending password policy --- _security-plugin/configuration/index.md | 1 + _security-plugin/configuration/yaml.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/_security-plugin/configuration/index.md b/_security-plugin/configuration/index.md index 6ce2565f..90d53e62 100644 --- a/_security-plugin/configuration/index.md +++ b/_security-plugin/configuration/index.md @@ -17,6 +17,7 @@ The plugin includes demo certificates so that you can get up and running quickly 1. [Reconfigure opensearch.yml to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls). 1. [Reconfigure config.yml to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database). 1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). +1. If you plan to use the internal user database, [set a password policy in opensearch.yml]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#opensearchyml). 1. [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin). 1. Start OpenSearch. 1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index 302d853f..066a7d76 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -91,7 +91,7 @@ snapshotrestore: ## opensearch.yml -This file contains relative file paths to TLS certificates and their attributes, such as distinguished names and trusted certificate authorities. +In addition to many OpenSearch settings, this file contains paths to TLS certificates and their attributes, such as distinguished names and trusted certificate authorities. ```yml plugins.security.ssl.transport.pemcert_filepath: esnode.pem @@ -116,7 +116,7 @@ plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opend node.max_local_storage_nodes: 3 ``` -If you want to run your users' passwords against some validation, you can specify the necessary regex in this file. You can also include an error message that loads if any passwords don't pass validation. The following example demonstrates how to include a regex so OpenSearch requires new passwords to be a minimum of eight characters with at least one uppercase, one lowercase, one digit, and one special character. +If you want to run your users' passwords against some validation, specify a regular expression (regex) in this file. You can also include an error message that loads when passwords don't pass validation. The following example demonstrates how to include a regex so OpenSearch requires new passwords to be a minimum of eight characters with at least one uppercase, one lowercase, one digit, and one special character. Note that OpenSearch validates only users and passwords created through OpenSearch Dashboards or the REST API. @@ -125,6 +125,7 @@ plugins.restapi.password_validation_regex: '(?=.*[A-Z])(?=.*[^a-zA-Z\d])(?=.*[0- plugins.restapi.password_validation_error_message: "Password must be minimum 8 characters long and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character." ``` + ## roles.yml This file contains any initial roles that you want to add to the security plugin. Aside from some metadata, the default file is empty, because the security plugin has a number of static roles that it adds automatically. From 47bd70cb2b14a2f61cc9d98cc5771a53706d4040 Mon Sep 17 00:00:00 2001 From: aetter Date: Sun, 11 Jul 2021 18:14:16 -0700 Subject: [PATCH 5/5] Update logs.md --- _opensearch/logs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/logs.md b/_opensearch/logs.md index 205bb0ae..57851372 100644 --- a/_opensearch/logs.md +++ b/_opensearch/logs.md @@ -11,7 +11,7 @@ The OpenSearch logs include valuable information for monitoring cluster operatio - On Docker, OpenSearch writes most logs to the console and stores the remainder in `opensearch/logs/`. The tarball installation also uses `opensearch/logs/`. - On most Linux installations, OpenSearch writes logs to `/var/log/opensearch/`. -Logs are available as `.log` (plain text) and `.json` files. +Logs are available as `.log` (plain text) and `.json` files. Permissions for the OpenSearch logs are `-rw-r--r--` by default, meaning that any user account on the node can read them. You can change this behavior _for each log type_ in `log4j2.properties` using the `filePermissions` option. For example, you might add `appender.rolling.filePermissions = rw-r-----` to change permissions for the JSON server log. For details, see the [Log4j 2 documentation](https://logging.apache.org/log4j/2.x/manual/appenders.html#RollingFileAppender). ## Application logs