Reorganize Configuration section of the Security TOC (#2212)
* fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#2155-sec-toc-config-reorg Signed-off-by: cwillum <cwmmoore@amazon.com> * Rename security section. Fix links. Add redirects Signed-off-by: Naarcha-AWS <naarcha@amazon.com> --------- Signed-off-by: cwillum <cwmmoore@amazon.com> Signed-off-by: Naarcha-AWS <naarcha@amazon.com> Co-authored-by: Naarcha-AWS <naarcha@amazon.com>
This commit is contained in:
Chris Moore
GitHub
parent
84da2cf812
commit
d04e88b496
@ -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`.
|
||||
|
||||
|
||||
@ -40,7 +40,7 @@ collections:
|
||||
dashboards:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
security-plugin:
|
||||
security:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
security-analytics:
|
||||
@ -109,8 +109,8 @@ just_the_docs:
|
||||
dashboards:
|
||||
name: OpenSearch Dashboards
|
||||
nav_fold: true
|
||||
security-plugin:
|
||||
name: Security plugin
|
||||
security:
|
||||
name: Security in OpenSearch
|
||||
nav_fold: true
|
||||
security-analytics:
|
||||
name: Security analytics plugin
|
||||
|
||||
@ -7,7 +7,7 @@ nav_order: 70
|
||||
|
||||
# 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 }
|
||||
|
||||
@ -2,6 +2,7 @@
|
||||
layout: default
|
||||
title: ISM Error Prevention API
|
||||
parent: ISM Error Prevention
|
||||
grand_parent: Index State Management
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
|
||||
@ -2,6 +2,7 @@
|
||||
layout: default
|
||||
title: ISM Error Prevention resolutions
|
||||
parent: ISM Error Prevention
|
||||
grand_parent: Index State Management
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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,8 @@ 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/)
|
||||
<<<<<<< HEAD
|
||||
- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/)
|
||||
=======
|
||||
- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/)
|
||||
>>>>>>> main
|
||||
|
||||
@ -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/)
|
||||
- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/)
|
||||
@ -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/)
|
||||
- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/)
|
||||
@ -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/)
|
||||
- [About the security plugin]({{site.url}}{{site.baseurl}}/security/index/)
|
||||
@ -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/)
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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 with a create user operation. To add a backend role to a create user request, follow the [Create user]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user) instructions in the Security Plugin API documentation.
|
||||
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.
|
||||
|
||||
<!-- ## (Advanced) Limit access by individual
|
||||
|
||||
If you only want users to be able to see and modify their own monitors and destinations, duplicate the `alerting_full_access` role and add the following [DLS query]({{site.url}}{{site.baseurl}}/security-plugin/access-control/document-level-security/) to it:
|
||||
If you only want users to be able to see and modify their own monitors and destinations, duplicate the `alerting_full_access` role and add the following [DLS query]({{site.url}}{{site.baseurl}}/security/access-control/document-level-security/) to it:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -107,7 +107,7 @@ Regular user | No | Don’t update the backend roles on the monitor.
|
||||
- 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-plugin/access-control/api#create-role).
|
||||
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.
|
||||
|
||||
@ -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
|
||||
:--- | :---
|
||||
|
||||
@ -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/multi-tenancy/tenant-index/).
|
||||
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 }
|
||||
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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/).
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -343,7 +343,7 @@ Request fields | Description
|
||||
`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]({{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. <br /><br > `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-plugin/access-control/users-roles/) in order to restore a snapshot using the type `remote_snapshot`. <br /><br > Defaults to `local`.
|
||||
`storage_type` | `local` indicates that all snapshot metadata and index data will be downloaded to local storage. <br /><br > `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`. <br /><br > 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:
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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`.
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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/<role>
|
||||
}
|
||||
```
|
||||
|
||||
>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 <admin_cert file name> --key <admin_cert_key file name> <domain>/_opendistro/_security/api/audit -H 'Content-Type: application/json' -d'[{"op":"add","path":"/config/enabled","value":"true"}]'
|
||||
@ -2,7 +2,7 @@
|
||||
layout: default
|
||||
title: Cross-cluster search
|
||||
parent: Access control
|
||||
nav_order: 40
|
||||
nav_order: 105
|
||||
---
|
||||
|
||||
# Cross-cluster search
|
||||
@ -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
|
||||
@ -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`
|
||||
|
||||
@ -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.
|
||||
@ -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
|
||||
@ -2,7 +2,7 @@
|
||||
layout: default
|
||||
title: User impersonation
|
||||
parent: Access control
|
||||
nav_order: 20
|
||||
nav_order: 100
|
||||
---
|
||||
|
||||
# User impersonation
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
layout: default
|
||||
title: Access control
|
||||
nav_order: 30
|
||||
nav_order: 75
|
||||
has_children: true
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /security-plugin/access-control/
|
||||
- /security/access-control/
|
||||
---
|
||||
|
||||
# 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.
|
||||
@ -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 }
|
||||
|
||||
|
||||
@ -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.
|
||||
@ -130,7 +130,7 @@ Role | Description
|
||||
`snapshot_management_read_access` | Grants permissions to view policies but not create, modify, start, stop, or delete them.
|
||||
`point_in_time_full_access` | Grants full permissions to all Point in Time operations.
|
||||
|
||||
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
|
||||
@ -2,7 +2,7 @@
|
||||
layout: default
|
||||
title: Audit log field reference
|
||||
parent: Audit logs
|
||||
nav_order: 1
|
||||
nav_order: 130
|
||||
---
|
||||
|
||||
# Audit log field reference
|
||||
@ -1,11 +1,11 @@
|
||||
---
|
||||
layout: default
|
||||
title: Audit logs
|
||||
nav_order: 40
|
||||
nav_order: 125
|
||||
has_children: true
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /security-plugin/audit-logs/
|
||||
- /security/audit-logs/
|
||||
---
|
||||
|
||||
# Audit logs
|
||||
@ -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.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
layout: default
|
||||
title: Audit log storage types
|
||||
parent: Audit logs
|
||||
nav_order: 10
|
||||
nav_order: 135
|
||||
---
|
||||
|
||||
# Audit log storage types
|
||||
31
_security/authentication-backends/authc-index.md
Executable file
31
_security/authentication-backends/authc-index.md
Executable file
@ -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.
|
||||
@ -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).
|
||||
@ -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
|
||||
@ -1,8 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: OpenID Connect
|
||||
parent: Configuration
|
||||
nav_order: 32
|
||||
parent: Authentication backends
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
# OpenID Connect
|
||||
@ -313,7 +313,7 @@ opensearch.ssl.verificationMode: none
|
||||
opensearch.requestHeadersAllowlist: ["Authorization", "security_tenant"]
|
||||
```
|
||||
|
||||
To include OpenID Connect with other authentication types in the Dashboards sign-in window, see [Multiple option authentication for Dashboards sign-in]({{site.url}}{{site.baseurl}}/security-plugin/configuration/multi-auth/).
|
||||
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
|
||||
@ -1,8 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: Proxy-based authentication
|
||||
parent: Configuration
|
||||
nav_order: 40
|
||||
parent: Authentication backends
|
||||
nav_order: 65
|
||||
---
|
||||
|
||||
# Proxy-based authentication
|
||||
@ -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):
|
||||
|
||||
```
|
||||
<saml2:Attribute Name='Role'>
|
||||
@ -314,7 +317,7 @@ 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 [Multiple option authentication for Dashboards sign-in]({{site.url}}{{site.baseurl}}/security-plugin/configuration/multi-auth/).
|
||||
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
|
||||
@ -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
|
||||
@ -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}}/install-and-configure/install-dashboards/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
|
||||
@ -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/).
|
||||
@ -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. To use OpenSearch in a production environment, you must configure it manually:
|
||||
|
||||
1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker#configuring-basic-security-settings).
|
||||
1. [Reconfigure `opensearch.yml` to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls).
|
||||
1. [Reconfigure `config.yml` to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database).
|
||||
1. [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 the `securityadmin` script]({{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 }
|
||||
@ -1,11 +1,11 @@
|
||||
---
|
||||
layout: default
|
||||
title: Multiple authentication options for Dashboards sign-in
|
||||
title: Configuring sign-in options
|
||||
parent: Configuration
|
||||
nav_order: 3
|
||||
nav_order: 35
|
||||
---
|
||||
|
||||
# Configure Dashboards sign-in for multiple authentication options
|
||||
# Configuring Dashboards sign-in for multiple authentication options
|
||||
|
||||
You can configure the sign-in window for OpenSearch Dashboards to provide either a single option for authenticating users at sign-in or multiple options. Currently, Dashboards supports basic authentication, OpenID Connect, and SAML as the multiple options.
|
||||
|
||||
@ -14,7 +14,7 @@ You can configure the sign-in window for OpenSearch Dashboards to provide either
|
||||
Consider the following sequence of steps before configuring the sign-in window for multiple authentication options.
|
||||
|
||||
1. Decide which types of authentication to make available at sign-in.
|
||||
1. Configure each authentication type, including an authentication domain for the identity provider (IdP) and the essential settings that give each type sign-in access to OpenSearch Dashboards. For OpenId Connect backend configuration, see [OpenID Connect]({{site.url}}{{site.baseurl}}/security-plugin/configuration/openid-connect/). For SAML backend configuration, see [SAML]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/).
|
||||
1. Configure each authentication type, including an authentication domain for the identity provider (IdP) and the essential settings that give each type sign-in access to OpenSearch Dashboards. For OpenId Connect backend configuration, see [OpenID Connect]({{site.url}}{{site.baseurl}}/security/authentication-backends/openid-connect/). For SAML backend configuration, see [SAML]({{site.url}}{{site.baseurl}}/security/authentication-backends/saml/).
|
||||
1. Add, enable, and configure multiple option authentication settings in the `opensearch_dashboards.yml` file.
|
||||
|
||||
## Enabling multiple authentication options
|
||||
@ -74,7 +74,7 @@ Setting | Description
|
||||
|
||||
### OpenID Connect authentication settings
|
||||
|
||||
These settings allow you to customize the sign-in button associated with OpenID Connect authentication. For the essential settings required to use OpenID Connect as a single sign-in option, see [OpenSearch Dashboards single sign-on]({{site.url}}{{site.baseurl}}/security-plugin/configuration/openid-connect/#opensearch-dashboards-single-sign-on).
|
||||
These settings allow you to customize the sign-in button associated with OpenID Connect authentication. For the essential settings required to use OpenID Connect as a single sign-in option, see [OpenSearch Dashboards single sign-on]({{site.url}}{{site.baseurl}}/security/authentication-backends/openid-connect/#opensearch-dashboards-single-sign-on).
|
||||
|
||||
Setting | Description
|
||||
:--- | :--- |:--- |:--- |
|
||||
@ -84,7 +84,7 @@ Setting | Description
|
||||
|
||||
### SAML authentication settings
|
||||
|
||||
These settings allow you to customize the sign-in button associated with SAML authentication. For the essential settings required to use SAML as a sign-in option, see [OpenSearch Dashboards configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/#opensearch-dashboards-configuration).
|
||||
These settings allow you to customize the sign-in button associated with SAML authentication. For the essential settings required to use SAML as a sign-in option, see [OpenSearch Dashboards configuration]({{site.url}}{{site.baseurl}}/security/authentication-backends/saml/#opensearch-dashboards-configuration).
|
||||
|
||||
Setting | Description
|
||||
:--- | :--- |:--- |:--- |
|
||||
@ -1,18 +1,18 @@
|
||||
---
|
||||
layout: default
|
||||
title: Apply changes with the securityadmin script
|
||||
title: Applying changes to configuration files
|
||||
parent: Configuration
|
||||
nav_order: 20
|
||||
nav_order: 25
|
||||
---
|
||||
|
||||
# Apply changes with the securityadmin script
|
||||
# Applying changes to configuration files
|
||||
|
||||
On **Windows**, use **securityadmin.bat** in place of **securityadmin.sh**. For more information, see [Windows usage](#windows-usage).
|
||||
{: .note}
|
||||
|
||||
The security plugin stores its configuration---including users, roles, and permissions---in an index on the OpenSearch cluster (`.opendistro_security`). Storing these settings in an index lets you change settings without restarting the cluster and eliminates the need to edit configuration files on every single node.
|
||||
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`.
|
||||
|
||||
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 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
|
||||
@ -23,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.
|
||||
|
||||
@ -60,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}
|
||||
@ -81,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.
|
||||
|
||||
`securityadmin.sh` requires that SSL/TLS transport is enabled on your opensearch cluster. In other words, make sure that the `plugins.security.ssl.http.enabled: true` is set in `opensearch.yml` before proceeding.
|
||||
{: .note}
|
||||
@ -107,8 +107,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.
|
||||
|
||||
@ -175,11 +175,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.
|
||||
|
||||
|
||||
@ -210,11 +210,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.
|
||||
@ -259,7 +259,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 \
|
||||
@ -285,7 +285,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.
|
||||
|
||||
|
||||
@ -293,11 +293,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.
|
||||
26
_security/configuration/system-indices.md
Normal file
26
_security/configuration/system-indices.md
Normal file
@ -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.
|
||||
|
||||
@ -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 security plugin configuration using [`plugins/opensearch-security/tools/securityadmin.sh`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) or the REST API. Admin certificates are configured in `opensearch.yml` by stating their DN(s):
|
||||
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:
|
||||
@ -1,22 +1,24 @@
|
||||
---
|
||||
layout: default
|
||||
title: YAML files
|
||||
title: Modifying the YAML files
|
||||
parent: Configuration
|
||||
nav_order: 4
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# YAML files
|
||||
# Modifying the YAML files
|
||||
|
||||
Before running [`securityadmin.sh`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) to load the settings into the `.opendistro_security` index, configure the YAML files in `config/opensearch-security`. You might want to back up these files so that you can reuse them on other clusters.
|
||||
The 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 <new-password>`. 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 <new-password>`. 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/multi-tenancy/tenant-index).
|
||||
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
|
||||
---
|
||||
@ -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/multi-tenancy/tenant-index/).
|
||||
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.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
layout: default
|
||||
title: Multi-tenancy aggregate view for saved objects
|
||||
parent: OpenSearch Dashboards multi-tenancy
|
||||
nav_order: 60
|
||||
nav_order: 150
|
||||
---
|
||||
|
||||
# OpenSearch Dashboards multi-tenancy aggregate view for saved objects
|
||||
@ -2,7 +2,7 @@
|
||||
layout: default
|
||||
title: Multi-tenancy configuration
|
||||
parent: OpenSearch Dashboards multi-tenancy
|
||||
nav_order: 55
|
||||
nav_order: 145
|
||||
---
|
||||
|
||||
|
||||
@ -65,7 +65,7 @@ To create tenants, use OpenSearch Dashboards, the REST API, or `tenants.yml`.
|
||||
|
||||
#### REST API
|
||||
|
||||
See [Create tenant]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-tenant).
|
||||
See [Create tenant]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-tenant).
|
||||
|
||||
|
||||
#### tenants.yml
|
||||
@ -99,7 +99,7 @@ After creating a tenant, give a role access to it using OpenSearch Dashboards, t
|
||||
|
||||
#### 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).
|
||||
|
||||
|
||||
#### roles.yml
|
||||
@ -1,11 +1,11 @@
|
||||
---
|
||||
layout: default
|
||||
title: OpenSearch Dashboards multi-tenancy
|
||||
nav_order: 50
|
||||
nav_order: 140
|
||||
has_children: true
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /security-plugin/multi-tenancy/
|
||||
- /security/multi-tenancy/
|
||||
---
|
||||
|
||||
# OpenSearch Dashboards multi-tenancy
|
||||
@ -31,5 +31,5 @@ http://<opensearch_dashboards_host>:5601/app/opensearch-dashboards?security_tena
|
||||
|
||||
## Next steps
|
||||
|
||||
To get started with tenants, see [Multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security-plugin/multi-tenancy/multi-tenancy-config/) for information on enabling multi-tenancy, adding tenants, and assigning roles to tenants.
|
||||
To get started with tenants, see [Multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security/multi-tenancy/multi-tenancy-config/) for information on enabling multi-tenancy, adding tenants, and assigning roles to tenants.
|
||||
|
||||
@ -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
|
||||
|
||||
2
index.md
2
index.md
@ -62,7 +62,7 @@ OpenSearch has several features and plugins to help index, secure, monitor, and
|
||||
|
||||
|
||||
## 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/) with your own certificates, authentication method, users, and 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?
|
||||
|
||||
|
||||
@ -129,7 +129,7 @@ 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/)
|
||||
- [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/)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user