From f04171e54df0c5ecb00eed7f059c5761bcbc1e06 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 31 Jan 2023 12:13:28 -0600 Subject: [PATCH] Reorganize Configuration section of the Security TOC (#2212) (#2532) * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum * Rename security section. Fix links. Add redirects Signed-off-by: Naarcha-AWS --------- Signed-off-by: cwillum Signed-off-by: Naarcha-AWS Co-authored-by: Naarcha-AWS (cherry picked from commit d04e88b496485474fc3d89bd42ea36e834d6a64c) Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com> --- README.md | 2 +- _config.yml | 6 +- _dashboards/reporting.md | 2 +- _im-plugin/ism/index.md | 2 +- _im-plugin/security.md | 6 +- _install-and-configure/configuration.md | 2 +- .../install-dashboards/tls.md | 4 +- .../install-opensearch/docker.md | 13 +- .../install-opensearch/rpm.md | 12 +- .../install-opensearch/tar.md | 12 +- .../install-opensearch/windows.md | 4 +- _install-and-configure/plugins.md | 2 +- _monitoring-plugins/ad/security.md | 8 +- _monitoring-plugins/alerting/monitors.md | 2 +- _monitoring-plugins/alerting/security.md | 52 +++++- _monitoring-plugins/alerting/settings.md | 2 +- _observability-plugin/notebooks.md | 2 +- .../observability-security.md | 4 +- _opensearch/cluster.md | 2 +- _opensearch/snapshots/snapshot-management.md | 2 +- _opensearch/snapshots/snapshot-restore.md | 8 +- _replication-plugin/permissions.md | 6 +- _search-plugins/async/security.md | 6 +- .../access-control/multi-tenancy.md | 168 ------------------ _security-plugin/configuration/concepts.md | 26 --- .../configuration/system-indices.md | 25 --- .../access-control/api.md | 12 +- .../access-control/cross-cluster-search.md | 2 +- .../access-control/default-action-groups.md | 4 +- .../access-control/document-level-security.md | 8 +- .../access-control/field-level-security.md | 8 +- .../access-control/field-masking.md | 6 +- .../access-control/impersonation.md | 2 +- .../access-control/index.md | 8 +- .../access-control/permissions.md | 8 +- .../access-control/users-roles.md | 20 +-- .../audit-logs/field-reference.md | 2 +- .../audit-logs/index.md | 4 +- .../audit-logs/storage-types.md | 2 +- .../authentication-backends/authc-index.md | 31 ++++ .../authentication-backends}/client-auth.md | 15 +- .../authentication-backends}/ldap.md | 7 +- .../openid-connect.md | 6 +- .../authentication-backends}/proxy.md | 4 +- .../authentication-backends}/saml.md | 12 +- .../configuration/configuration.md | 12 +- .../configuration/disable.md | 8 +- .../configuration/generate-certificates.md | 14 +- .../configuration/index.md | 20 +-- .../configuration/security-admin.md | 43 ++--- _security/configuration/system-indices.md | 26 +++ .../configuration/tls.md | 8 +- .../configuration/yaml.md | 22 +-- {_security-plugin => _security}/index.md | 22 +-- _troubleshoot/security-admin.md | 2 +- index.md | 4 +- quickstart.md | 4 +- 57 files changed, 312 insertions(+), 414 deletions(-) delete mode 100644 _security-plugin/access-control/multi-tenancy.md delete mode 100755 _security-plugin/configuration/concepts.md delete mode 100644 _security-plugin/configuration/system-indices.md rename {_security-plugin => _security}/access-control/api.md (97%) rename {_security-plugin => _security}/access-control/cross-cluster-search.md (99%) rename {_security-plugin => _security}/access-control/default-action-groups.md (96%) rename {_security-plugin => _security}/access-control/document-level-security.md (91%) rename {_security-plugin => _security}/access-control/field-level-security.md (85%) rename {_security-plugin => _security}/access-control/field-masking.md (90%) rename {_security-plugin => _security}/access-control/impersonation.md (98%) rename {_security-plugin => _security}/access-control/index.md (78%) rename {_security-plugin => _security}/access-control/permissions.md (92%) rename {_security-plugin => _security}/access-control/users-roles.md (87%) rename {_security-plugin => _security}/audit-logs/field-reference.md (99%) rename {_security-plugin => _security}/audit-logs/index.md (98%) rename {_security-plugin => _security}/audit-logs/storage-types.md (99%) create mode 100755 _security/authentication-backends/authc-index.md rename {_security-plugin/configuration => _security/authentication-backends}/client-auth.md (72%) rename {_security-plugin/configuration => _security/authentication-backends}/ldap.md (99%) rename {_security-plugin/configuration => _security/authentication-backends}/openid-connect.md (98%) rename {_security-plugin/configuration => _security/authentication-backends}/proxy.md (99%) rename {_security-plugin/configuration => _security/authentication-backends}/saml.md (97%) rename {_security-plugin => _security}/configuration/configuration.md (97%) rename {_security-plugin => _security}/configuration/disable.md (93%) rename {_security-plugin => _security}/configuration/generate-certificates.md (93%) rename {_security-plugin => _security}/configuration/index.md (50%) rename {_security-plugin => _security}/configuration/security-admin.md (82%) create mode 100644 _security/configuration/system-indices.md rename {_security-plugin => _security}/configuration/tls.md (96%) rename {_security-plugin => _security}/configuration/yaml.md (84%) rename {_security-plugin => _security}/index.md (80%) diff --git a/README.md b/README.md index 8b9b1b5aa2..c23177aa44 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ If you're making major changes to the documentation and need to see the rendered 1. Create a new branch. -1. Edit the Markdown files in each collection (e.g. `_security-plugin/`). +1. Edit the Markdown files in each collection (e.g. `_security/`). If you're a web developer, you can customize `_layouts/default.html` and `_sass/custom/custom.scss`. diff --git a/_config.yml b/_config.yml index fe70718a6a..55b5bd690a 100644 --- a/_config.yml +++ b/_config.yml @@ -40,7 +40,7 @@ collections: dashboards: permalink: /:collection/:path/ output: true - security-plugin: + security: permalink: /:collection/:path/ output: true search-plugins: @@ -97,8 +97,8 @@ just_the_docs: dashboards: name: OpenSearch Dashboards nav_fold: true - security-plugin: - name: Security plugin + security: + name: Security in OpenSearch nav_fold: true search-plugins: name: Search plugins diff --git a/_dashboards/reporting.md b/_dashboards/reporting.md index 6f1637c1d7..5be825fdca 100644 --- a/_dashboards/reporting.md +++ b/_dashboards/reporting.md @@ -7,7 +7,7 @@ nav_order: 20 # Reporting -You can use OpenSearch Dashboards to create PNG, PDF, and CSV reports. To create reports, you must have the correct permissions. For a summary of the predefined roles and the permissions they grant, see the [security plugin]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +You can use OpenSearch Dashboards to create PNG, PDF, and CSV reports. To create reports, you must have the correct permissions. For a summary of the predefined roles and the permissions they grant, see the [security plugin]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). CSV reports have a non-configurable 10,000 row limit. They have no explicit size limit (e.g. in MB), but extremely large documents could cause report generation to fail with an out of memory error from the V8 JavaScript engine. {: .tip } diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 61d761b267..c37a395b1c 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -20,7 +20,7 @@ For example, you can define a policy that moves your index into a `read_only` st You might want to perform an index rollover after a certain amount of time or run a `force_merge` operation on an index during off-peak hours to improve search performance during peak hours. -To use the ISM plugin, your user role needs to be mapped to the `all_access` role that gives you full access to the cluster. To learn more, see [Users and roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/). +To use the ISM plugin, your user role needs to be mapped to the `all_access` role that gives you full access to the cluster. To learn more, see [Users and roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/). {: .note } ## Get started with ISM diff --git a/_im-plugin/security.md b/_im-plugin/security.md index d5d48ac6e9..0fb7dbeb35 100644 --- a/_im-plugin/security.md +++ b/_im-plugin/security.md @@ -9,11 +9,11 @@ has_children: false Using the security plugin with index management lets you limit non-admin users to certain actions. For example, you might want to set up your security such that a group of users can only read ISM policies, while others can create, delete, or change policies. -All index management data are protected as system indices, and only a super admin or an admin with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices). +All index management data are protected as system indices, and only a super admin or an admin with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security/configuration/system-indices). ## Basic permissions -The security plugin comes with one role that offers full access to index management: `index_management_full_access`. For a description of the role's permissions, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +The security plugin comes with one role that offers full access to index management: `index_management_full_access`. For a description of the role's permissions, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). With security enabled, users not only need the correct index management permissions, but they also need permissions to execute actions to involved indices. For example, if a user wants to use the REST API to attach a policy that executes a rollup job to an index named `system-logs`, they would need the permissions to attach a policy and execute a rollup job, as well as access to `system-logs`. @@ -23,7 +23,7 @@ Finally, with the exceptions of Create Policy, Get Policy, and Delete Policy, us You can use backend roles to configure fine-grained access to index management policies and actions. For example, users of different departments in an organization might view different policies depending on what roles and permissions they are assigned. -First, ensure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user). +First, ensure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security/access-control/api#create-user). Use the REST API to enable the following setting: diff --git a/_install-and-configure/configuration.md b/_install-and-configure/configuration.md index 3293d9038e..29aea0ebe4 100755 --- a/_install-and-configure/configuration.md +++ b/_install-and-configure/configuration.md @@ -86,7 +86,7 @@ action.auto_create_index: true compatibility.override_main_response_version: true ``` -The demo configuration includes a number of settings for the security plugin that you should modify before using OpenSearch for a production workload. To learn more, see [Security]({{site.url}}{{site.baseurl}}/security-plugin/). +The demo configuration includes a number of settings for the security plugin that you should modify before using OpenSearch for a production workload. To learn more, see [Security]({{site.url}}{{site.baseurl}}/security/). ### (Optional) CORS header configuration If you are working on a client application running against an OpenSearch cluster on a different domain, you can configure headers in `opensearch.yml` to allow for developing a local application on the same machine. Use [Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) so your application can make calls to the OpenSearch API running locally. Add the following lines in your `custom-opensearch.yml` file (note that the "-" must be the first character in each line). diff --git a/_install-and-configure/install-dashboards/tls.md b/_install-and-configure/install-dashboards/tls.md index 0410d80715..4bd4dac5e2 100644 --- a/_install-and-configure/install-dashboards/tls.md +++ b/_install-and-configure/install-dashboards/tls.md @@ -16,8 +16,8 @@ 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 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 to one or more CA certificates that comprise a trusted chain for your OpenSearch cluster. For example, you might need to include a root CA _and_ an intermediate CA if you used the intermediate CA to issue your admin, client, and node certificates. 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 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. +server.ssl.certificate | If `server.ssl.enabled` is true, specify the full path to a valid client certificate for your OpenSearch cluster. You can [generate your own]({{site.url}}{{site.baseurl}}/security/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/configuration/generate-certificates/) or get one from a certificate authority. 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: diff --git a/_install-and-configure/install-opensearch/docker.md b/_install-and-configure/install-opensearch/docker.md index b394b0c3e9..fc3ed6e3c8 100644 --- a/_install-and-configure/install-opensearch/docker.md +++ b/_install-and-configure/install-opensearch/docker.md @@ -356,7 +356,7 @@ networks: ### Configuring basic security settings -Before making your OpenSearch cluster available to external hosts, it's a good idea to review the deployment's security configuration. You may recall from the first [Sample docker-compose.yml](#sample-docker-composeyml) file that, unless disabled by setting `DISABLE_SECURITY_PLUGIN=true`, a bundled script will apply a default demo security configuration to the nodes in the cluster. Because this configuration is used for demo purposes, the default usernames and passwords are known. For that reason, we recommend that you create your own security configuration files and use `volumes` to pass these files to the containers. For specific guidance on OpenSearch security settings, see [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/). +Before making your OpenSearch cluster available to external hosts, it's a good idea to review the deployment's security configuration. You may recall from the first [Sample docker-compose.yml](#sample-docker-composeyml) file that, unless disabled by setting `DISABLE_SECURITY_PLUGIN=true`, a bundled script will apply a default demo security configuration to the nodes in the cluster. Because this configuration is used for demo purposes, the default usernames and passwords are known. For that reason, we recommend that you create your own security configuration files and use `volumes` to pass these files to the containers. For specific guidance on OpenSearch security settings, see [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/). To use your own certificates in your configuration, add all of the necessary certificates to the volumes section of the compose file: ```yml @@ -379,7 +379,7 @@ volumes: - ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml ``` -Remember that the certificates you specify in your compose file must be the same as the certificates defined in your custom `opensearch.yml` file. You should replace the root, admin, and node certificates with your own. For more information see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls). +Remember that the certificates you specify in your compose file must be the same as the certificates defined in your custom `opensearch.yml` file. You should replace the root, admin, and node certificates with your own. For more information see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls). ```yml plugins.security.ssl.transport.pemcert_filepath: node1.pem plugins.security.ssl.transport.pemkey_filepath: node1-key.pem @@ -415,9 +415,9 @@ opendistro_security.audit.config.disabled_rest_categories: NONE opendistro_security.audit.config.disabled_transport_categories: NONE ``` -For a full list of settings, see [Security]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/). +For a full list of settings, see [Security]({{site.url}}{{site.baseurl}}/security/configuration/index/). -Use the same process to specify a [Backend configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) in `/usr/share/opensearch/config/opensearch-security/config.yml` as well as new internal users, roles, mappings, action groups, and tenants in their respective [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/). +Use the same process to specify a [Backend configuration]({{site.url}}{{site.baseurl}}/security/configuration/configuration/) in `/usr/share/opensearch/config/opensearch-security/config.yml` as well as new internal users, roles, mappings, action groups, and tenants in their respective [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/). After replacing the certificates and creating your own internal users, roles, mappings, action groups, and tenants, use Docker Compose to start the cluster: ```bash @@ -446,7 +446,7 @@ FROM opensearchproject/opensearch:latest RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch-security ``` -You can also use a Dockerfile to pass your own certificates for use with the [Security Plugin]({{site.url}}{{site.baseurl}}/security-plugin/): +You can also use a Dockerfile to pass your own certificates for use with the [Security Plugin]({{site.url}}{{site.baseurl}}/security/): ``` FROM opensearchproject/opensearch:latest COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/ @@ -460,4 +460,5 @@ COPY --chown=opensearch:opensearch my-root-cas.pem /usr/share/opensearch/config/ - [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [Performance analyzer]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/) - [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) -- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) +- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/) + diff --git a/_install-and-configure/install-opensearch/rpm.md b/_install-and-configure/install-opensearch/rpm.md index bf4d512c00..d84ca76e37 100644 --- a/_install-and-configure/install-opensearch/rpm.md +++ b/_install-and-configure/install-opensearch/rpm.md @@ -115,7 +115,7 @@ Before proceeding with any configuration, you should test your installation of O When OpenSearch is installed using the RPM package, some demo security settings are automatically applied. This includes self-signed TLS certificates and several users and roles. If you would like to configure these yourself, see [Set up OpenSearch in your environment](#step-3-set-up-opensearch-in-your-environment). -An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. +An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. {: .warning} 1. Send requests to the server to verify that OpenSearch is running. Note the use of the `--insecure` flag, which is required because the TLS certificates are self-signed. @@ -222,7 +222,7 @@ Before modifying any configuration files, it's always a good idea to save a back ### Configure TLS -TLS certificates provide additional security for your cluster by allowing clients to confirm the identity of hosts and encrypt traffic between the client and host. For more information, refer to [Configure TLS Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/) and [Generate Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/), which are included in the [Security Plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) documentation. For work performed in a development environment, self-signed certificates are usually adequate. This section will guide you through the basic steps required to generate your own TLS certificates and apply them to your OpenSearch host. +TLS certificates provide additional security for your cluster by allowing clients to confirm the identity of hosts and encrypt traffic between the client and host. For more information, refer to [Configure TLS Certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/) and [Generate Certificates]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/), which are included in the [Security Plugin]({{site.url}}{{site.baseurl}}/security/index/) documentation. For work performed in a development environment, self-signed certificates are usually adequate. This section will guide you through the basic steps required to generate your own TLS certificates and apply them to your OpenSearch host. 1. Navigate to the directory where the certificates will be stored. ```bash @@ -283,7 +283,7 @@ TLS certificates provide additional security for your cluster by allowing client ```bash sudo chown opensearch:opensearch admin-key.pem admin.pem node1-key.pem node1.pem root-ca-key.pem root-ca.pem root-ca.srl ``` -1. Add these certificates to `opensearch.yml` as described in [Generate Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml). Advanced users might also choose to append the settings using a script: +1. Add these certificates to `opensearch.yml` as described in [Generate Certificates]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml). Advanced users might also choose to append the settings using a script: ```bash #! /bin/bash @@ -318,7 +318,7 @@ TLS certificates provide additional security for your cluster by allowing client ### Configure a user -Users are defined and authenticated by OpenSearch in a variety of ways. One method that does not require additional backend infrastructure is to manually configure users in `internal_users.yml`. See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/) for more information about configuring users. The following steps explain how to remove all demo users except for the `admin` user and how to replace the `admin` default password using a script. +Users are defined and authenticated by OpenSearch in a variety of ways. One method that does not require additional backend infrastructure is to manually configure users in `internal_users.yml`. See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/) for more information about configuring users. The following steps explain how to remove all demo users except for the `admin` user and how to replace the `admin` default password using a script. 1. Navigate to the security plugins tools directory. ```bash @@ -379,7 +379,7 @@ Now that TLS certificates are installed and demo users were removed or assigned # Change to the correct directory cd /usr/share/opensearch/plugins/opensearch-security/tools ``` -1. Invoke the script. See [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) for definitions of the arguments you must pass. +1. Invoke the script. See [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/) for definitions of the arguments you must pass. ```bash # You can omit the environment variable if you declared this in your $PATH. OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./securityadmin.sh -cd /etc/opensearch/opensearch-security/ -cacert /etc/opensearch/root-ca.pem -cert /etc/opensearch/admin.pem -key /etc/opensearch/admin-key.pem -icl -nhnv @@ -446,4 +446,4 @@ sudo yum update - [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) - [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) -- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file +- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/) \ No newline at end of file diff --git a/_install-and-configure/install-opensearch/tar.md b/_install-and-configure/install-opensearch/tar.md index 48995be924..e22be71f47 100644 --- a/_install-and-configure/install-opensearch/tar.md +++ b/_install-and-configure/install-opensearch/tar.md @@ -81,7 +81,7 @@ The demo security script will apply a generic configuration to your instance of If you only want to verify that the service is properly configured and you intend to configure security settings yourself, then you may want to disable the security plugin and launch the service without encryption or authentication. -An OpenSearch node configured by the demo security script is not suitable for a production environment. If you plan to use the node in a production environment after running `opensearch-tar-install.sh`, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. +An OpenSearch node configured by the demo security script is not suitable for a production environment. If you plan to use the node in a production environment after running `opensearch-tar-install.sh`, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. {: .warning} ### Option 1: Test your Opensearch settings with security enabled @@ -264,7 +264,7 @@ Before modifying any configuration files, it's always a good idea to save a back ### Configure TLS -TLS certificates provide additional security for your cluster by allowing clients to confirm the identity of hosts and encrypt traffic between the client and host. For more information, refer to [Configure TLS Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/) and [Generate Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/), which are included in the [Security Plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) documentation. For work performed in a development environment, self-signed certificates are usually adequate. This section will guide you through the basic steps required to generate your own TLS certificates and apply them to your OpenSearch host. +TLS certificates provide additional security for your cluster by allowing clients to confirm the identity of hosts and encrypt traffic between the client and host. For more information, refer to [Configure TLS Certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/) and [Generate Certificates]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/), which are included in the [Security Plugin]({{site.url}}{{site.baseurl}}/security/index/) documentation. For work performed in a development environment, self-signed certificates are usually adequate. This section will guide you through the basic steps required to generate your own TLS certificates and apply them to your OpenSearch host. 1. Navigate to the OpenSearch `config` directory. This is where the certificates will be stored. ```bash @@ -317,7 +317,7 @@ TLS certificates provide additional security for your cluster by allowing client ```bash rm *temp.pem *csr *ext ``` -1. Add these certificates to `opensearch.yml` as described in [Generate Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml). Advanced users might also choose to append the settings using a script: +1. Add these certificates to `opensearch.yml` as described in [Generate Certificates]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml). Advanced users might also choose to append the settings using a script: ```bash #! /bin/bash @@ -353,7 +353,7 @@ TLS certificates provide additional security for your cluster by allowing client ### Configure a user -Users are defined and authenticated by OpenSearch in a variety of ways. One method, which does not require additional backend infrastructure, is to manually configure users in `internal_users.yml`. See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/) for more information about configuring users. The following steps explain how to remove all demo users except for the `admin` user and how to replace the `admin` default password using a script. +Users are defined and authenticated by OpenSearch in a variety of ways. One method, which does not require additional backend infrastructure, is to manually configure users in `internal_users.yml`. See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/) for more information about configuring users. The following steps explain how to remove all demo users except for the `admin` user and how to replace the `admin` default password using a script. 1. Make the security plugin scripts executable. ```bash @@ -418,7 +418,7 @@ Now that TLS certificates are installed and demo users were removed or assigned # Change to the correct directory cd /path/to/opensearch-{{site.opensearch_version}}/plugins/opensearch-security/tools ``` -1. Invoke the script. See [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) for definitions of the arguments you must pass. +1. Invoke the script. See [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/) for definitions of the arguments you must pass. ```bash # You can omit the environment variable if you declared this in your $PATH. OPENSEARCH_JAVA_HOME=/path/to/opensearch-{{site.opensearch_version}}/jdk ./securityadmin.sh -cd /path/to/opensearch-{{site.opensearch_version}}/config/opensearch-security/ -cacert /path/to/opensearch-{{site.opensearch_version}}/config/root-ca.pem -cert /path/to/opensearch-{{site.opensearch_version}}/config/admin.pem -key /path/to/opensearch-{{site.opensearch_version}}/config/admin-key.pem -icl -nhnv @@ -541,4 +541,4 @@ The following configuration is only suitable for testing in a non-production env - [Configure Performance Analyzer for Tarball Installation]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/#install-performance-analyzer) - [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) - [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) -- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file +- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/) \ No newline at end of file diff --git a/_install-and-configure/install-opensearch/windows.md b/_install-and-configure/install-opensearch/windows.md index c6f7a70cf8..24a0d5e175 100644 --- a/_install-and-configure/install-opensearch/windows.md +++ b/_install-and-configure/install-opensearch/windows.md @@ -42,7 +42,7 @@ The batch script will apply a generic configuration to your instance of OpenSear If you only want to verify that the service is properly configured and you intend to configure security settings yourself, then you may want to disable the security plugin and launch the service without encryption or authentication. -An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. +An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. {: .warning} ### Option 1: Test your OpenSearch settings with security enabled @@ -246,4 +246,4 @@ The Performance Analyzer plugin is not available on Windows. All other OpenSearc - [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) -- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file +- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/) \ No newline at end of file diff --git a/_install-and-configure/plugins.md b/_install-and-configure/plugins.md index 2c715ac99f..dabac1a0d6 100644 --- a/_install-and-configure/plugins.md +++ b/_install-and-configure/plugins.md @@ -293,7 +293,7 @@ Members of the OpenSearch community have built countless plugins for the service - [About Observability]({{site.url}}{{site.baseurl}}/observability-plugin/index/) - [About security analytics]({{site.url}}{{site.baseurl}}/security-analytics/index/) -- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) +- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/) - [Alerting]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/index/) - [Anomaly detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/index/) - [Asynchronous search]({{site.url}}{{site.baseurl}}/search-plugins/async/index/) diff --git a/_monitoring-plugins/ad/security.md b/_monitoring-plugins/ad/security.md index dd8e57abed..777bb41679 100644 --- a/_monitoring-plugins/ad/security.md +++ b/_monitoring-plugins/ad/security.md @@ -10,7 +10,7 @@ has_children: false You can use the security plugin with anomaly detection in OpenSearch to limit non-admin users to specific actions. For example, you might want some users to only be able to create, update, or delete detectors, while others to only view detectors. -All anomaly detection indices are protected as system indices. Only a super admin user or an admin user with a TLS certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/). +All anomaly detection indices are protected as system indices. Only a super admin user or an admin user with a TLS certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security/configuration/system-indices/). Security for anomaly detection works the same as [security for alerting]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/). @@ -19,15 +19,15 @@ Security for anomaly detection works the same as [security for alerting]({{site. As an admin user, you can use the security plugin to assign specific permissions to users based on which APIs they need access to. For a list of supported APIs, see [Anomaly detection API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/). -The security plugin has two built-in roles that cover most anomaly detection use cases: `anomaly_full_access` and `anomaly_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +The security plugin has two built-in roles that cover most anomaly detection use cases: `anomaly_full_access` and `anomaly_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). -If these roles don't meet your needs, mix and match individual anomaly detection [permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/ad/detector/delete` permission lets you delete detectors. +If these roles don't meet your needs, mix and match individual anomaly detection [permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/ad/detector/delete` permission lets you delete detectors. ## (Advanced) Limit access by backend role Use backend roles to configure fine-grained access to individual detectors based on roles. For example, users of different departments in an organization can view detectors owned by their own department. -First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user). +First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security/access-control/api#create-user). Next, enable the following setting: diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index e33768c4e6..5ced6251ac 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -193,7 +193,7 @@ Per query monitors run your specified query and then check whether the query's r To define a monitor visually, choose **Visual editor**. Then choose a source index, a timeframe, an aggregation (for example, `count()` or `average()`), a data filter if you want to monitor a subset of your source index, and a group-by field if you want to include an aggregation field in your query. At least one group-by field is required if you're defining a bucket-level monitor. Visual definition works well for most monitors. - If you use the Security plugin, you can only choose indexes that you have permission to access. For details, see [Alerting security]({{site.url}}{{site.baseurl}}/security-plugin/). + If you use the Security plugin, you can only choose indexes that you have permission to access. For details, see [Alerting security]({{site.url}}{{site.baseurl}}/security/). To use a query, choose **Extraction query editor**, add your query (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/)), and test it using the **Run** button. diff --git a/_monitoring-plugins/alerting/security.md b/_monitoring-plugins/alerting/security.md index c934c45d6c..c71910e066 100644 --- a/_monitoring-plugins/alerting/security.md +++ b/_monitoring-plugins/alerting/security.md @@ -13,9 +13,9 @@ If you use the security plugin alongside alerting, you might want to limit certa ## Basic permissions -The security plugin has three built-in roles that cover most alerting use cases: `alerting_read_access`, `alerting_ack_alerts`, and `alerting_full_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +The security plugin has three built-in roles that cover most alerting use cases: `alerting_read_access`, `alerting_ack_alerts`, and `alerting_full_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). -If these roles don't meet your needs, mix and match individual alerting [permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/alerting/destination/delete` permission lets you delete destinations. +If these roles don't meet your needs, mix and match individual alerting [permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/alerting/destination/delete` permission lets you delete destinations. ## How monitors access data @@ -29,7 +29,7 @@ Later, the user `psantos` wants to edit the monitor to run every two hours, but - Update the monitor so that it only checks `store1-returns`. - Ask an administrator for read access to the other two indices. -After making the change, the monitor now runs with the same permissions as `psantos`, including any [document-level security]({{site.url}}{{site.baseurl}}/security-plugin/access-control/document-level-security/) queries, [excluded fields]({{site.url}}{{site.baseurl}}/security-plugin/access-control/field-level-security/), and [masked fields]({{site.url}}{{site.baseurl}}/security-plugin/access-control/field-masking/). If you use an extraction query to define your monitor, use the **Run** button to ensure that the response includes the fields you need. +After making the change, the monitor now runs with the same permissions as `psantos`, including any [document-level security]({{site.url}}{{site.baseurl}}/security/access-control/document-level-security/) queries, [excluded fields]({{site.url}}{{site.baseurl}}/security/access-control/field-level-security/), and [masked fields]({{site.url}}{{site.baseurl}}/security/access-control/field-masking/). If you use an extraction query to define your monitor, use the **Run** button to ensure that the response includes the fields you need. Once a monitor is created, the Alerting plugin will continue executing the monitor, even if the user who created the monitor has their permissions removed. Only a user with the correct cluster permissions can manually disable or delete a monitor to stop it from executing: @@ -42,7 +42,7 @@ If your monitor's trigger has notifications configured, the Alerting plugin cont Out of the box, the alerting plugin has no concept of ownership. For example, if you have the `cluster:admin/opensearch/alerting/monitor/write` permission, you can edit *all* monitors, regardless of whether you created them. If a small number of trusted users manage your monitors and destinations, this lack of ownership generally isn't a problem. A larger organization might need to segment access by backend role. -First, make sure that your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user). +First, make sure that your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security/configuration/saml/). However, if you use the internal user database, you can use the REST API to add them manually with a create user operation. To add a backend role to a create user request, follow the [Create user]({{site.url}}{{site.baseurl}}/security/access-control/api#create-user) instructions in the Security Plugin API documentation. Next, enable the following setting: @@ -63,7 +63,7 @@ If `jdoe` creates a monitor, `jroe` can see and modify it, but `psantos` can't. +<<<<<<< HEAD +======= + +### Specify RBAC backend roles + +You can specify role-based access control (RBAC) backend roles when you create or update a monitor with the Alerting API. + +In a create monitor scenario, follow these guidelines to specify roles: + +User type | Role is specified by user or not (Y/N) | How to use the RBAC roles +:--- | :--- | :--- +Admin user | Yes | Use all the specified backend roles to associate to the monitor. +Regular user | Yes | Use all the specified backend roles from the list of backend roles that the user has permission to use to associate with the monitor. +Regular user | No | Copy user’s backend roles and associate them to the monitor. + +In an update monitor scenario, follow these guidelines to specify roles: + +User type | Role is specified by user or not (Y/N) | How to use the RBAC roles +:--- | :--- | :--- +Admin user | Yes | Remove all the backend roles associate to the monitor and then use all the specified backend roles associated to the monitor. +Regular user | Yes | Remove backend roles associated to the monitor that the user has access to, but didn’t specify. Then add all the other specified backend roles from the list of backend roles that the user has permission to use to the monitor. +Regular user | No | Don’t update the backend roles on the monitor. + +- For admin users, an empty list is considered the same as removing all permissions that the user possesses. If a non-admin user passes in an empty list, that will throw an exception, because that is not allowed by non-admin users. +- If the user tries to associate roles that they don't have permission to use, it will throw an exception. +{: .note } + +To create an RBAC role, follow instructions in the Security Plugin API documentation to [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api#create-role). +### Create a monitor with an RBAC role + +When you create a monitor with the Alerting API, you can specify the RBAC roles at the bottom of the request body. Use the `rbac_roles` parameter. + +The following sample shows the RBAC roles specified by the RBAC parameter: + +```json +... + "rbac_roles": ["role1", "role2"] +} +``` + +To see a full request sample, see [Create a monitor]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api/#create-a-query-level-monitor). +>>>>>>> d04e88b4 (Reorganize Configuration section of the Security TOC (#2212)) diff --git a/_monitoring-plugins/alerting/settings.md b/_monitoring-plugins/alerting/settings.md index b4a427259c..6e44d7ae5b 100644 --- a/_monitoring-plugins/alerting/settings.md +++ b/_monitoring-plugins/alerting/settings.md @@ -10,7 +10,7 @@ nav_order: 5 ## Alerting indices -The alerting feature creates several indices and one alias. The security plugin demo script configures them as [system indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/) for an extra layer of protection. Don't delete these indices or modify their contents without using the alerting APIs. +The alerting feature creates several indices and one alias. The security plugin demo script configures them as [system indices]({{site.url}}{{site.baseurl}}/security/configuration/system-indices/) for an extra layer of protection. Don't delete these indices or modify their contents without using the alerting APIs. Index | Purpose :--- | :--- diff --git a/_observability-plugin/notebooks.md b/_observability-plugin/notebooks.md index cbe95c469c..c4392696cb 100644 --- a/_observability-plugin/notebooks.md +++ b/_observability-plugin/notebooks.md @@ -18,7 +18,7 @@ You can also generate [reports]({{site.url}}{{site.baseurl}}/dashboards/reportin Common use cases include creating postmortem reports, designing runbooks, building live infrastructure reports, and writing documentation. -Tenants in OpenSearch Dashboards are spaces for saving notebooks and other OpenSearch Dashboards objects. For more information, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy/). +Tenants in OpenSearch Dashboards are spaces for saving notebooks and other OpenSearch Dashboards objects. For more information, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security/multi-tenancy/tenant-index/). {: .note } diff --git a/_observability-plugin/observability-security.md b/_observability-plugin/observability-security.md index dbbb1d8c97..aacf40c30b 100644 --- a/_observability-plugin/observability-security.md +++ b/_observability-plugin/observability-security.md @@ -11,7 +11,7 @@ You can use the security plugin with Observability in OpenSearch to limit non-ad ## Basic permissions -The security plugin has two built-in roles that cover most Observability use cases: `observability_full_access` and `observability_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). If you don't see these predefined roles in OpenSearch Dashboards, you can create them with the following commands: +The security plugin has two built-in roles that cover most Observability use cases: `observability_full_access` and `observability_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). If you don't see these predefined roles in OpenSearch Dashboards, you can create them with the following commands: ```json PUT _plugins/_security/api/roles/observability_read_access @@ -31,7 +31,7 @@ PUT _plugins/_security/api/roles/observability_full_access } ``` -If these roles don't meet your needs, mix and match individual Observability [permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/) to suit your use case. For example, the `cluster:admin/opensearch/observability/create` permission lets you create Observability objects (visualizations, operational panels, notebooks, etc.). +If these roles don't meet your needs, mix and match individual Observability [permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/) to suit your use case. For example, the `cluster:admin/opensearch/observability/create` permission lets you create Observability objects (visualizations, operational panels, notebooks, etc.). The following is an example role that provides access to Observability: diff --git a/_opensearch/cluster.md b/_opensearch/cluster.md index 8a2be2bdbe..dc4ecfa112 100644 --- a/_opensearch/cluster.md +++ b/_opensearch/cluster.md @@ -341,4 +341,4 @@ You can then use the [Index State Management (ISM)]({{site.url}}{{site.baseurl}} ## Next steps -If you are using the security plugin, the previous request to `_cat/nodes?v` might have failed with an initialization error. For full guidance around using the security plugin, see [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/). +If you are using the security plugin, the previous request to `_cat/nodes?v` might have failed with an initialization error. For full guidance around using the security plugin, see [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/). diff --git a/_opensearch/snapshots/snapshot-management.md b/_opensearch/snapshots/snapshot-management.md index 88d9df0aa5..8cedd0b4d5 100644 --- a/_opensearch/snapshots/snapshot-management.md +++ b/_opensearch/snapshots/snapshot-management.md @@ -48,7 +48,7 @@ If a snapshot operation fails, it is retried a maximum of three times. The failu ## Security -The Security plugin has two built-in roles for Snapshot Management actions: `snapshot_management_full_access` and `snapshot_management_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +The Security plugin has two built-in roles for Snapshot Management actions: `snapshot_management_full_access` and `snapshot_management_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). The following table lists the required permissions for each Snapshot Management API. diff --git a/_opensearch/snapshots/snapshot-restore.md b/_opensearch/snapshots/snapshot-restore.md index fbddebfb25..8a6d06cf75 100644 --- a/_opensearch/snapshots/snapshot-restore.md +++ b/_opensearch/snapshots/snapshot-restore.md @@ -341,9 +341,9 @@ Setting | Description `partial` | Whether to allow the restoration of partial snapshots. Default is false. `rename_pattern` | If you want to rename indices as you restore them, use this option to specify a regular expression that matches all indices you want to restore. Use capture groups (`()`) to reuse portions of the index name. `rename_replacement` | If you want to rename indices as you restore them, use this option to specify the replacement pattern. Use `$0` to include the entire matching index name, `$1` to include the content of the first capture group, etc. -`index_settings` | If you want to change index settings on restore, specify them here. -`ignore_index_settings` | Rather than explicitly specifying new settings with `index_settings`, you can ignore certain index settings in the snapshot and use the cluster defaults on restore. - +`index_settings` | If you want to change [index settings]({{site.url}}{{site.baseurl}}/api-reference/index-apis/create-index/#index-settings) applied during restore, specify them here. You cannot change `index.number_of_shards`. +`ignore_index_settings` | Rather than explicitly specifying new settings with `index_settings`, you can ignore certain index settings in the snapshot and use the cluster defaults applied during restore. You cannot ignore `index.number_of_shards`, `index.number_of_replicas`, or `index.auto_expand_replicas`. +`storage_type` | `local` indicates that all snapshot metadata and index data will be downloaded to local storage.

`remote_snapshot` indicates that snapshot metadata will be downloaded to the cluster, but the remote repository will remain the authoritative store of the index data. Data will be downloaded and cached as necessary to service queries. At least one node in the cluster must be configured with the [search role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/) in order to restore a snapshot using the type `remote_snapshot`.

Defaults to `local`. ### Conflicts and compatibility @@ -359,7 +359,7 @@ We recommend ceasing write requests to a cluster before restoring from a snapsho Snapshots are only forward-compatible by one major version. If you have an old snapshot, you can sometimes restore it into an intermediate cluster, reindex all indices, take a new snapshot, and repeat until you arrive at your desired version, but you might find it easier to just manually index your data on the new cluster. -## Security plugin considerations +## Security considerations If you're using the security plugin, snapshots have some additional restrictions: diff --git a/_replication-plugin/permissions.md b/_replication-plugin/permissions.md index 621df26002..e09c9e9460 100644 --- a/_replication-plugin/permissions.md +++ b/_replication-plugin/permissions.md @@ -6,7 +6,7 @@ nav_order: 30 # Cross-cluster replication security -You can use the [security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) with cross-cluster replication to limit users to certain actions. For example, you might want certain users to only perform replication activity on the leader or follower cluster. +You can use the [security plugin]({{site.url}}{{site.baseurl}}/security/index/) with cross-cluster replication to limit users to certain actions. For example, you might want certain users to only perform replication activity on the leader or follower cluster. Because cross-cluster replication involves multiple clusters, it's possible that clusters might have different security configurations. The following configurations are supported: @@ -20,7 +20,7 @@ Enable node-to-node encryption on both the leader and the follower cluster to en In order for non-admin users to perform replication activities, they must be mapped to the appropriate permissions. -The security plugin has two built-in roles that cover most replication use cases: `cross_cluster_replication_leader_full_access`, which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access`, which provides replication permissions on the follower cluster. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +The security plugin has two built-in roles that cover most replication use cases: `cross_cluster_replication_leader_full_access`, which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access`, which provides replication permissions on the follower cluster. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). If you don't want to use the default roles, you can combine individual replication [permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#replication-permissions) to meet your needs. Most permissions correspond to specific REST API operations. For example, the `indices:admin/plugins/replication/index/pause` permission lets you pause replication. @@ -29,7 +29,7 @@ If you don't want to use the default roles, you can combine individual replicati The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#create-replication-rule) operations are special cases. They involve background processes on the leader and follower clusters that must be associated with roles. When you perform one of these actions, you must explicitly pass the `leader_cluster_role` and `follower_cluster_role` in the request, which OpenSearch then uses in all backend replication tasks. -To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/#map-users-to-roles). +To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#map-users-to-roles). Then add those roles to the request, and sign it with the appropriate credentials: diff --git a/_search-plugins/async/security.md b/_search-plugins/async/security.md index e23f28e53a..853a310c3a 100644 --- a/_search-plugins/async/security.md +++ b/_search-plugins/async/security.md @@ -10,13 +10,13 @@ has_children: false You can use the security plugin with asynchronous searches to limit non-admin users to specific actions. For example, you might want some users to only be able to submit or delete asynchronous searches, while you might want others to only view the results. -All asynchronous search indices are protected as system indices. Only a super admin user or an admin user with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/). +All asynchronous search indices are protected as system indices. Only a super admin user or an admin user with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security/configuration/system-indices/). ## Basic permissions As an admin user, you can use the security plugin to assign specific permissions to users based on which API operations they need access to. For a list of supported APIs operations, see [Asynchronous search]({{site.url}}{{site.baseurl}}/). -The security plugin has two built-in roles that cover most asynchronous search use cases: `asynchronous_search_full_access` and `asynchronous_search_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). +The security plugin has two built-in roles that cover most asynchronous search use cases: `asynchronous_search_full_access` and `asynchronous_search_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). If these roles don’t meet your needs, mix and match individual asynchronous search permissions to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/asynchronous_search/delete` permission lets you delete a previously submitted asynchronous search. @@ -24,7 +24,7 @@ If these roles don’t meet your needs, mix and match individual asynchronous se Use backend roles to configure fine-grained access to asynchronous searches based on roles. For example, users of different departments in an organization can view asynchronous searches owned by their own department. -First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user). +First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security/access-control/api#create-user). Now when users view asynchronous search resources in OpenSearch Dashboards (or make REST API calls), they only see asynchronous searches submitted by users who have a subset of the backend role. For example, consider two users: `judy` and `elon`. diff --git a/_security-plugin/access-control/multi-tenancy.md b/_security-plugin/access-control/multi-tenancy.md deleted file mode 100644 index 83d430a104..0000000000 --- a/_security-plugin/access-control/multi-tenancy.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -layout: default -title: OpenSearch Dashboards multi-tenancy -parent: Access control -nav_order: 30 ---- - -# OpenSearch Dashboards multi-tenancy - -*Tenants* in OpenSearch Dashboards are spaces for saving index patterns, visualizations, dashboards, and other OpenSearch Dashboards objects. Tenants are useful for safely sharing your work with other OpenSearch Dashboards users. You can control which roles have access to a tenant and whether those roles have read or write access. By default, all OpenSearch Dashboards users have access to two independent tenants: - -- **Private** - This tenant is exclusive to each user and can't be shared. You can't use it to access routes or index patterns made by the user's global tenant. -- **Global** - This tenant is shared between every OpenSearch Dashboards user. - -The global tenant is not a *primary* tenant such that any action done within the global tenant is not replicated to a user's private tenant. If you make a change to your global tenant, you won't see that change reflected in your private tenant. Some example changes include, but are not limited to: - -- Change advanced settings -- Create visualizations -- Create index patterns - -You might use the private tenant for exploratory work, create detailed visualizations with your team in an `analysts` tenant, and maintain a summary dashboard for corporate leadership in an `executive` tenant. - -If you share a visualization or dashboard with someone, you can see that the URL includes the tenant: - -``` -http://:5601/app/opensearch-dashboards?security_tenant=analysts#/visualize/edit/c501fa50-7e52-11e9-ae4e-b5d69947d32e?_g=() -``` - - -## Configuration - -Multi-tenancy is enabled by default, but you can disable it or change its settings using `config/opensearch-security/config.yml`: - -```yml -config: - dynamic: - kibana: - multitenancy_enabled: true - server_username: kibanaserver - index: '.kibana' - do_not_fail_on_forbidden: false -``` - -Setting | Description -:--- | :--- -`multitenancy_enabled` | Enable or disable multi-tenancy. Default is true. -`server_username` | Must match the name of the OpenSearch Dashboards server user from `opensearch_dashboards.yml`. Default is `kibanaserver`. -`index` | Must match the name of the OpenSearch Dashboards index from `opensearch_dashboards.yml`. Default is `.kibana`. -`do_not_fail_on_forbidden` | If true, the security plugin removes any content that a user is not allowed to see from search results. If false, the plugin returns a security exception. Default is false. - -`opensearch_dashboards.yml` has some additional settings: - -```yml -opensearch.username: kibanaserver -opensearch.password: kibanaserver -opensearch.requestHeadersAllowlist: ["securitytenant","Authorization"] -opensearch_security.multitenancy.enabled: true -opensearch_security.multitenancy.tenants.enable_global: true -opensearch_security.multitenancy.tenants.enable_private: true -opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] -opensearch_security.multitenancy.enable_filter: false -``` - -Setting | Description -:--- | :--- -`opensearch.requestHeadersAllowlist` | OpenSearch Dashboards requires that you add all HTTP headers to the allow list so that the headers pass to OpenSearch. Multi-tenancy uses a specific header, `securitytenant`, that must be present with the standard `Authorization` header. If the `securitytenant` header is not on the allow list, OpenSearch Dashboards starts with a red status. -`opensearch_security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true. -`opensearch_security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true. -`opensearch_security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true. -`opensearch_security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list. -`opensearch_security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false. - - -## Add tenants - -To create tenants, use OpenSearch Dashboards, the REST API, or `tenants.yml`. - - -#### OpenSearch Dashboards - -1. Open OpenSearch Dashboards. -1. Choose **Security**, **Tenants**, and **Create tenant**. -1. Give the tenant a name and description. -1. Choose **Create**. - - -#### REST API - -See [Create tenant]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-tenant). - - -#### tenants.yml - -```yml ---- -_meta: - type: "tenants" - config_version: 2 - -## Demo tenants -admin_tenant: - reserved: false - description: "Demo tenant for admin user" -``` - -## Give roles access to tenants - -After creating a tenant, give a role access to it using OpenSearch Dashboards, the REST API, or `roles.yml`. - -- Read-write (`kibana_all_write`) permissions let the role view and modify objects in the tenant. -- Read-only (`kibana_all_read`) permissions let the role view objects, but not modify them. - - -#### OpenSearch Dashboards - -1. Open OpenSearch Dashboards. -1. Choose **Security**, **Roles**, and a role. -1. For **Tenant permissions**, add tenants, press Enter, and give the role read and/or write permissions to it. - - -#### REST API - -See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role). - - -#### roles.yml - -```yml ---- -test-role: - reserved: false - hidden: false - cluster_permissions: - - "cluster_composite_ops" - - "indices_monitor" - index_permissions: - - index_patterns: - - "movies*" - dls: "" - fls: [] - masked_fields: [] - allowed_actions: - - "read" - tenant_permissions: - - tenant_patterns: - - "human_resources" - allowed_actions: - - "kibana_all_read" - static: false -_meta: - type: "roles" - config_version: 2 -``` - - -## Manage OpenSearch Dashboards indices - -The open source version of OpenSearch Dashboards saves all objects to a single index: `.kibana`. The security plugin uses this index for the global tenant, but separate indices for every other tenant. Each user also has a private tenant, so you might see a large number of indices that follow two patterns: - -``` -.kibana__ -.kibana__ -``` - -The security plugin scrubs these index names of special characters, so they might not be a perfect match of tenant names and usernames. -{: .tip } - -To back up your OpenSearch Dashboards data, [take a snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshots/snapshot-restore/) of all tenant indexes using an index pattern such as `.kibana*`. diff --git a/_security-plugin/configuration/concepts.md b/_security-plugin/configuration/concepts.md deleted file mode 100755 index 4a6e5aa084..0000000000 --- a/_security-plugin/configuration/concepts.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: default -title: Authentication flow -parent: Configuration -nav_order: 1 ---- - -# Authentication flow - -Understanding the authentication flow is a great way to get started with configuring the security plugin. - -1. To identify a user who wants to access the cluster, the security plugin needs the user's credentials. - - These credentials differ depending on how you've configured the plugin. For example, if you use basic authentication, the credentials are a user name and password. If you use a JSON web token, the credentials are stored within the token itself. If you use TLS certificates, the credentials are the distinguished name (DN) of the certificate. - -2. The security plugin authenticates the user's credentials against a backend: the internal user database, Lightweight Directory Access Protocol (LDAP), Active Directory, Kerberos, or JSON web tokens. - - The plugin supports chaining backends in `config/opensearch-security/config.yml`. If more than one backend is present, the plugin tries to authenticate the user sequentially against each until one succeeds. A common use case is to combine the internal user database of the security plugin with LDAP/Active Directory. - -3. After a backend verifies the user's credentials, the plugin collects any backend roles. These roles can be arbitrary strings in the internal user database, but in most cases, these backend roles come from LDAP/Active Directory. - -4. After the user is authenticated and any backend roles are retrieved, the security plugin uses the role mapping to assign security roles to the user. - - If the role mapping doesn't include the user (or the user's backend roles), the user is successfully authenticated, but has no permissions. - -5. The user can now perform actions as defined by the mapped security roles. For example, a user might map to the `kibana_user` role and thus have permissions to access OpenSearch Dashboards. diff --git a/_security-plugin/configuration/system-indices.md b/_security-plugin/configuration/system-indices.md deleted file mode 100644 index 893163a1c6..0000000000 --- a/_security-plugin/configuration/system-indices.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: default -title: System indices -parent: Configuration -nav_order: 15 ---- - -# System indices - -By default, OpenSearch has a protected system index, `.opendistro_security`, which you create using [securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/). Even if your user account has read permissions for all indices, you can't directly access the data in this system index. - -You can add additional system indices in in `opensearch.yml`. In addition to automatically creating `.opendistro_security`, the demo configuration adds several indices for the various OpenSearch plugins that integrate with the security plugin: - -```yml -plugins.security.system_indices.enabled: true -plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"] -``` - -To access these indices, you must authenticate with an [admin certificate]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#configure-admin-certificates): - -```bash -curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opendistro_security/_search' -``` - -The alternative is to remove indices from the `plugins.security.system_indices.indices` list on each node and restart OpenSearch. diff --git a/_security-plugin/access-control/api.md b/_security/access-control/api.md similarity index 97% rename from _security-plugin/access-control/api.md rename to _security/access-control/api.md index 2b730dec95..58e516c306 100644 --- a/_security-plugin/access-control/api.md +++ b/_security/access-control/api.md @@ -2,7 +2,7 @@ layout: default title: API parent: Access control -nav_order: 90 +nav_order: 120 --- # API @@ -425,7 +425,7 @@ Introduced 1.0 Creates or replaces the specified user. You must specify either `password` (plain text) or `hash` (the hashed user password). If you specify `password`, the security plugin automatically hashes the password before storing it. -Note that any role you supply in the `opendistro_security_roles` array must already exist for the security plugin to map the user to that role. To see predefined roles, refer to [the list of predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). For instructions on how to create a role, refer to [creating a role](#create-role). +Note that any role you supply in the `opendistro_security_roles` array must already exist for the security plugin to map the user to that role. To see predefined roles, refer to [the list of predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles). For instructions on how to create a role, refer to [creating a role](#create-role). #### Request @@ -678,11 +678,11 @@ PUT _plugins/_security/api/roles/ } ``` ->Due to word boundaries associated with Unicode special characters, the Unicode standard analyzer cannot index a [text field type](https://opensearch.org/docs/2.2/opensearch/supported-field-types/text/) value as a whole value when it includes one of these special characters. As a result, a text field value that includes a special character is parsed by the standard analyzer as multiple values separated by the special character, effectively tokenizing the different elements on either side of it. +>Due to word boundaries associated with Unicode special characters, the Unicode standard analyzer cannot index a [text field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text/) value as a whole value when it includes one of these special characters. As a result, a text field value that includes a special character is parsed by the standard analyzer as multiple values separated by the special character, effectively tokenizing the different elements on either side of it. > >For example, since the values in the fields ```"user.id": "User-1"``` and ```"user.id": "User-2"``` contain the hyphen/minus sign, this special character will prevent the analyzer from distinguishing between the two different users for `user.id` and interpret them as one and the same. This can lead to unintentional filtering of documents and potentially compromise control over their access. > ->To avoid this circumstance, you can use a custom analyzer or map the field as `keyword`, which performs an exact-match search. See [Keyword field type](https://opensearch.org/docs/2.2/opensearch/supported-field-types/keyword/) for the latter option. +>To avoid this circumstance, you can use a custom analyzer or map the field as `keyword`, which performs an exact-match search. See [Keyword field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/) for the latter option. > >For a list of characters that should be avoided when field type is `text`, see [Word Boundaries](https://unicode.org/reports/tr29/#Word_Boundaries). {: .warning} @@ -1424,7 +1424,7 @@ The following API is available for audit logging in the security plugin. This API allows you to enable or disable audit logging, define the configuration for audit logging and compliance, and make updates to settings. -For details on using audit logging to track access to OpenSearch clusters, as well as information on further configurations, see [Audit logs](https://opensearch.org/docs/latest/security-plugin/audit-logs/index/). +For details on using audit logging to track access to OpenSearch clusters, as well as information on further configurations, see [Audit logs]({{site.url}}{{site.baseurl}}/security/audit-logs/index/). You can do an initial configuration of audit logging in the `audit.yml` file, found in the `opensearch-project/security/config` directory. Thereafter, you can use the REST API or Dashboards for further changes to the configuration. {: note.} @@ -1525,7 +1525,7 @@ PUT /_opendistro/_security/api/audit/config A PATCH call is used to update specified fields in the audit configuration. The PATCH method requires an operation, a path, and a value to complete a valid request. For details on using the PATCH method, see the following [Patching resources](https://en.wikipedia.org/wiki/PATCH_%28HTTP%29#Patching_resources) description at Wikipedia. -Using the PATCH method also requires a user to have a security configuration that includes admin certificates for encryption. To find out more about these certificates, see [Configure admin certificates](https://opensearch.org/docs/latest/security-plugin/configuration/tls/#configure-admin-certificates). +Using the PATCH method also requires a user to have a security configuration that includes admin certificates for encryption. To find out more about these certificates, see [Configure admin certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configure-admin-certificates). ```bash curl -X PATCH -k -i --cert --key /_opendistro/_security/api/audit -H 'Content-Type: application/json' -d'[{"op":"add","path":"/config/enabled","value":"true"}]' diff --git a/_security-plugin/access-control/cross-cluster-search.md b/_security/access-control/cross-cluster-search.md similarity index 99% rename from _security-plugin/access-control/cross-cluster-search.md rename to _security/access-control/cross-cluster-search.md index 9c209b89ec..a1fbbf801f 100644 --- a/_security-plugin/access-control/cross-cluster-search.md +++ b/_security/access-control/cross-cluster-search.md @@ -2,7 +2,7 @@ layout: default title: Cross-cluster search parent: Access control -nav_order: 40 +nav_order: 105 --- # Cross-cluster search diff --git a/_security-plugin/access-control/default-action-groups.md b/_security/access-control/default-action-groups.md similarity index 96% rename from _security-plugin/access-control/default-action-groups.md rename to _security/access-control/default-action-groups.md index 025791b638..2d26649168 100644 --- a/_security-plugin/access-control/default-action-groups.md +++ b/_security/access-control/default-action-groups.md @@ -2,12 +2,12 @@ layout: default title: Default action groups parent: Access control -nav_order: 51 +nav_order: 115 --- # Default action groups -This page catalogs all default action groups. Often, the most coherent way to create new action groups is to use a combination of these default groups and [individual permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/). +This page catalogs all default action groups. Often, the most coherent way to create new action groups is to use a combination of these default groups and [individual permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/). ## General diff --git a/_security-plugin/access-control/document-level-security.md b/_security/access-control/document-level-security.md similarity index 91% rename from _security-plugin/access-control/document-level-security.md rename to _security/access-control/document-level-security.md index d94f870394..06c4a4842d 100644 --- a/_security-plugin/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -2,7 +2,7 @@ layout: default title: Document-level security parent: Access control -nav_order: 10 +nav_order: 85 --- # Document-level security (DLS) @@ -57,7 +57,7 @@ These queries can be as complex as you want, but we recommend keeping them simpl ### A note on Unicode special characters in text fields -Due to word boundaries associated with Unicode special characters, the Unicode standard analyzer cannot index a [text field type](https://opensearch.org/docs/2.2/opensearch/supported-field-types/text/) value as a whole value when it includes one of these special characters. As a result, a text field value that includes a special character is parsed by the standard analyzer as multiple values separated by the special character, effectively tokenizing the different elements on either side of it. This can lead to unintentional filtering of documents and potentially compromise control over their access. +Due to word boundaries associated with Unicode special characters, the Unicode standard analyzer cannot index a [text field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text/) value as a whole value when it includes one of these special characters. As a result, a text field value that includes a special character is parsed by the standard analyzer as multiple values separated by the special character, effectively tokenizing the different elements on either side of it. This can lead to unintentional filtering of documents and potentially compromise control over their access. The examples below illustrate values containing special characters that will be parsed improperly by the standard analyzer. In this example, the existence of the hyphen/minus sign in the value prevents the analyzer from distinguishing between the two different users for `user.id` and interprets them as one and the same: @@ -85,7 +85,7 @@ The examples below illustrate values containing special characters that will be } ``` -To avoid this circumstance when using either Query DSL or the REST API, you can use a custom analyzer or map the field as `keyword`, which performs an exact-match search. See [Keyword field type](https://opensearch.org/docs/2.2/opensearch/supported-field-types/keyword/) for the latter option. +To avoid this circumstance when using either Query DSL or the REST API, you can use a custom analyzer or map the field as `keyword`, which performs an exact-match search. See [Keyword field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/) for the latter option. For a list of characters that should be avoided when field type is `text`, see [Word Boundaries](https://unicode.org/reports/tr29/#Word_Boundaries). @@ -165,7 +165,7 @@ You can perform term-level lookup queries (TLQs) with document-level security (D By default, the security plugin detects if a DLS query contains a TLQ or not and chooses the appropriate mode automatically at runtime. -To learn more about OpenSearch queries, see [Term-level queries](https://opensearch.org/docs/latest/opensearch/query-dsl/term/). +To learn more about OpenSearch queries, see [Term-level queries]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/term/). ### How to set the DLS evaluation mode in `opensearch.yml` diff --git a/_security-plugin/access-control/field-level-security.md b/_security/access-control/field-level-security.md similarity index 85% rename from _security-plugin/access-control/field-level-security.md rename to _security/access-control/field-level-security.md index f0ad637946..2f9590c559 100644 --- a/_security-plugin/access-control/field-level-security.md +++ b/_security/access-control/field-level-security.md @@ -2,12 +2,12 @@ layout: default title: Field-level security parent: Access control -nav_order: 11 +nav_order: 90 --- # Field-level security -Field-level security lets you control which document fields a user can see. Just like [document-level security]({{site.url}}{{site.baseurl}}/security-plugin/access-control/document-level-security/), you control access by index within a role. +Field-level security lets you control which document fields a user can see. Just like [document-level security]({{site.url}}{{site.baseurl}}/security/access-control/document-level-security/), you control access by index within a role. The easiest way to get started with document- and field-level security is open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section. @@ -93,7 +93,7 @@ someonerole: ### REST API -See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role). +See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role). ## Interaction with multiple roles @@ -118,4 +118,4 @@ For example, in the `movies` index, if you include `actors`, `title`, and `year` ## Interaction with document-level security -[Document-level security]({{site.url}}{{site.baseurl}}/security-plugin/access-control/document-level-security/) relies on OpenSearch queries, which means that all fields in the query must be visible in order for it to work properly. If you use field-level security in conjunction with document-level security, make sure you don't restrict access to the fields that document-level security uses. +[Document-level security]({{site.url}}{{site.baseurl}}/security/access-control/document-level-security/) relies on OpenSearch queries, which means that all fields in the query must be visible in order for it to work properly. If you use field-level security in conjunction with document-level security, make sure you don't restrict access to the fields that document-level security uses. diff --git a/_security-plugin/access-control/field-masking.md b/_security/access-control/field-masking.md similarity index 90% rename from _security-plugin/access-control/field-masking.md rename to _security/access-control/field-masking.md index 9cff0d576e..1ac4935d5f 100644 --- a/_security-plugin/access-control/field-masking.md +++ b/_security/access-control/field-masking.md @@ -2,12 +2,12 @@ layout: default title: Field masking parent: Access control -nav_order: 12 +nav_order: 95 --- # Field masking -If you don't want to remove fields from a document using [field-level security]({{site.url}}{{site.baseurl}}/security-plugin/access-control/field-level-security/), you can mask their values. Currently, field masking is only available for string-based fields and replaces the field's value with a cryptographic hash. +If you don't want to remove fields from a document using [field-level security]({{site.url}}{{site.baseurl}}/security/access-control/field-level-security/), you can mask their values. Currently, field masking is only available for string-based fields and replaces the field's value with a cryptographic hash. Field masking works alongside field-level security on the same per-role, per-index basis. You can allow certain roles to see sensitive fields in plain text and mask them for others. A search result with a masked field might look like this: @@ -68,7 +68,7 @@ someonerole: ### REST API -See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role). +See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role). ## (Advanced) Use an alternative hash algorithm diff --git a/_security-plugin/access-control/impersonation.md b/_security/access-control/impersonation.md similarity index 98% rename from _security-plugin/access-control/impersonation.md rename to _security/access-control/impersonation.md index 100d11040b..80d6ddc55e 100644 --- a/_security-plugin/access-control/impersonation.md +++ b/_security/access-control/impersonation.md @@ -2,7 +2,7 @@ layout: default title: User impersonation parent: Access control -nav_order: 20 +nav_order: 100 --- # User impersonation diff --git a/_security-plugin/access-control/index.md b/_security/access-control/index.md similarity index 78% rename from _security-plugin/access-control/index.md rename to _security/access-control/index.md index 6275487f34..f4b18cd0a3 100644 --- a/_security-plugin/access-control/index.md +++ b/_security/access-control/index.md @@ -1,7 +1,7 @@ --- layout: default title: Access control -nav_order: 10 +nav_order: 75 has_children: true has_toc: false redirect_from: @@ -10,7 +10,7 @@ redirect_from: # Access control -After you [configure the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) to use your own certificates and preferred authentication backend, you can start adding users, creating roles, and mapping roles to users. +After you [configure the Security plugin]({{site.url}}{{site.baseurl}}/security/configuration/index/) to use your own certificates and preferred authentication backend, you can start adding users, creating roles, and mapping roles to users. This section of the documentation covers what a user is allowed to see and do after successfully authenticating. @@ -19,11 +19,11 @@ This section of the documentation covers what a user is allowed to see and do af Term | Description :--- | :--- -Permission | An individual action, such as creating an index (e.g. `indices:admin/create`). For a complete list, see [Permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/). +Permission | An individual action, such as creating an index (e.g. `indices:admin/create`). For a complete list, see [Permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/). Action group | A set of permissions. For example, the predefined `SEARCH` action group authorizes roles to use the `_search` and `_msearch` APIs. Role | Security roles define the scope of a permission or action group: cluster, index, document, or field. For example, a role named `delivery_analyst` might have no cluster permissions, the `READ` action group for all indices that match the `delivery-data-*` pattern, access to all document types within those indices, and access to all fields except `delivery_driver_name`. Backend role | (Optional) Arbitrary strings that you specify *or* that come from an external authentication system (e.g. LDAP/Active Directory). Backend roles can help simplify the role mapping process. Rather than mapping a role to 100 individual users, you can map the role to a single backend role that all 100 users share. User | Users make requests to OpenSearch clusters. A user has credentials (e.g. a username and password), zero or more backend roles, and zero or more custom attributes. Role mapping | Users assume roles after they successfully authenticate. Role mappings, well, map roles to users (or backend roles). For example, a mapping of `kibana_user` (role) to `jdoe` (user) means that John Doe gains all the permissions of `kibana_user` after authenticating. Likewise, a mapping of `all_access` (role) to `admin` (backend role) means that any user with the backend role of `admin` gains all the permissions of `all_access` after authenticating. You can map each role to many users and/or backend roles. -The security plugin comes with a number of [predefined action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/), roles, mappings, and users. These entities serve as sensible defaults and are good examples of how to use the plugin. +The security plugin comes with a number of [predefined action groups]({{site.url}}{{site.baseurl}}/security/access-control/default-action-groups/), roles, mappings, and users. These entities serve as sensible defaults and are good examples of how to use the plugin. diff --git a/_security-plugin/access-control/permissions.md b/_security/access-control/permissions.md similarity index 92% rename from _security-plugin/access-control/permissions.md rename to _security/access-control/permissions.md index da9f6bdfe0..bdfeaf3918 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security/access-control/permissions.md @@ -2,7 +2,7 @@ layout: default title: Permissions parent: Access control -nav_order: 50 +nav_order: 110 --- # Permissions @@ -41,7 +41,7 @@ These permissions also allow you add, update, or delete documents (e.g. `PUT tes ## Test permissions -If you want a user to have the absolute minimum set of permissions necessary to perform some function---the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)----the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response: +If you want a user to have the absolute minimum set of permissions necessary to perform some function—the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)—the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response: ```json GET _cat/shards?v @@ -57,9 +57,9 @@ GET _cat/shards?v } ``` -[Create a user and a role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/), map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds. +[Create a user and a role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/), map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds. -Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/) for descriptions of the permissions that each group grants. +Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See [Default action groups]({{site.url}}{{site.baseurl}}/security/access-control/default-action-groups/) for descriptions of the permissions that each group grants. {: .tip } diff --git a/_security-plugin/access-control/users-roles.md b/_security/access-control/users-roles.md similarity index 87% rename from _security-plugin/access-control/users-roles.md rename to _security/access-control/users-roles.md index cc5abd870a..f46c67ad98 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security/access-control/users-roles.md @@ -2,7 +2,7 @@ layout: default title: Users and roles parent: Access control -nav_order: 1 +nav_order: 80 --- # Users and roles @@ -11,7 +11,7 @@ The security plugin includes an internal user database. Use this database in pla Roles are the core way of controlling access to your cluster. Roles contain any combination of cluster-wide permissions, index-specific permissions, document- and field-level security, and tenants. Then you map users to these roles so that users gain those permissions. -Unless you need to create new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#reserved-and-hidden-resources), we **highly** recommend using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use. +Unless you need to create new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources), we **highly** recommend using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use. {: .warning } --- @@ -39,12 +39,12 @@ You can create users using OpenSearch Dashboards, `internal_users.yml`, or the R ### internal_users.yml -See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#internal_usersyml). +See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#internal_usersyml). ### REST API -See [Create user]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user). +See [Create user]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-user). ## Create roles @@ -65,12 +65,12 @@ Just like users, you can create roles using OpenSearch Dashboards, `roles.yml`, ### roles.yml -See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#rolesyml). +See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml). ### REST API -See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role). +See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role). ## Map users to roles @@ -89,12 +89,12 @@ Just like users and roles, you create role mappings using OpenSearch Dashboards, ### roles_mapping.yml -See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#roles_mappingyml). +See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles_mappingyml). ### REST API -See [Create role mapping]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role-mapping). +See [Create role mapping]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role-mapping). ## Predefined roles @@ -119,7 +119,7 @@ Role | Description `manage_snapshots` | Grants permissions to manage snapshot repositories, take snapshots, and restore snapshots. `readall` | Grants permissions for cluster-wide searches like `msearch` and search permissions for all indices. `readall_and_monitor` | Same as `readall`, but with added cluster monitoring permissions. -`security_rest_api_access` | A special role that allows access to the REST API. See `plugins.security.restapi.roles_enabled` in `opensearch.yml` and [Access control for the API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#access-control-for-the-api). +`security_rest_api_access` | A special role that allows access to the REST API. See `plugins.security.restapi.roles_enabled` in `opensearch.yml` and [Access control for the API]({{site.url}}{{site.baseurl}}/security/access-control/api/#access-control-for-the-api). `reports_read_access` | Grants permissions to generate on-demand reports, download existing reports, and view report definitions, but not to create report definitions. `reports_instances_read_access` | Grants permissions to generate on-demand reports and download existing reports, but not to view or create report definitions. `reports_full_access` | Grants full permissions to reports. @@ -129,7 +129,7 @@ Role | Description `snapshot_management_full_access` | Grants full permissions to all snapshot management actions. `snapshot_management_read_access` | Grants permissions to view policies but not create, modify, start, stop, or delete them. -For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/). +For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in [Default action groups]({{site.url}}{{site.baseurl}}/security/access-control/default-action-groups/). ## Sample roles diff --git a/_security-plugin/audit-logs/field-reference.md b/_security/audit-logs/field-reference.md similarity index 99% rename from _security-plugin/audit-logs/field-reference.md rename to _security/audit-logs/field-reference.md index 989de205eb..edd37d43c4 100644 --- a/_security-plugin/audit-logs/field-reference.md +++ b/_security/audit-logs/field-reference.md @@ -2,7 +2,7 @@ layout: default title: Audit log field reference parent: Audit logs -nav_order: 1 +nav_order: 130 --- # Audit log field reference diff --git a/_security-plugin/audit-logs/index.md b/_security/audit-logs/index.md similarity index 98% rename from _security-plugin/audit-logs/index.md rename to _security/audit-logs/index.md index 05284eb3a4..4ca82ba151 100644 --- a/_security-plugin/audit-logs/index.md +++ b/_security/audit-logs/index.md @@ -1,7 +1,7 @@ --- layout: default title: Audit logs -nav_order: 90 +nav_order: 125 has_children: true has_toc: false redirect_from: @@ -20,7 +20,7 @@ To enable audit logging: plugins.security.audit.type: internal_opensearch ``` - This setting stores audit logs on the current cluster. For other storage options, see [Audit Log Storage Types]({{site.url}}{{site.baseurl}}/security-plugin/audit-logs/storage-types/). + This setting stores audit logs on the current cluster. For other storage options, see [Audit Log Storage Types]({{site.url}}{{site.baseurl}}/security/audit-logs/storage-types/). 2. Restart each node. diff --git a/_security-plugin/audit-logs/storage-types.md b/_security/audit-logs/storage-types.md similarity index 99% rename from _security-plugin/audit-logs/storage-types.md rename to _security/audit-logs/storage-types.md index 774ac6f47c..17cfb12704 100644 --- a/_security-plugin/audit-logs/storage-types.md +++ b/_security/audit-logs/storage-types.md @@ -2,7 +2,7 @@ layout: default title: Audit log storage types parent: Audit logs -nav_order: 10 +nav_order: 135 --- # Audit log storage types diff --git a/_security/authentication-backends/authc-index.md b/_security/authentication-backends/authc-index.md new file mode 100755 index 0000000000..065e980e4d --- /dev/null +++ b/_security/authentication-backends/authc-index.md @@ -0,0 +1,31 @@ +--- +layout: default +title: Authentication backends +nav_order: 45 +has_children: true +has_toc: false +redirect_from: + - /security/authentication-backends/ +--- + +# Authentication backends + +Authentication backend configurations determine the method or methods you use for authenticating users and the way users pass their credentials and sign in to OpenSearch. Having an understanding of the basic authentication flow before getting started can help with the configuration process for whichever backend you choose. Consider the high-level sequence of events in the description that follows, and then refer to the detailed steps for configuring the authentication type you choose to use with OpenSearch. + +## Authentication flow + +1. To identify a user who wants to access the cluster, the Security plugin needs the user's credentials. + + These credentials differ depending on how you've configured the plugin. For example, if you use basic authentication, the credentials are a username and password. If you use a JSON web token, the credentials (username and roles) are stored within the token itself. If you use TLS certificates, the credentials are the distinguished name (DN) of the certificate. No matter which backend you use, these credentials are included in the request for authentication. + +2. The Security plugin authenticates a request against a backend configured for an authentication provider. Some examples of authentication providers used with OpenSearch include Basic Auth (which uses the internal user database), LDAP/Active Directory, JSON web tokens, SAML, or another authentication protocol. + + The plugin supports chaining backends in `config/opensearch-security/config.yml`. If more than one backend is present, the plugin tries to authenticate the user sequentially against each until one succeeds. A common use case is to combine the internal user database of the security plugin with LDAP/Active Directory. + +3. After a backend verifies the user's credentials, the plugin collects any [backend roles]({{site.url}}{{site.baseurl}}/security/access-control/index/#concepts). The authentication provider determines the way these roles are retrieved. For example, LDAP extracts backend roles from its directory service based on their mappings to roles in OpenSearch, while SAML stores the roles as attributes. When basic authentication is used, the internal user database refers to role mappings configured in OpenSearch. + +4. After the user is authenticated and any backend roles are retrieved, the security plugin uses the role mapping to assign security roles to the user. + + If the role mapping doesn't include the user (or the user's backend roles), the user is successfully authenticated, but has no permissions. + +5. The user can now perform actions as defined by the mapped security roles. For example, a user might map to the `kibana_user` role and thus have permissions to access OpenSearch Dashboards. diff --git a/_security-plugin/configuration/client-auth.md b/_security/authentication-backends/client-auth.md similarity index 72% rename from _security-plugin/configuration/client-auth.md rename to _security/authentication-backends/client-auth.md index 5ae6144290..b70253184d 100644 --- a/_security-plugin/configuration/client-auth.md +++ b/_security/authentication-backends/client-auth.md @@ -1,13 +1,16 @@ --- layout: default title: Client certificate authentication -parent: Configuration -nav_order: 50 +parent: Authentication backends +nav_order: 70 +redirect_from: + - /security/configuration/client-auth/ + - /security-plugin/configuration/client-auth/ --- # Client certificate authentication -After obtaining your own certificates either from a certificate authority (CA) or by [generating your own certificates using OpenSSL]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates), you can start configuring OpenSearch to authenticate a user using a client certificate. +After obtaining your own certificates either from a certificate authority (CA) or by [generating your own certificates using OpenSSL]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates), you can start configuring OpenSearch to authenticate a user using a client certificate. Client certificate authentication offers more security advantages than just using basic authentication (username and password). Because client certificate authentication requires both a client certificate and its private key, which are often in the user's possession, it is less vulnerable to brute force attacks in which malicious individuals try to guess a user's password. @@ -40,9 +43,9 @@ clientcert_auth_domain: ## Assigning roles to your common name -You can now assign your certificate's common name (CN) to a role. For this step, you must know your certificate's CN and the role you want to assign to. To get a list of all predefined roles in OpenSearch, refer to our [list of predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). If you want to first create a role, refer to [how to create a role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#create-users), and then map your certificate's CN to that role. +You can now assign your certificate's common name (CN) to a role. For this step, you must know your certificate's CN and the role you want to assign to. To get a list of all predefined roles in OpenSearch, refer to our [list of predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#predefined-roles). If you want to first create a role, refer to [how to create a role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#create-users), and then map your certificate's CN to that role. -After deciding which role you want to map your certificate's CN to, you can use [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#map-users-to-roles), [`roles_mapping.yml`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#roles_mappingyml), or the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role-mapping) to map your certificate's CN to the role. The following example uses the `REST API` to map the common name `CLIENT1` to the role `readall`. +After deciding which role you want to map your certificate's CN to, you can use [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#map-users-to-roles), [`roles_mapping.yml`]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles_mappingyml), or the [REST API]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role-mapping) to map your certificate's CN to the role. The following example uses the `REST API` to map the common name `CLIENT1` to the role `readall`. **Sample request** @@ -109,4 +112,4 @@ output.opensearch: ## Using certificates with Docker -While we recommend using the [tarball]({{site.url}}{{site.baseurl}}/opensearch/install/tar) installation of ODFE to test client certificate authentication configurations, you can also use any of the other install types. For instructions on using Docker security, see [Configuring basic security settings]({{site.url}}{{site.baseurl}}/opensearch/install/docker#configuring-basic-security-settings). +While we recommend using the [tarball]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/tar/) installation of ODFE to test client certificate authentication configurations, you can also use any of the other install types. For instructions on using Docker security, see [Configuring basic security settings]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#configuring-basic-security-settings). diff --git a/_security-plugin/configuration/ldap.md b/_security/authentication-backends/ldap.md similarity index 99% rename from _security-plugin/configuration/ldap.md rename to _security/authentication-backends/ldap.md index 482ec43599..411c706e88 100755 --- a/_security-plugin/configuration/ldap.md +++ b/_security/authentication-backends/ldap.md @@ -1,8 +1,11 @@ --- layout: default title: Active Directory and LDAP -parent: Configuration -nav_order: 30 +parent: Authentication backends +nav_order: 60 +redirect_from: + - /security/configuration/ldap/ + - /security-plugin/configuration/ldap/ --- # Active Directory and LDAP diff --git a/_security-plugin/configuration/openid-connect.md b/_security/authentication-backends/openid-connect.md similarity index 98% rename from _security-plugin/configuration/openid-connect.md rename to _security/authentication-backends/openid-connect.md index 0a5281fcad..a8a6913ac1 100755 --- a/_security-plugin/configuration/openid-connect.md +++ b/_security/authentication-backends/openid-connect.md @@ -1,8 +1,8 @@ --- layout: default title: OpenID Connect -parent: Configuration -nav_order: 32 +parent: Authentication backends +nav_order: 50 --- # OpenID Connect @@ -313,6 +313,8 @@ opensearch.ssl.verificationMode: none opensearch.requestHeadersAllowlist: ["Authorization", "security_tenant"] ``` +To include OpenID Connect with other authentication types in the Dashboards sign-in window, see [Configuring sign-in options]({{site.url}}{{site.baseurl}}/security/configuration/multi-auth/). +{: .note } ### OpenSearch security configuration diff --git a/_security-plugin/configuration/proxy.md b/_security/authentication-backends/proxy.md similarity index 99% rename from _security-plugin/configuration/proxy.md rename to _security/authentication-backends/proxy.md index 8e7b88b9dd..bb1f3b28f0 100644 --- a/_security-plugin/configuration/proxy.md +++ b/_security/authentication-backends/proxy.md @@ -1,8 +1,8 @@ --- layout: default title: Proxy-based authentication -parent: Configuration -nav_order: 40 +parent: Authentication backends +nav_order: 65 --- # Proxy-based authentication diff --git a/_security-plugin/configuration/saml.md b/_security/authentication-backends/saml.md similarity index 97% rename from _security-plugin/configuration/saml.md rename to _security/authentication-backends/saml.md index da3060de66..851faf8265 100755 --- a/_security-plugin/configuration/saml.md +++ b/_security/authentication-backends/saml.md @@ -1,8 +1,11 @@ --- layout: default title: SAML -parent: Configuration -nav_order: 31 +parent: Authentication backends +nav_order: 55 +redirect_from: + - /security/configuration/saml/ + - /security-plugin/configuration/saml/ --- # SAML @@ -130,7 +133,7 @@ Subjects (for example, user names) are usually stored in the `NameID` element of If your IdP is compliant with the SAML 2.0 specification, you do not need to set anything special. If your IdP uses a different element name, you can also specify its name explicitly. -Role attributes are optional. However, most IdPs can be configured to add roles in the SAML assertions as well. If present, you can use these roles in your [role mappings]({{site.url}}{{site.baseurl}}/security-plugin/configuration/concepts/): +Role attributes are optional. However, most IdPs can be configured to add roles in the SAML assertions as well. If present, you can use these roles in your [role mappings]({{site.url}}{{site.baseurl}}/security/access-control/index/#concepts): ``` @@ -314,6 +317,9 @@ If you use the logout POST binding, you also need to ad the logout endpoint to y server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"] ``` +To include SAML with other authentication types in the Dashboards sign-in window, see [Configuring sign-in options]({{site.url}}{{site.baseurl}}/security/configuration/multi-auth/). +{: .note } + ### IdP-initiated SSO To use IdP-initiated SSO, set the Assertion Consumer Service endpoint of your IdP to this: diff --git a/_security-plugin/configuration/configuration.md b/_security/configuration/configuration.md similarity index 97% rename from _security-plugin/configuration/configuration.md rename to _security/configuration/configuration.md index 4b3f15a395..073fd73d16 100755 --- a/_security-plugin/configuration/configuration.md +++ b/_security/configuration/configuration.md @@ -1,13 +1,13 @@ --- layout: default -title: Backend configuration +title: Configuring the Security backend parent: Configuration -nav_order: 2 +nav_order: 5 --- -# Backend configuration +# Configuring the Security backend -One of the first steps to using the security plugin is to decide on an authentication backend, which handles [steps 2-3 of the authentication flow]({{site.url}}{{site.baseurl}}/security-plugin/configuration/concepts#authentication-flow). The plugin has an internal user database, but many people prefer to use an existing authentication backend, such as an LDAP server, or some combination of the two. +One of the first steps to using the security plugin is to decide on an authentication backend, which handles [steps 2-3 of the authentication flow]({{site.url}}{{site.baseurl}}/security/authentication-backends/authc-index/#authentication-flow). The plugin has an internal user database, but many people prefer to use an existing authentication backend, such as an LDAP server, or some combination of the two. The main configuration file for authentication and authorization backends is `config/opensearch-security/config.yml`. It defines how the security plugin retrieves the user credentials, how it verifies these credentials, and how to fetch additional roles from backend systems (optional). @@ -95,7 +95,7 @@ These are the possible values for `type`: - `noop`: No further authentication against any backend system is performed. Use `noop` if the HTTP authenticator has already authenticated the user completely, as in the case of JWT, Kerberos, or client certificate authentication. - `internal`: Use the users and roles defined in `internal_users.yml` for authentication. -- `ldap`: Authenticate users against an LDAP server. This setting requires [additional, LDAP-specific configuration settings]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/). +- `ldap`: Authenticate users against an LDAP server. This setting requires [additional, LDAP-specific configuration settings]({{site.url}}{{site.baseurl}}/security/authentication-backends/ldap/). ## Authorization @@ -118,7 +118,7 @@ You can define multiple entries in this section the same way as you can for auth These are the possible values for `type`: - `noop`: Skip this step altogether. -- `ldap`: Fetch additional roles from an LDAP server. This setting requires [additional, LDAP-specific configuration settings]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/). +- `ldap`: Fetch additional roles from an LDAP server. This setting requires [additional, LDAP-specific configuration settings]({{site.url}}{{site.baseurl}}/security/authentication-backends/ldap/). ## Configuration examples diff --git a/_security-plugin/configuration/disable.md b/_security/configuration/disable.md similarity index 93% rename from _security-plugin/configuration/disable.md rename to _security/configuration/disable.md index c43aa7dff4..036acc9588 100755 --- a/_security-plugin/configuration/disable.md +++ b/_security/configuration/disable.md @@ -1,11 +1,11 @@ --- layout: default -title: Disable security +title: Disabling security parent: Configuration -nav_order: 99 +nav_order: 40 --- -# Disable security +# Disabling security You might want to temporarily disable the security plugin to make testing or internal usage more straightforward. To disable the plugin, add the following line in `opensearch.yml`: @@ -28,7 +28,7 @@ Disabling or removing the plugin exposes the configuration index for the securit The security plugin is actually two plugins: one for OpenSearch and one for OpenSearch Dashboards. You can use the OpenSearch plugin independently, but the OpenSearch Dashboards plugin depends on a secured OpenSearch cluster. -If you disable the security plugin in `opensearch.yml` (or delete the plugin entirely) and still want to use OpenSearch Dashboards, you must remove the corresponding OpenSearch Dashboards plugin. For more information, see [OpenSearch Dashboards remove plugins]({{site.url}}{{site.baseurl}}/dashboards/install/plugins#remove-plugins). +If you disable the security plugin in `opensearch.yml` (or delete the plugin entirely) and still want to use OpenSearch Dashboards, you must remove the corresponding OpenSearch Dashboards plugin. For more information, see [OpenSearch Dashboards remove plugins]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/plugins/#remove-plugins). ### Docker diff --git a/_security-plugin/configuration/generate-certificates.md b/_security/configuration/generate-certificates.md similarity index 93% rename from _security-plugin/configuration/generate-certificates.md rename to _security/configuration/generate-certificates.md index 8ede691482..4360454830 100755 --- a/_security-plugin/configuration/generate-certificates.md +++ b/_security/configuration/generate-certificates.md @@ -1,11 +1,11 @@ --- layout: default -title: Generate certificates +title: Generating self-signed certificates parent: Configuration -nav_order: 11 +nav_order: 20 --- -# Generate certificates +# Generating self-signed certificates If you don't have access to a certificate authority (CA) for your organization and want to use OpenSearch for non-demo purposes, you can generate your own self-signed certificates using [OpenSSL](https://www.openssl.org/){:target='\_blank'}. @@ -77,7 +77,7 @@ Follow the prompts to fill in the details. You don't need to specify a challenge If you generate TLS certificates and have enabled hostname verification by setting `plugins.security.ssl.transport.enforce_hostname_verification` to `true` (default), be sure to specify a common name (CN) for each certificate signing request (CSR) that matches the corresponding DNS A record of the intended node. -If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#advanced-hostname-verification-and-dns-lookup). +If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/#advanced-hostname-verification-and-dns-lookup). Now that the private key and signing request have been created, generate the certificate: @@ -228,14 +228,14 @@ plugins.security.nodes_dn: - 'CN=node2.dns.a-record,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA' ``` -For more information about adding and using these certificates in your own setup, see [Configuring basic security settings]({{site.url}}{{site.baseurl}}/opensearch/install/docker#configuring-basic-security-settings) for Docker, [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/), and [Client certificate authentication]({{site.url}}{{site.baseurl}}/security-plugin/configuration/client-auth/). +For more information about adding and using these certificates in your own setup, see [Configuring basic security settings]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#configuring-basic-security-settings) for Docker, [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/), and [Client certificate authentication]({{site.url}}{{site.baseurl}}/security/configuration/client-auth/). ## Run securityadmin.sh -After configuring your certificates and starting OpenSearch, run `securityadmin.sh` to initialize the security plugin. For information about how to use this script, see [Apply configuration changes]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/). +After configuring your certificates and starting OpenSearch, run `securityadmin.sh` to initialize the security plugin. For information about how to use this script, see [Applying changes to configuration files]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/). ## OpenSearch Dashboards -For information on using your root CA and a client certificate to enable TLS for OpenSearch Dashboards, see [Configure TLS for OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/tls/). +For information on using your root CA and a client certificate to enable TLS for OpenSearch Dashboards, see [Configure TLS for OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/tls/). diff --git a/_security-plugin/configuration/index.md b/_security/configuration/index.md similarity index 50% rename from _security-plugin/configuration/index.md rename to _security/configuration/index.md index 92ced6b818..7bcdb25610 100644 --- a/_security-plugin/configuration/index.md +++ b/_security/configuration/index.md @@ -1,27 +1,27 @@ --- layout: default title: Configuration -nav_order: 5 +nav_order: 2 has_children: true has_toc: false redirect_from: - - /security-plugin/configuration/ + - /security/configuration/ --- # 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: -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. [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. [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-plugin/access-control/index/). +1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security/access-control/index/). -If you don't want to use the plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security-plugin/configuration/disable). +If you don't want to use the plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security/configuration/disable). 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. {: .note } diff --git a/_security-plugin/configuration/security-admin.md b/_security/configuration/security-admin.md similarity index 82% rename from _security-plugin/configuration/security-admin.md rename to _security/configuration/security-admin.md index a59c9b60cc..cc3fbc58ef 100755 --- a/_security-plugin/configuration/security-admin.md +++ b/_security/configuration/security-admin.md @@ -1,15 +1,18 @@ --- layout: default -title: Apply changes with securityadmin.sh +title: Applying changes to configuration files parent: Configuration -nav_order: 20 +nav_order: 25 --- -# Apply changes using securityadmin.sh +# Applying changes to configuration files -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. +On **Windows**, use **securityadmin.bat** in place of **securityadmin.sh**. For more information, see [Windows usage](#windows-usage). +{: .note} -To initialize the `.opendistro_security` index, however, you must run `plugins/opensearch-security/tools/securityadmin.sh`. This script loads your initial configuration into the index using the configuration files in `config/opensearch-security`. After the `.opendistro_security` index is initialized, use OpenSearch Dashboards or the REST API to manage your users, roles, and permissions. +The Security plugin stores its configuration—including users, roles, permissions, and backend settings—in a [system index]({{site.url}}{{site.baseurl}}/security/configuration/system-indices) on the OpenSearch cluster. Storing these settings in an index lets you change settings without restarting the cluster and eliminates the need to edit configuration files on every individual node. This is accomplished by running the `securityadmin.sh` script. The script can be found at `plugins/opensearch-security/tools/securityadmin.sh`. + +The first job of the script, however, is to initialize the `.opendistro_security` index. This loads your initial configuration into the index using the configuration files in `config/opensearch-security`. After the `.opendistro_security` index is initialized, you can use OpenSearch Dashboards or the REST API to manage your users, roles, and permissions. ## A word of caution @@ -20,7 +23,7 @@ Running `securityadmin.sh` **overwrites** one or more portions of the `.opendist 1. You initialize the `.opendistro_security` index. 1. You create ten users using the REST API. -1. You decide to create a new [reserved user]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#reserved-and-hidden-resources) using `internal_users.yml`. +1. You decide to create a new [reserved user]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources) using `internal_users.yml`. 1. You run `securityadmin.sh` again to load the new reserved user into the index. 1. You lose all ten users that you created using the REST API. @@ -57,7 +60,7 @@ To resolve all environment variables before applying the security configurations -key ../../../kirk.key.pem ``` -Here’s an example of an environment variable in the `config.yml` file: +The following example shows an environment variable in the `config.yml` file: ```yml password: ${env.LDAP_PASSWORD} @@ -78,7 +81,7 @@ You can't use node certificates as admin certificates. The two must be separate. ## Basic usage -The `securityadmin.sh` tool can be run from any machine that has access to the http port of your OpenSearch cluster (the default port is 9200). You can change the security plugin configuration without having to access your nodes through SSH. +The `securityadmin.sh` tool can be run from any machine that has access to the HTTP port of your OpenSearch cluster (the default port is 9200). You can change the Security plugin configuration without having to access your nodes through SSH. Each node also includes the tool at `plugins/opensearch-security/tools/securityadmin.sh`. You might need to make the script executable before running it: @@ -101,8 +104,8 @@ To load your initial configuration (all YAML files), you might use the following -key ../../../config/kirk-key.pem ``` -- The `-cd` option specifies where the security plugin configuration files can be found. -- The `-icl` (`--ignore-clustername`) option tells the security plugin to upload the configuration regardless of the cluster name. As an alternative, you can also specify the cluster name with the `-cn` (`--clustername`) option. +- The `-cd` option specifies where the Security plugin configuration files can be found. +- The `-icl` (`--ignore-clustername`) option tells the Security plugin to upload the configuration regardless of the cluster name. As an alternative, you can also specify the cluster name with the `-cn` (`--clustername`) option. - Because the demo certificates are self-signed, this command disables hostname verification with the `-nhnv` (`--disable-host-name-verification`) option. - The `-cacert`, `-cert` and `-key` options define the location of your root CA certificate, the admin certificate, and the private key for the admin certificate. If the private key has a password, specify it with the `-keypass` option. @@ -169,11 +172,11 @@ Name | Description :--- | :--- `-ks` | The location of the keystore containing the admin certificate and all intermediate certificates, if any. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of `securityadmin.sh`. `-kspass` | The password for the keystore. -`-kst` | The key store type, either JKS or PKCS#12/PFX. If not specified, the security plugin tries to determine the type from the file extension. +`-kst` | The key store type, either JKS or PKCS#12/PFX. If not specified, the Security plugin tries to determine the type from the file extension. `-ksalias` | The alias of the admin certificate, if any. `-ts` | The location of the truststore containing the root certificate. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of `securityadmin.sh`. `-tspass` | The password for the truststore. -`-tst` | The truststore type, either JKS or PKCS#12/PFX. If not specified, the security plugin tries to determine the type from the file extension. +`-tst` | The truststore type, either JKS or PKCS#12/PFX. If not specified, the Security plugin tries to determine the type from the file extension. `-tsalias` | The alias for the root certificate, if any. @@ -204,11 +207,11 @@ Name | Description ### Configuration files settings -The following switches define which configuration files you want to push to the security plugin. You can either push a single file or specify a directory containing one or more configuration files. +The following switches define which configuration files you want to push to the Security plugin. You can either push a single file or specify a directory containing one or more configuration files. Name | Description :--- | :--- -`-cd` | Directory containing multiple security plugin configuration files. +`-cd` | Directory containing multiple Security plugin configuration files. `-f` | Single configuration file. Can't be used with `-cd`. `-t` | File type. `-rl` | Reload the current configuration and flush the internal cache. @@ -253,7 +256,7 @@ You can download all current configuration files from your cluster with the foll ./securityadmin.sh -backup my-backup-directory -ts ... -tspass ... -ks ... -kspass ... ``` -This command dumps the current security plugin configuration from your cluster to individual files in the directory you specify. You can then use these files as backups or to load the configuration into a different cluster. This command is useful when moving a proof-of-concept to production or if you need to add additional [reserved or hidden resources]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#reserved-and-hidden-resources): +This command dumps the current Security plugin configuration from your cluster to individual files in the directory you specify. You can then use these files as backups or to load the configuration into a different cluster. This command is useful when moving a proof-of-concept to production or if you need to add additional [reserved or hidden resources]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources): ```bash ./securityadmin.sh \ @@ -279,7 +282,7 @@ To migrate configuration YAML files from the Open Distro for Elasticsearch 0.x.x Name | Description :--- | :--- -`-backup` | Retrieve the current security plugin configuration from a running cluster and dump it to the working directory. +`-backup` | Retrieve the current Security plugin configuration from a running cluster and dump it to the working directory. `-migrate` | Migrate configuration YAML files from Open Distro for Elasticsearch 0.x.x to OpenSearch 1.x.x. @@ -287,11 +290,11 @@ Name | Description Name | Description :--- | :--- -`-dci` | Delete the security plugin configuration index and exit. This option is useful if the cluster state is red due to a corrupted security plugin index. -`-esa` | Enable shard allocation and exit. This option is useful if you disabled shard allocation while performing a full cluster restart and need to recreate the security plugin index. +`-dci` | Delete the Security plugin configuration index and exit. This option is useful if the cluster state is red due to a corrupted Security plugin index. +`-esa` | Enable shard allocation and exit. This option is useful if you disabled shard allocation while performing a full cluster restart and need to recreate the Security plugin index. `-w` | Displays information about the used admin certificate. -`-rl` | By default, the security plugin caches authenticated users, along with their roles and permissions, for one hour. This option reloads the current security plugin configuration stored in your cluster, invalidating any cached users, roles, and permissions. -`-i` | The security plugin index name. Default is `.opendistro_security`. +`-rl` | By default, the Security plugin caches authenticated users, along with their roles and permissions, for one hour. This option reloads the current Security plugin configuration stored in your cluster, invalidating any cached users, roles, and permissions. +`-i` | The Security plugin index name. Default is `.opendistro_security`. `-er` | Set explicit number of replicas or auto-expand expression for the `opensearch_security` index. `-era` | Enable replica auto-expand. `-dra` | Disable replica auto-expand. diff --git a/_security/configuration/system-indices.md b/_security/configuration/system-indices.md new file mode 100644 index 0000000000..fa83443c2c --- /dev/null +++ b/_security/configuration/system-indices.md @@ -0,0 +1,26 @@ +--- +layout: default +title: System indexes +parent: Configuration +nav_order: 4 +--- + +# System indexes + +By default, OpenSearch has a protected system index, `.opendistro_security`, which is used to store the Security configuration YAML files. You create this index using [securityadmin.sh]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/). Even with a user account that has read permissions for all indexes, you can't directly access the data in this system index. + +Instead, you first need to authenticate with an [admin certificate]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configure-admin-certificates) to gain access: + +```bash +curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opendistro_security/_search' +``` + +When Security is installed, the demo configuration automatically creates the `.opendistro_security` system index. It also adds several other indexes for the various OpenSearch plugins that integrate with the Security plugin: + +```yml +plugins.security.system_indices.enabled: true +plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"] +``` + +You can add additional system indexes in `opensearch.yml`. An alternative way to remove a system index is to delete it from the `plugins.security.system_indices.indices` list on each node and restart OpenSearch. + diff --git a/_security-plugin/configuration/tls.md b/_security/configuration/tls.md similarity index 96% rename from _security-plugin/configuration/tls.md rename to _security/configuration/tls.md index 9c0c75084d..0f929f9958 100755 --- a/_security-plugin/configuration/tls.md +++ b/_security/configuration/tls.md @@ -1,11 +1,11 @@ --- layout: default -title: TLS certificates +title: Configuring TLS certificates parent: Configuration -nav_order: 10 +nav_order: 15 --- -# Configure TLS certificates +# Configuring TLS certificates TLS is configured in `opensearch.yml`. Certificates are used to secure transport-layer traffic (node-to-node communication within your cluster) and REST-layer traffic (communication between a client and a node within your cluster). TLS is optional for the REST layer and mandatory for the transport layer. @@ -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/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/configuration/yaml.md similarity index 84% rename from _security-plugin/configuration/yaml.md rename to _security/configuration/yaml.md index 6b1e7e9043..0138df3f3e 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security/configuration/yaml.md @@ -1,22 +1,24 @@ --- layout: default -title: YAML files +title: Modifying the YAML files parent: Configuration -nav_order: 3 +nav_order: 10 --- -# YAML files +# Modifying the 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. +The Security installation provides a number of YAML confguration files that are used to store the necessary settings that define the way Security manages users, roles, and activity within the cluster. These settings range from configurations for authentication backends to lists of allowed endpoints and HTTP requests. -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. +Before running [`securityadmin.sh`]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/) to load the settings into the `.opendistro_security` index, perform an initial configuration of the YAML files. The files can be found in the `config/opensearch-security` directory. It's also good practice to back up these files so that you can reuse them for other clusters. + +The approach we recommend for using the YAML files is to first configure [reserved and hidden resources]({{site.url}}{{site.baseurl}}/security/access-control/api#reserved-and-hidden-resources), such as the `admin` and `kibanaserver` users. Thereafter you can create other users, roles, mappings, action groups, and tenants using OpenSearch Dashboards or the REST API. ## internal_users.yml This file contains any initial users that you want to add to the security plugin's internal user database. -The file format requires a hashed password. To generate one, run `plugins/opensearch-security/tools/hash.sh -p `. If you decide to keep any of the demo users, *change their passwords* and re-run [securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) to apply the new passwords. +The file format requires a hashed password. To generate one, run `plugins/opensearch-security/tools/hash.sh -p `. If you decide to keep any of the demo users, *change their passwords* and re-run [securityadmin.sh]({{site.url}}{{site.baseurl}}/security/configuration/security-admin/) to apply the new passwords. ```yml --- @@ -328,9 +330,9 @@ _meta: ## tenants.yml -You can use this file to specify and add any number of OpenSearch Dashboards tenants to your OpenSearch cluster. For more information about tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy). +You can use this file to specify and add any number of OpenSearch Dashboards tenants to your OpenSearch cluster. For more information about tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security/multi-tenancy/tenant-index). -Like all of the other YAML files, we recommend you use `tenants.yml` to add any tenants you must have in your cluster, and then use OpenSearch Dashboards or the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#tenants) if you need to further configure or create any other tenants. +Like all of the other YAML files, we recommend you use `tenants.yml` to add any tenants you must have in your cluster, and then use OpenSearch Dashboards or the [REST API]({{site.url}}{{site.baseurl}}/security/access-control/api/#tenants) if you need to further configure or create any other tenants. ```yml --- @@ -344,9 +346,9 @@ admin_tenant: ## nodes_dn.yml -`nodes_dn.yml` lets you add certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) an allow list to enable communication between any number of nodes and/or clusters. For example, a node that has the DN `CN=node1.example.com` in its allow list accepts communication from any other node or certificate that uses that DN. +`nodes_dn.yml` lets you add certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) an allow list to enable communication between any number of nodes and/or clusters. For example, a node that has the DN `CN=node1.example.com` in its allow list accepts communication from any other node or certificate that uses that DN. -The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically add DNs to your allow lists, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names). +The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically add DNs to your allow lists, use the [REST API]({{site.url}}{{site.baseurl}}/security/access-control/api/#distinguished-names). ```yml --- diff --git a/_security-plugin/index.md b/_security/index.md similarity index 80% rename from _security-plugin/index.md rename to _security/index.md index 0026795796..900f7a26ca 100755 --- a/_security-plugin/index.md +++ b/_security/index.md @@ -1,14 +1,14 @@ --- layout: default -title: About the security plugin +title: About Security nav_order: 1 has_children: false has_toc: false redirect_from: - - /security-plugin/ + - /security/ --- -# About security in OpenSearch +# About Security in OpenSearch Security in OpenSearch is built around four main features that work together to safeguard data and track activity within a cluster. Separately, these features are: @@ -29,21 +29,21 @@ Encryption protects both data at rest and in transit. At rest, encryption secure Encryption in transit encrypts data moving to, from, and within the cluster. OpenSearch uses the TLS protocol, which covers both client-to-node encryption (the REST layer) and node-to-node encryption (the transport layer). This combination of in-transit encryption helps ensure that both requests to OpenSearch and the movement of data among different nodes are safe from tampering. -You can find out more about configuring TLS in the [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/) section. +You can find out more about configuring TLS in the [Configuring TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/) section. ### Authentication Authentication is used to validate the identity of users and works by verifying an end user’s credentials against a backend configuration. These credentials can be a simple name and password, a JSON web token, or a TLS certificate. Once the authentication domain extracts those credentials from a user’s request, it can check their validity against the authentication backend. -The backend used for validation can be OpenSearch's built-in internal user database—used for storing user and role configurations and hashed passwords—or one of a wide range of industry-standard identification protocols such as LDAP, Active Directory, SAML, or OpenID Connect. A common practice is to chain together more than one authentication method to create a more robust defense against unauthorized access. This might involve, for example, HTTP basic authentication followed by a backend configuration that specifies the LDAP protocol. See the [Backend configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) section to learn more about setting up the backend. +The backend used for validation can be OpenSearch's built-in internal user database—used for storing user and role configurations and hashed passwords—or one of a wide range of industry-standard identification protocols such as LDAP, Active Directory, SAML, or OpenID Connect. A common practice is to chain together more than one authentication method to create a more robust defense against unauthorized access. This might involve, for example, HTTP basic authentication followed by a backend configuration that specifies the LDAP protocol. See the [Configuring the Security backend]({{site.url}}{{site.baseurl}}/security/configuration/configuration/) section to learn more about setting up the backend. ### Access control -Access control (or authorization) generally involves selectively assigning permissions to users that allow them to perform specific tasks, such as clearing the cache for a particular index or taking a snapshot of a cluster. However, rather than assign individual permissions directly to users, OpenSearch assigns these permissions to roles and then maps the roles to users. For more on setting up these relationships, see [Users and roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/). Roles, therefore, define the actions that users can perform, including the data they can read, the cluster settings they can modify, the indexes to which they can write, and so on. Roles are reusable across multiple users, and users can have multiple roles. +Access control (or authorization) generally involves selectively assigning permissions to users that allow them to perform specific tasks, such as clearing the cache for a particular index or taking a snapshot of a cluster. However, rather than assign individual permissions directly to users, OpenSearch assigns these permissions to roles and then maps the roles to users. For more on setting up these relationships, see [Users and roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/). Roles, therefore, define the actions that users can perform, including the data they can read, the cluster settings they can modify, the indexes to which they can write, and so on. Roles are reusable across multiple users, and users can have multiple roles. Another notable characteristic of access control in OpenSearch is the ability to assign user access through levels of increasing granularity. Fine-grained access control (FGAC) means that a role can control permissions for users at not only the cluster level but also the index level, the document level, and even the field level. For example, a role may provide a user access to certain cluster-level permissions but at the same time prevent the user from accessing a given group of indexes. Likewise, that role may grant access to certain types of documents but not others, or it may even include access to specific fields within a document but exclude access to other sensitive fields. Field masking further extends FGAC by providing options to mask certain types of data, such as a list of emails, which can still be aggregated but not made viewable to a role. -To learn more about this feature, see the [Access control]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/) section of the security documentation. +To learn more about this feature, see the [Access control]({{site.url}}{{site.baseurl}}/security/access-control/index/) section of the security documentation. ### Audit logging and compliance @@ -51,7 +51,7 @@ Finally, audit logging and compliance refer to mechanisms that allow for trackin How OpenSearch archives logging is configurable at many levels of detail, and there are a number of options for where those logs are stored. Compliance features also ensure that all data is available if and when compliance auditing is required. In this case, the logging can be automated to focus on data especially pertinent to those compliance requirements. -See the [Audit logs]({{site.url}}{{site.baseurl}}/security-plugin/audit-logs/index/) section of the security documentation to read more about this feature. +See the [Audit logs]({{site.url}}{{site.baseurl}}/security/audit-logs/index/) section of the security documentation to read more about this feature. ## Other features and functionality @@ -60,14 +60,14 @@ OpenSearch includes other features that complement the security infrastructure. ### Dashboards multi-tenancy One such feature is OpenSearch Dashboards multi-tenancy. Tenants are work spaces that include visualizations, index patterns, and other Dashboards objects. Multi-tenancy allows for the sharing of tenants among users of Dashboards and leverages OpenSearch roles to manage access to tenants and safely make them available to others. -For more information on creating tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy/). +For more information on creating tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security/multi-tenancy/tenant-index/). ### Cross-cluster search Another notable feature is cross-cluster search. This feature provides users with the ability to perform searches from one node in a cluster across other clusters that have been set up to coordinate this type of search. As with other features, cross-cluster search is supported by the OpenSearch access control infrastructure, which defines the permissions users have for working with this feature. -To learn more, see [Cross-cluster search]({{site.url}}{{site.baseurl}}/security-plugin/access-control/cross-cluster-search/). +To learn more, see [Cross-cluster search]({{site.url}}{{site.baseurl}}/security/access-control/cross-cluster-search/). ## Next steps -To get started, see the configuration overview in the [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) section, which provides the basic steps for setting up security in your OpenSearch implementation and includes links to information about customizing security for your business needs. +To get started, see the configuration overview in the [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/) section, which provides the basic steps for setting up security in your OpenSearch implementation and includes links to information about customizing security for your business needs. diff --git a/_troubleshoot/security-admin.md b/_troubleshoot/security-admin.md index 0fe63a73e7..8409953daf 100644 --- a/_troubleshoot/security-admin.md +++ b/_troubleshoot/security-admin.md @@ -92,7 +92,7 @@ Connected as CN=node-0.example.com,OU=SSL,O=Test,L=Test,C=DE ERR: CN=node-0.example.com,OU=SSL,O=Test,L=Test,C=DE is not an admin user ``` -You must use an admin certificate when executing the script. To learn more, see [Configure admin certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#configure-admin-certificates). +You must use an admin certificate when executing the script. To learn more, see [Configure admin certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls#configure-admin-certificates). ## Use the diagnose option diff --git a/index.md b/index.md index bba2f17120..d8ebefcd4d 100644 --- a/index.md +++ b/index.md @@ -64,9 +64,7 @@ For more comprehensive installation instructions for other download types, such ## 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. - +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/configuration/index/) with your own certificates, authentication method, users, and passwords. ## Looking for the Javadoc? diff --git a/quickstart.md b/quickstart.md index f007648476..3f9d591108 100644 --- a/quickstart.md +++ b/quickstart.md @@ -129,8 +129,8 @@ Create an index and define field mappings using a dataset provided by the OpenSe ## Next steps You successfully deployed your own OpenSearch cluster with OpenSearch Dashboards and added some sample data. Now you're ready to learn about configuration and functionality in more detail. Here are a few recommendations on where to begin: -- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) -- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/) +- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/) +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) - [Getting started with OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/index/) - [OpenSearch tools]({{site.url}}{{site.baseurl}}/tools/index/)