From 12715e30fb0eafb930efcb31ea3db73271eab3e8 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Tue, 8 Nov 2022 11:52:04 -0500 Subject: [PATCH] Adds Windows security documentation (#1821) * Adds Windows security documentation Signed-off-by: Fanit Kolchina * Incorporated tech reveiw feedback Signed-off-by: Fanit Kolchina * Included powershell and removed call Signed-off-by: Fanit Kolchina * Changed to backslashes Signed-off-by: Fanit Kolchina * Incorporated doc review feedback Signed-off-by: Fanit Kolchina * Incorporated editorial feedback Signed-off-by: Fanit Kolchina Signed-off-by: Fanit Kolchina --- _security-plugin/configuration/index.md | 10 +++---- .../configuration/security-admin.md | 30 +++++++++++++++++-- _security-plugin/configuration/tls.md | 2 +- _security-plugin/configuration/yaml.md | 2 +- 4 files changed, 35 insertions(+), 9 deletions(-) diff --git a/_security-plugin/configuration/index.md b/_security-plugin/configuration/index.md index 92ced6b8..f5a96d57 100644 --- a/_security-plugin/configuration/index.md +++ b/_security-plugin/configuration/index.md @@ -10,14 +10,14 @@ redirect_from: # Security configuration -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: +The plugin includes demo certificates so that you can get up and running quickly. To use OpenSearch in a production environment, you must configure it manually: 1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker#configuring-basic-security-settings). -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. [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. 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 the `securityadmin` script]({{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/security-admin.md b/_security-plugin/configuration/security-admin.md index 881191e6..975d7b35 100755 --- a/_security-plugin/configuration/security-admin.md +++ b/_security-plugin/configuration/security-admin.md @@ -1,11 +1,14 @@ --- layout: default -title: Apply changes with securityadmin.sh +title: Apply changes with the securityadmin script parent: Configuration nav_order: 20 --- -# Apply changes using securityadmin.sh +# Apply changes with the securityadmin script + +On **Windows**, use **securityadmin.bat** in place of **securityadmin.sh**. For more information, see [Windows usage](#windows-usage). +{: .note} The security plugin stores its configuration---including users, roles, and permissions---in an index on the OpenSearch cluster (`.opendistro_security`). Storing these settings in an index lets you change settings without restarting the cluster and eliminates the need to edit configuration files on every single node. @@ -299,3 +302,26 @@ Name | Description `-era` | Enable replica auto-expand. `-dra` | Disable replica auto-expand. `-us` | Update the replica settings. + +## Windows usage + +On Windows, the equivalent of `securityadmin.sh` is the `securityadmin.bat` script located in the `\path\to\opensearch-{{site.opensearch_version}}\plugins\opensearch-security\tools\` directory. + +When running the example commands in the preceding sections, use the **command prompt** or **Powershell**. Open the command prompt by entering `cmd` or Powershell by entering `powershell` in the search box next to **Start** on the taskbar. + +For example, to print all available command line options, run the script with no arguments: + +```bat +.\plugins\opensearch-security\tools\securityadmin.bat +``` + +When entering a multiline command, use the caret (`^`) character to escape the next character in the command line. + +For example, to load your initial configuration (all YAML files), use the following command: + +```bat +.\securityadmin.bat -cd ..\..\..\config\opensearch-security\ -icl -nhnv ^ + -cacert ..\..\..\config\root-ca.pem ^ + -cert ..\..\..\config\kirk.pem ^ + -key ..\..\..\config\kirk-key.pem +``` \ No newline at end of file diff --git a/_security-plugin/configuration/tls.md b/_security-plugin/configuration/tls.md index 9c0c7508..c0cab946 100755 --- a/_security-plugin/configuration/tls.md +++ b/_security-plugin/configuration/tls.md @@ -91,7 +91,7 @@ If your node certificates have an Object ID (OID) identifier in the SAN section, ## Configure admin certificates -Admin certificates are regular client certificates that have elevated rights to perform administrative tasks. You need an admin certificate to change the the security plugin configuration using `plugins/opensearch-security/tools/securityadmin.sh` or the REST API. Admin certificates are configured in `opensearch.yml` by stating their DN(s): +Admin certificates are regular client certificates that have elevated rights to perform administrative tasks. You need an admin certificate to change the security plugin configuration using [`plugins/opensearch-security/tools/securityadmin.sh`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) or the REST API. Admin certificates are configured in `opensearch.yml` by stating their DN(s): ```yml plugins.security.authcz.admin_dn: diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index 12c587fc..a70fd552 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -7,7 +7,7 @@ nav_order: 4 # YAML files -Before running `securityadmin.sh` to load the settings into the `.opendistro_security` index, configure the YAML files in `config/opensearch-security`. You might want to back up these files so that you can reuse them on other clusters. +Before running [`securityadmin.sh`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) to load the settings into the `.opendistro_security` index, configure the YAML files in `config/opensearch-security`. You might want to back up these files so that you can reuse them on other clusters. The best use of these YAML files is to configure [reserved and hidden resources]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#reserved-and-hidden-resources), such as the `admin` and `kibanaserver` users. You might find it easier to create other users, roles, mappings, action groups, and tenants using OpenSearch Dashboards or the REST API.