Enhancing Security configuration steps (#8058)

* wip building out the security configuration steps

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* adding relevant links to docs.

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* adding further info to security settings

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* reviewdog issues fixed

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* paths given for 1.0 securityadmin

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Reconfiguring layout

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* updating security configuraton

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Update _security/configuration/index.md

Co-authored-by: Craig Perkins <craig5008@gmail.com>
Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com>

* Updates for examples given in config doc.
Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Add doc review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Update index.md

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Delete _security/configuration/test

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Made the securityadmin.sh backup tool instructions clearer
Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Update _security/configuration/index.md

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* updating the command for the securityadmin tool

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* reviewdog updates

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com>

* removing headings as links

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Updating headings to be headings and adding extra links at the end of the text, as is the standard (not to have hyperlinked headings).

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Update index.md

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

---------

Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com>
Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Co-authored-by: Craig Perkins <craig5008@gmail.com>
Co-authored-by: Melissa Vagi <vagimeli@amazon.com>
Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Co-authored-by: Nathan Bower <nbower@amazon.com>
(cherry picked from commit 9230b00)
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

_security/configuration/index.md

@@ -3,29 +3,113 @@ layout: default
 title: Configuration
 nav_order: 2
 has_children: true
-has_toc: false
+has_toc: true
 redirect_from:
   - /security-plugin/configuration/
   - /security-plugin/configuration/index/
 ---
 
 # Security configuration
 
-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:
+The Security plugin includes demo certificates so that you can get up and running quickly. To use OpenSearch with the Security plugin in a production environment, you must make changes to the demo certificates and other configuration options manually.
 
-1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#configuring-basic-security-settings).
-1. [Reconfigure `opensearch.yml` to use your certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls).
-1. [Reconfigure `config.yml` to use your authentication backend]({{site.url}}{{site.baseurl}}/security/configuration/configuration/) (if you don't plan to use the internal user database).
-1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml).
-1. If you plan to use the internal user database, [set a password policy in `opensearch.yml`]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#opensearchyml).
-1. [Apply changes using the `securityadmin` script]({{site.url}}{{site.baseurl}}/security/configuration/security-admin).
-1. Start OpenSearch.
-1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security/access-control/index/).
+## Replace the demo certificates
 
-If you don't want to use the plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security/configuration/disable-enable-security/).
+OpenSearch ships with demo certificates intended for quick setup and demonstration purposes. For a production environment, it's critical to replace these with your own trusted certificates, using the following steps, to ensure secure communication:
 
-The Security plugin has several default users, roles, action groups, permissions, and settings for OpenSearch Dashboards that use kibana in their names. We will change these names in a future release.
+1. **Generate your own certificates:** Use tools like OpenSSL or a certificate authority (CA) to generate your own certificates. For more information about generating certificates with OpenSSL, see [Generating self-signed certificates]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/).
+2. **Store the generated certificates and private key in the appropriate directory:** Generated certificates are typically stored in `<OPENSEARCH_HOME>/config/`. For more information, see [Add certificate files to opensearch.yml]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/#add-certificate-files-to-opensearchyml).
+3. **Set the following file permissions:**
+    - Private key (.key files): Set the file mode to `600`. This restricts access so that only the file owner (the OpenSearch user) can read and write to the file, ensuring that the private key remains secure and inaccessible to unauthorized users.
+    - Public certificates (.crt, .pem files): Set the file mode to `644`. This allows the file owner to read and write to the file, while other users can only read it.
+
+For additional guidance on file modes, see the following table.
+
+        | Item        | Sample              | Numeric | Bitwise      |
+        |-------------|---------------------|---------|--------------|
+        | Public key  | `~/.ssh/id_rsa.pub` | `644`   | `-rw-r--r--` |
+        | Private key | `~/.ssh/id_rsa`     | `600`   | `-rw-------` |
+        | SSH folder  | `~/.ssh`            | `700`   | `drwx------` |
+
+For more information, see [Configuring basic security settings]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#configuring-basic-security-settings).
+
+## Reconfigure `opensearch.yml` to use your certificates
+
+The `opensearch.yml` file is the main configuration file for OpenSearch; you can find the file at `<OPENSEARCH_HOME>/config/opensearch.yml`. Use the following steps to update this file to point to your custom certificates:
+
+In `opensearch.yml`, set the correct paths for your certificates and keys, as shown in the following example:
+   ```
+   plugins.security.ssl.transport.pemcert_filepath: /path/to/your/cert.pem
+   plugins.security.ssl.transport.pemkey_filepath: /path/to/your/key.pem
+   plugins.security.ssl.transport.pemtrustedcas_filepath: /path/to/your/ca.pem
+   plugins.security.ssl.http.enabled: true
+   plugins.security.ssl.http.pemcert_filepath: /path/to/your/cert.pem
+   plugins.security.ssl.http.pemkey_filepath: /path/to/your/key.pem
+   plugins.security.ssl.http.pemtrustedcas_filepath: /path/to/your/ca.pem
+   ```
+For more information, see [Configuring TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/).
+
+## Reconfigure `config.yml` to use your authentication backend
+
+The `config.yml` file allows you to configure the authentication and authorization mechanisms for OpenSearch. Update the authentication backend settings in `<OPENSEARCH_HOME>/config/opensearch-security/config.yml` according to your requirements. 
+
+For example, to use LDAP as your authentication backend, add the following settings:
+
+  ```
+    authc:
+      basic_internal_auth:
+        http_enabled: true
+        transport_enabled: true
+        order: 1
+        http_authenticator:
+          type: basic
+          challenge: true
+        authentication_backend:
+          type: internal
+   ```
+For more information, see [Configuring the Security backend]({{site.url}}{{site.baseurl}}/security/configuration/configuration/).
+
+## Modify the configuration YAML files
+
+Determine whether any additional YAML files need modification, for example, the `roles.yml`, `roles_mapping.yml`, or `internal_users.yml` files. Update the files with any additional configuration information. For more information, see [Modifying the YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/).
+
+## Set a password policy
+
+When using the internal user database, we recommend enforcing a password policy to ensure that strong passwords are used. For information about strong password policies, see [Password settings]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#password-settings).
+
+## Apply changes using the `securityadmin` script
+
+The following steps do not apply to first-time users because the security index is automatically initialized from the YAML configuration files when OpenSearch starts.
+{: .note}
+
+After initial setup, if you make changes to your security configuration or disable automatic initialization by setting `plugins.security.allow_default_init_securityindex` to `false` (which prevents security index initialization from `yaml` files), you need to manually apply changes using the `securityadmin` script:
+
+1. Find the `securityadmin` script. The script is typically stored in the OpenSearch plugins directory, `plugins/opensearch-security/tools/securityadmin.[sh|bat]`. 
+   - Note: If you're using OpenSearch 1.x, the `securityadmin` script is located in the `plugins/opendistro_security/tools/` directory. 
+   - For more information, see [Basic usage](https://opensearch.org/docs/latest/security/configuration/security-admin/#basic-usage).
+2. Run the script by using the following command:
+   ```
+    ./plugins/opensearch-security/tools/securityadmin.[sh|bat]
+   ```
+3. Check the OpenSearch logs and configuration to ensure that the changes have been successfully applied.
+
+For more information about using the `securityadmin` script, see [Applying changes to configuration files]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/).
+
+## Add users, roles, role mappings, and tenants
+
+If you don't want to use the Security plugin, you can disable it by adding the following setting to the `opensearch.yml` file:
+
+```
+plugins.security.disabled: true
+```
+
+You can then enable the plugin by removing the `plugins.security.disabled` setting.
+
+For more information about disabling the Security plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security/configuration/disable-enable-security/).
+
+The Security plugin has several default users, roles, action groups, permissions, and settings for OpenSearch Dashboards that contain "Kibana" in their names. We will change these names in a future version.
 {: .note }
 
-For a full list of `opensearch.yml` Security plugin settings, Security plugin settings, see [Security settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/security-settings/).
+For a full list of `opensearch.yml` Security plugin settings, see [Security settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/security-settings/).
 {: .note}
+