From 43d9d6bb13fbe5b11030e98df9af39a4b117d1c5 Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Thu, 21 Mar 2024 13:33:07 +0000 Subject: [PATCH 01/14] updating the doucumentation to be more descriptive and adding examples of HTTP methods. Signed-off-by: leanne.laceybyrne@eliatra.com --- .../document-apis/index-document.md | 38 +- .../access-control/document-level-security.md | 562 ++++++++++++++++++ 2 files changed, 589 insertions(+), 11 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index ec1664bc44..bb3309d031 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -11,17 +11,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple} -Before you can search for data, you must first add documents. This operation adds a single document to your index. - -## Example - -```json -PUT sample-index/_doc/1 -{ - "Description": "To be or not to be, that is the question." -} -``` -{% include copy-curl.html %} +Through the use of HTTP methods, we can interact with the data in our database. ## Path and HTTP methods @@ -32,6 +22,32 @@ POST /_doc PUT /_create/<_id> POST /_create/<_id> ``` +- PUT adds or updates documents with a specified ID in the index. Used for controlled document creation or updates. +- POST adds documents to the index with auto-generated IDs. Useful for adding new documents without specifying IDs. +- `_create` is a type identifier indicating document creation should only occur if the document with the specified ID doesn't already exist. +- `` represents the name of the index where the document will be added. +- `<_id>` represents the unique identifier of the document. + +## Adding a sample index and documents to use the HTTP methods + +Before you can search for data, you must first add documents. +To do this follow the steps: +1. Open OpenSearch Dashboards +2. Navigate to the hamburger menu +3. In the **Management** section, choose **Dev Tools** +4. Running the PUT command in the dev tools and send the request to create the index `sample-index` +```json +PUT /sample-index +``` +## Example + +```json +PUT sample-index/_doc/1 +{ + "Description": "To be or not to be, that is the question." +} +``` +{% include copy-curl.html %} ## URL parameters diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index 3f2049a1e2..b06d41dcab 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -36,6 +36,568 @@ This query specifies that for the role to have access to a document, its `genres A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`: +--- +layout: default +title: Document-level security +parent: Access control +nav_order: 85 +redirect_from: +- /security/access-control/document-level-security/ +- /security-plugin/access-control/document-level-security/ +--- + +# Document-level security (DLS) + +Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section. + +![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) + + +## Simple roles + +Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document level security** section: + +```json +{ + "bool": { + "must": { + "match": { + "genres": "Comedy" + } + } + } +} +``` + +This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`. + +A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. + +In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`: + +```json +PUT _plugins/_security/api/roles/public_data +{ + "cluster_permissions": [ + "*" + ], + "index_permissions": [{ + "index_patterns": [ + "pub*" + ], + "dls": "{\"term\": { \"public\": true}}", + "allowed_actions": [ + "read" + ] + }] +} +``` + +These queries can be as complex as you want, but we recommend keeping them simple to minimize the performance impact that the document-level security feature has on the cluster. +{: .warning } + +### 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]({{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: + +```json +{ + "bool": { + "must": { + "match": { + "user.id": "User-1" + } + } + } +} +``` + +```json +{ + "bool": { + "must": { + "match": { + "user.id": "User-2" + } + } + } +} +``` + +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). + + +## Parameter substitution + +A number of variables exist that you can use to enforce rules based on the properties of a user. For example, `${user.name}` is replaced with the name of the current user. + +This rule allows a user to read any document where the username is a value of the `readable_by` field: + +```json +PUT _plugins/_security/api/roles/user_data +{ + "cluster_permissions": [ + "*" + ], + "index_permissions": [{ + "index_patterns": [ + "pub*" + ], + "dls": "{\"term\": { \"readable_by\": \"${user.name}\"}}", + "allowed_actions": [ + "read" + ] + }] +} +``` + +This table lists substitutions. + +Term | Replaced with +:--- | :--- +`${user.name}` | Username. +`${user.roles}` | A comma-separated, quoted list of user backend roles. +`${user.securityRoles}` | A comma-separated, quoted list of user security roles. +`${attr..}` | An attribute with name `` defined for a user. `` is `internal`, `jwt`, `proxy` or `ldap` + + +## Attribute-based security + +You can use roles and parameter substitution with the `terms_set` query to enable attribute-based security. + +> Note that the `security_attributes` of the index need to be of type `keyword`. + +#### User definition + +```json +PUT _plugins/_security/api/internalusers/user1 +{ + "password": "asdf", + "backend_roles": ["abac"], + "attributes": { + "permissions": "\"att1\", \"att2\", \"att3\"" + } +} +``` + +#### Role definition + +```json +PUT _plugins/_security/api/roles/abac +{ + "index_permissions": [{ + "index_patterns": [ + "*" + ], + "dls": "{\"terms_set\": {\"security_attributes\": {\"terms\": [${attr.internal.permissions}], \"minimum_should_match_script\": {\"source\": \"doc['security_attributes'].length\"}}}}", + "allowed_actions": [ + "read" + ] + }] +} +``` +## Use term-level lookup queries (TLQs) with DLS + +You can perform term-level lookup queries (TLQs) with document-level security (DLS) using either of two modes: adaptive or filter level. The default mode is adaptive, where OpenSearch automatically switches between Lucene-level or filter-level mode depending on whether or not there is a TLQ. DLS queries without TLQs are executed in Lucene-level mode, whereas DLS queries with TLQs are executed in filter-level mode. + +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]({{site.url}}{{site.baseurl}}/query-dsl/term/index/). + +### How to set the DLS evaluation mode in `opensearch.yml` + +By default, the DLS evaluation mode is set to `adaptive`. You can also explicitly set the mode in `opensearch.yml` with the `plugins.security.dls.mode` setting. Add a line to `opensearch.yml` with the desired evaluation mode. +For example, to set it to filter level, add this line: +``` +plugins.security.dls.mode: filter-level +``` + +#### DLS evaluation modes + +| Evaluation mode | Parameter | Description | Usage | +:--- | :--- | :--- | :--- | +Lucene-level DLS | `lucene-level` | This setting makes all DLS queries apply to the Lucene level. | Lucene-level DLS modifies Lucene queries and data structures directly. This is the most efficient mode but does not allow certain advanced constructs in DLS queries, including TLQs. +Filter-level DLS | `filter-level` | This setting makes all DLS queries apply to the filter level. | In this mode, OpenSearch applies DLS by modifying queries that OpenSearch receives. This allows for term-level lookup queries in DLS queries, but you can only use the `get`, `search`, `mget`, and `msearch` operations to retrieve data from the protected index. Additionally, cross-cluster searches are limited with this mode. +Adaptive | `adaptive-level` | The default setting that allows OpenSearch to automatically choose the mode. | DLS queries without TLQs are executed in Lucene-level mode, while DLS queries that contain TLQ are executed in filter- level mode. + +## DLS and multiple roles + +OpenSearch combines all DLS queries with the logical `OR` operator. However, when a role that uses DLS is combined with another security role that doesn't use DLS, the query results are filtered to display only documents matching the DLS from the first role. This filter rule also applies to roles that do not grant read documents. + +### When to enable `plugins.security.dfm_empty_overrides_all` + +When to enable the `plugins.security.dfm_empty_overrides_all` setting depends on whether you want to restrict user access to documents without DLS. + + +To ensure access is not restricted, you can set the following configuration in `opensearch.yml`: + +``` +plugins.security.dfm_empty_overrides_all: true +``` +{% include copy.html %} + + +The following examples show what level of access roles with DLS enabled and without DLS enabled, depending on the interaction. These examples can help you decide when to enable the `plugins.security.dfm_empty_overrides_all` setting. + +#### Example: Document access + +This example demonstrates that enabling `plugins.security.dfm_empty_overrides_all` is beneficial in scenarios where you need specific users to have unrestricted access to documents despite being part of a broader group with restricted access. + +**Role A with DLS**: This role is granted to a broad group of users and includes DLS to restrict access to specific documents, as shown in the following permission set: + +``` +{ + "index_permissions": [ + { + "index_patterns": ["example-index"], + "dls": "[.. some DLS here ..]", + "allowed_actions": ["indices:data/read/search"] + } + ] +} +``` + +**Role B without DLS:** This role is specifically granted to certain users, such as administrators, and does not include DLS, as shown in the following permission set: + +``` +{ + "index_permissions" : [ + { + "index_patterns" : ["*"], + "allowed_actions" : ["indices:data/read/search"] + } + ] +} +``` +{% include copy.html %} + +Setting `plugins.security.dfm_empty_overrides_all` to `true` ensures that administrators assigned Role B can override any DLS restrictions imposed by Role A. This allows specific Role B users to access all documents, regardless of the restrictions applied by Role A's DLS restrictions. + +#### Example: Search template access + +In this example, two roles are defined, one with DLS and another without DLS, granting access to search templates: + +**Role A with DLS:** + +``` +{ + "index_permissions": [ + { + "index_patterns": [ + "example-index" + ], + "dls": "[.. some DLS here ..]", + "allowed_actions": [ + "indices:data/read/search", + ] + } + ] +} +``` +{% include copy.html %} + +**Role B, without DLS**, which only grants access to search templates: + +``` +{ + "index_permissions" : [ + { + "index_patterns" : [ "*" ], + "allowed_actions" : [ "indices:data/read/search/template" ]--- +layout: default +title: Document-level security +parent: Access control +nav_order: 85 +redirect_from: +- /security/access-control/document-level-security/ +- /security-plugin/access-control/document-level-security/ +--- + +# Document-level security (DLS) + +Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section. + +![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) + + +## Simple roles + +Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document level security** section: + +```json +{ + "bool": { + "must": { + "match": { + "genres": "Comedy" + } + } + } +} +``` + +This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`. + +A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. + +In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`: + +```json +PUT _plugins/_security/api/roles/public_data +{ + "cluster_permissions": [ + "*" + ], + "index_permissions": [{ + "index_patterns": [ + "pub*" + ], + "dls": "{\"term\": { \"public\": true}}", + "allowed_actions": [ + "read" + ] + }] +} +``` + +These queries can be as complex as you want, but we recommend keeping them simple to minimize the performance impact that the document-level security feature has on the cluster. +{: .warning } + +### 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]({{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: + +```json +{ + "bool": { + "must": { + "match": { + "user.id": "User-1" + } + } + } +} +``` + +```json +{ + "bool": { + "must": { + "match": { + "user.id": "User-2" + } + } + } +} +``` + +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). + + +## Parameter substitution + +A number of variables exist that you can use to enforce rules based on the properties of a user. For example, `${user.name}` is replaced with the name of the current user. + +This rule allows a user to read any document where the username is a value of the `readable_by` field: + +```json +PUT _plugins/_security/api/roles/user_data +{ + "cluster_permissions": [ + "*" + ], + "index_permissions": [{ + "index_patterns": [ + "pub*" + ], + "dls": "{\"term\": { \"readable_by\": \"${user.name}\"}}", + "allowed_actions": [ + "read" + ] + }] +} +``` + +This table lists substitutions. + +Term | Replaced with +:--- | :--- +`${user.name}` | Username. +`${user.roles}` | A comma-separated, quoted list of user backend roles. +`${user.securityRoles}` | A comma-separated, quoted list of user security roles. +`${attr..}` | An attribute with name `` defined for a user. `` is `internal`, `jwt`, `proxy` or `ldap` + + +## Attribute-based security + +You can use roles and parameter substitution with the `terms_set` query to enable attribute-based security. + +> Note that the `security_attributes` of the index need to be of type `keyword`. + +#### User definition + +```json +PUT _plugins/_security/api/internalusers/user1 +{ + "password": "asdf", + "backend_roles": ["abac"], + "attributes": { + "permissions": "\"att1\", \"att2\", \"att3\"" + } +} +``` + +#### Role definition + +```json +PUT _plugins/_security/api/roles/abac +{ + "index_permissions": [{ + "index_patterns": [ + "*" + ], + "dls": "{\"terms_set\": {\"security_attributes\": {\"terms\": [${attr.internal.permissions}], \"minimum_should_match_script\": {\"source\": \"doc['security_attributes'].length\"}}}}", + "allowed_actions": [ + "read" + ] + }] +} +``` +## Use term-level lookup queries (TLQs) with DLS + +You can perform term-level lookup queries (TLQs) with document-level security (DLS) using either of two modes: adaptive or filter level. The default mode is adaptive, where OpenSearch automatically switches between Lucene-level or filter-level mode depending on whether or not there is a TLQ. DLS queries without TLQs are executed in Lucene-level mode, whereas DLS queries with TLQs are executed in filter-level mode. + +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]({{site.url}}{{site.baseurl}}/query-dsl/term/index/). + +### How to set the DLS evaluation mode in `opensearch.yml` + +By default, the DLS evaluation mode is set to `adaptive`. You can also explicitly set the mode in `opensearch.yml` with the `plugins.security.dls.mode` setting. Add a line to `opensearch.yml` with the desired evaluation mode. +For example, to set it to filter level, add this line: +``` +plugins.security.dls.mode: filter-level +``` + +#### DLS evaluation modes + +| Evaluation mode | Parameter | Description | Usage | +:--- | :--- | :--- | :--- | +Lucene-level DLS | `lucene-level` | This setting makes all DLS queries apply to the Lucene level. | Lucene-level DLS modifies Lucene queries and data structures directly. This is the most efficient mode but does not allow certain advanced constructs in DLS queries, including TLQs. +Filter-level DLS | `filter-level` | This setting makes all DLS queries apply to the filter level. | In this mode, OpenSearch applies DLS by modifying queries that OpenSearch receives. This allows for term-level lookup queries in DLS queries, but you can only use the `get`, `search`, `mget`, and `msearch` operations to retrieve data from the protected index. Additionally, cross-cluster searches are limited with this mode. +Adaptive | `adaptive-level` | The default setting that allows OpenSearch to automatically choose the mode. | DLS queries without TLQs are executed in Lucene-level mode, while DLS queries that contain TLQ are executed in filter- level mode. + +## DLS and multiple roles + +OpenSearch combines all DLS queries with the logical `OR` operator. However, when a role that uses DLS is combined with another security role that doesn't use DLS, the query results are filtered to display only documents matching the DLS from the first role. This filter rule also applies to roles that do not grant read documents. + +### When to enable `plugins.security.dfm_empty_overrides_all` + +When to enable the `plugins.security.dfm_empty_overrides_all` setting depends on whether you want to restrict user access to documents without DLS. + + +To ensure access is not restricted, you can set the following configuration in `opensearch.yml`: + +``` +plugins.security.dfm_empty_overrides_all: true +``` +{% include copy.html %} + + +The following examples show what level of access roles with DLS enabled and without DLS enabled, depending on the interaction. These examples can help you decide when to enable the `plugins.security.dfm_empty_overrides_all` setting. + +#### Example: Document access + +This example demonstrates that enabling `plugins.security.dfm_empty_overrides_all` is beneficial in scenarios where you need specific users to have unrestricted access to documents despite being part of a broader group with restricted access. + +**Role A with DLS**: This role is granted to a broad group of users and includes DLS to restrict access to specific documents, as shown in the following permission set: + +``` +{ + "index_permissions": [ + { + "index_patterns": ["example-index"], + "dls": "[.. some DLS here ..]", + "allowed_actions": ["indices:data/read/search"] + } + ] +} +``` + +**Role B without DLS:** This role is specifically granted to certain users, such as administrators, and does not include DLS, as shown in the following permission set: + +``` +{ + "index_permissions" : [ + { + "index_patterns" : ["*"], + "allowed_actions" : ["indices:data/read/search"] + } + ] +} +``` +{% include copy.html %} + +Setting `plugins.security.dfm_empty_overrides_all` to `true` ensures that administrators assigned Role B can override any DLS restrictions imposed by Role A. This allows specific Role B users to access all documents, regardless of the restrictions applied by Role A's DLS restrictions. + +#### Example: Search template access + +In this example, two roles are defined, one with DLS and another without DLS, granting access to search templates: + +**Role A with DLS:** + +``` +{ + "index_permissions": [ + { + "index_patterns": [ + "example-index" + ], + "dls": "[.. some DLS here ..]", + "allowed_actions": [ + "indices:data/read/search", + ] + } + ] +} +``` +{% include copy.html %} + +**Role B, without DLS**, which only grants access to search templates: + +``` +{ + "index_permissions" : [ + { + "index_patterns" : [ "*" ], + "allowed_actions" : [ "indices:data/read/search/template" ] + } + ] +} +``` +{% include copy.html %} + +When a user has both Role A and Role B permissions, the query results are filtered based on Role A's DLS, even though Role B doesn't use DLS. The DLS settings are retained, and the returned access is appropriately restricted. + +When a user is assigned both Role A and Role B and the `plugins.security.dfm_empty_overrides_all` setting is enabled, Role B's permissions Role B's permissions will override Role A's restrictions, allowing that user to access all documents. This ensures that the role without DLS takes precedence in the search query response. + + } + ] +} +``` +{% include copy.html %} + +When a user has both Role A and Role B permissions, the query results are filtered based on Role A's DLS, even though Role B doesn't use DLS. The DLS settings are retained, and the returned access is appropriately restricted. + +When a user is assigned both Role A and Role B and the `plugins.security.dfm_empty_overrides_all` setting is enabled, Role B's permissions Role B's permissions will override Role A's restrictions, allowing that user to access all documents. This ensures that the role without DLS takes precedence in the search query response. ```json PUT _plugins/_security/api/roles/public_data From 1172fff1e95f7a65ed7bc31ad6d680656baabaad Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Fri, 22 Mar 2024 17:01:55 +0000 Subject: [PATCH 02/14] actual runnable examples given to the user for greater clarity Signed-off-by: leanne.laceybyrne@eliatra.com --- .../document-apis/index-document.md | 28 ++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index bb3309d031..046522e25e 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -35,20 +35,40 @@ To do this follow the steps: 1. Open OpenSearch Dashboards 2. Navigate to the hamburger menu 3. In the **Management** section, choose **Dev Tools** -4. Running the PUT command in the dev tools and send the request to create the index `sample-index` +4. Run the following commands in the dev tools by pressing the green triangle play button to send the request. + +### Create a sample-index ```json PUT /sample-index ``` -## Example +{% include copy-curl.html %} + +### Example PUT request + +```json +PUT /sample_index/_doc/1 +{ + "name": "Example", + "price": 29.99, + "description": "To be or not to be, that is the question" +} +``` +{% include copy-curl.html %} + +### Example POST request ```json -PUT sample-index/_doc/1 +POST /sample_index/_doc { - "Description": "To be or not to be, that is the question." + "name": "Another Example", + "price": 19.99, + "description": "We are such stuff as dreams are made on" } + ``` {% include copy-curl.html %} + ## URL parameters In your request, you must specify the index you want to add your document to. If the index doesn't already exist, OpenSearch automatically creates the index and adds in your document. All other URL parameters are optional. From 107358ea341bb0c3ec1ac7b98fc26931634247d7 Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Wed, 27 Mar 2024 10:19:51 +0000 Subject: [PATCH 03/14] removing duplication added in error and addressing review comments Signed-off-by: leanne.laceybyrne@eliatra.com --- .../access-control/document-level-security.md | 42 +------------------ 1 file changed, 2 insertions(+), 40 deletions(-) diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index b06d41dcab..4f45315aa1 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -3,44 +3,6 @@ layout: default title: Document-level security parent: Access control nav_order: 85 -redirect_from: - - /security/access-control/document-level-security/ - - /security-plugin/access-control/document-level-security/ ---- - -# Document-level security (DLS) - -Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section. - -![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) - - -## Simple roles - -Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document level security** section: - -```json -{ - "bool": { - "must": { - "match": { - "genres": "Comedy" - } - } - } -} -``` - -This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`. - -A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. - -In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`: ---- -layout: default -title: Document-level security -parent: Access control -nav_order: 85 redirect_from: - /security/access-control/document-level-security/ - /security-plugin/access-control/document-level-security/ @@ -48,7 +10,7 @@ redirect_from: # Document-level security (DLS) -Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section. +Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section. ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) @@ -319,7 +281,7 @@ redirect_from: # Document-level security (DLS) -Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section. +Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index pPermissions** section. ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) From de1ef92ff732f944e8f045ab300492cca8a03bc5 Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Wed, 27 Mar 2024 16:20:53 +0000 Subject: [PATCH 04/14] adding back the first 2 sections Signed-off-by: leanne.laceybyrne@eliatra.com --- _api-reference/document-apis/index-document.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index 046522e25e..c829121ed4 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -11,7 +11,17 @@ redirect_from: **Introduced 1.0** {: .label .label-purple} -Through the use of HTTP methods, we can interact with the data in our database. +Before you can search for data, you must first add documents. This operation adds a single document to your index. + +## Example + +```json +PUT sample-index/_doc/1 +{ + "Description": "To be or not to be, that is the question." +} +``` +{% include copy-curl.html %} ## Path and HTTP methods @@ -22,6 +32,7 @@ POST /_doc PUT /_create/<_id> POST /_create/<_id> ``` + - PUT adds or updates documents with a specified ID in the index. Used for controlled document creation or updates. - POST adds documents to the index with auto-generated IDs. Useful for adding new documents without specifying IDs. - `_create` is a type identifier indicating document creation should only occur if the document with the specified ID doesn't already exist. @@ -35,7 +46,7 @@ To do this follow the steps: 1. Open OpenSearch Dashboards 2. Navigate to the hamburger menu 3. In the **Management** section, choose **Dev Tools** -4. Run the following commands in the dev tools by pressing the green triangle play button to send the request. +4. Run the following commands in the Dev tools by pressing the green triangle play button to send the request. ### Create a sample-index ```json From 3bf64672cd1768ae478f811ec1c133b8afd13b47 Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Wed, 27 Mar 2024 16:25:53 +0000 Subject: [PATCH 05/14] fixing formatting Signed-off-by: leanne.laceybyrne@eliatra.com --- .../access-control/document-level-security.md | 524 ------------------ 1 file changed, 524 deletions(-) diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index 4f45315aa1..9c47227e5b 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -127,530 +127,6 @@ Term | Replaced with `${attr..}` | An attribute with name `` defined for a user. `` is `internal`, `jwt`, `proxy` or `ldap` -## Attribute-based security - -You can use roles and parameter substitution with the `terms_set` query to enable attribute-based security. - -> Note that the `security_attributes` of the index need to be of type `keyword`. - -#### User definition - -```json -PUT _plugins/_security/api/internalusers/user1 -{ - "password": "asdf", - "backend_roles": ["abac"], - "attributes": { - "permissions": "\"att1\", \"att2\", \"att3\"" - } -} -``` - -#### Role definition - -```json -PUT _plugins/_security/api/roles/abac -{ - "index_permissions": [{ - "index_patterns": [ - "*" - ], - "dls": "{\"terms_set\": {\"security_attributes\": {\"terms\": [${attr.internal.permissions}], \"minimum_should_match_script\": {\"source\": \"doc['security_attributes'].length\"}}}}", - "allowed_actions": [ - "read" - ] - }] -} -``` -## Use term-level lookup queries (TLQs) with DLS - -You can perform term-level lookup queries (TLQs) with document-level security (DLS) using either of two modes: adaptive or filter level. The default mode is adaptive, where OpenSearch automatically switches between Lucene-level or filter-level mode depending on whether or not there is a TLQ. DLS queries without TLQs are executed in Lucene-level mode, whereas DLS queries with TLQs are executed in filter-level mode. - -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]({{site.url}}{{site.baseurl}}/query-dsl/term/index/). - -### How to set the DLS evaluation mode in `opensearch.yml` - -By default, the DLS evaluation mode is set to `adaptive`. You can also explicitly set the mode in `opensearch.yml` with the `plugins.security.dls.mode` setting. Add a line to `opensearch.yml` with the desired evaluation mode. -For example, to set it to filter level, add this line: -``` -plugins.security.dls.mode: filter-level -``` - -#### DLS evaluation modes - -| Evaluation mode | Parameter | Description | Usage | -:--- | :--- | :--- | :--- | -Lucene-level DLS | `lucene-level` | This setting makes all DLS queries apply to the Lucene level. | Lucene-level DLS modifies Lucene queries and data structures directly. This is the most efficient mode but does not allow certain advanced constructs in DLS queries, including TLQs. -Filter-level DLS | `filter-level` | This setting makes all DLS queries apply to the filter level. | In this mode, OpenSearch applies DLS by modifying queries that OpenSearch receives. This allows for term-level lookup queries in DLS queries, but you can only use the `get`, `search`, `mget`, and `msearch` operations to retrieve data from the protected index. Additionally, cross-cluster searches are limited with this mode. -Adaptive | `adaptive-level` | The default setting that allows OpenSearch to automatically choose the mode. | DLS queries without TLQs are executed in Lucene-level mode, while DLS queries that contain TLQ are executed in filter- level mode. - -## DLS and multiple roles - -OpenSearch combines all DLS queries with the logical `OR` operator. However, when a role that uses DLS is combined with another security role that doesn't use DLS, the query results are filtered to display only documents matching the DLS from the first role. This filter rule also applies to roles that do not grant read documents. - -### When to enable `plugins.security.dfm_empty_overrides_all` - -When to enable the `plugins.security.dfm_empty_overrides_all` setting depends on whether you want to restrict user access to documents without DLS. - - -To ensure access is not restricted, you can set the following configuration in `opensearch.yml`: - -``` -plugins.security.dfm_empty_overrides_all: true -``` -{% include copy.html %} - - -The following examples show what level of access roles with DLS enabled and without DLS enabled, depending on the interaction. These examples can help you decide when to enable the `plugins.security.dfm_empty_overrides_all` setting. - -#### Example: Document access - -This example demonstrates that enabling `plugins.security.dfm_empty_overrides_all` is beneficial in scenarios where you need specific users to have unrestricted access to documents despite being part of a broader group with restricted access. - -**Role A with DLS**: This role is granted to a broad group of users and includes DLS to restrict access to specific documents, as shown in the following permission set: - -``` -{ - "index_permissions": [ - { - "index_patterns": ["example-index"], - "dls": "[.. some DLS here ..]", - "allowed_actions": ["indices:data/read/search"] - } - ] -} -``` - -**Role B without DLS:** This role is specifically granted to certain users, such as administrators, and does not include DLS, as shown in the following permission set: - -``` -{ - "index_permissions" : [ - { - "index_patterns" : ["*"], - "allowed_actions" : ["indices:data/read/search"] - } - ] -} -``` -{% include copy.html %} - -Setting `plugins.security.dfm_empty_overrides_all` to `true` ensures that administrators assigned Role B can override any DLS restrictions imposed by Role A. This allows specific Role B users to access all documents, regardless of the restrictions applied by Role A's DLS restrictions. - -#### Example: Search template access - -In this example, two roles are defined, one with DLS and another without DLS, granting access to search templates: - -**Role A with DLS:** - -``` -{ - "index_permissions": [ - { - "index_patterns": [ - "example-index" - ], - "dls": "[.. some DLS here ..]", - "allowed_actions": [ - "indices:data/read/search", - ] - } - ] -} -``` -{% include copy.html %} - -**Role B, without DLS**, which only grants access to search templates: - -``` -{ - "index_permissions" : [ - { - "index_patterns" : [ "*" ], - "allowed_actions" : [ "indices:data/read/search/template" ]--- -layout: default -title: Document-level security -parent: Access control -nav_order: 85 -redirect_from: -- /security/access-control/document-level-security/ -- /security-plugin/access-control/document-level-security/ ---- - -# Document-level security (DLS) - -Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index pPermissions** section. - -![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) - - -## Simple roles - -Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document level security** section: - -```json -{ - "bool": { - "must": { - "match": { - "genres": "Comedy" - } - } - } -} -``` - -This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`. - -A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. - -In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`: - -```json -PUT _plugins/_security/api/roles/public_data -{ - "cluster_permissions": [ - "*" - ], - "index_permissions": [{ - "index_patterns": [ - "pub*" - ], - "dls": "{\"term\": { \"public\": true}}", - "allowed_actions": [ - "read" - ] - }] -} -``` - -These queries can be as complex as you want, but we recommend keeping them simple to minimize the performance impact that the document-level security feature has on the cluster. -{: .warning } - -### 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]({{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: - -```json -{ - "bool": { - "must": { - "match": { - "user.id": "User-1" - } - } - } -} -``` - -```json -{ - "bool": { - "must": { - "match": { - "user.id": "User-2" - } - } - } -} -``` - -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). - - -## Parameter substitution - -A number of variables exist that you can use to enforce rules based on the properties of a user. For example, `${user.name}` is replaced with the name of the current user. - -This rule allows a user to read any document where the username is a value of the `readable_by` field: - -```json -PUT _plugins/_security/api/roles/user_data -{ - "cluster_permissions": [ - "*" - ], - "index_permissions": [{ - "index_patterns": [ - "pub*" - ], - "dls": "{\"term\": { \"readable_by\": \"${user.name}\"}}", - "allowed_actions": [ - "read" - ] - }] -} -``` - -This table lists substitutions. - -Term | Replaced with -:--- | :--- -`${user.name}` | Username. -`${user.roles}` | A comma-separated, quoted list of user backend roles. -`${user.securityRoles}` | A comma-separated, quoted list of user security roles. -`${attr..}` | An attribute with name `` defined for a user. `` is `internal`, `jwt`, `proxy` or `ldap` - - -## Attribute-based security - -You can use roles and parameter substitution with the `terms_set` query to enable attribute-based security. - -> Note that the `security_attributes` of the index need to be of type `keyword`. - -#### User definition - -```json -PUT _plugins/_security/api/internalusers/user1 -{ - "password": "asdf", - "backend_roles": ["abac"], - "attributes": { - "permissions": "\"att1\", \"att2\", \"att3\"" - } -} -``` - -#### Role definition - -```json -PUT _plugins/_security/api/roles/abac -{ - "index_permissions": [{ - "index_patterns": [ - "*" - ], - "dls": "{\"terms_set\": {\"security_attributes\": {\"terms\": [${attr.internal.permissions}], \"minimum_should_match_script\": {\"source\": \"doc['security_attributes'].length\"}}}}", - "allowed_actions": [ - "read" - ] - }] -} -``` -## Use term-level lookup queries (TLQs) with DLS - -You can perform term-level lookup queries (TLQs) with document-level security (DLS) using either of two modes: adaptive or filter level. The default mode is adaptive, where OpenSearch automatically switches between Lucene-level or filter-level mode depending on whether or not there is a TLQ. DLS queries without TLQs are executed in Lucene-level mode, whereas DLS queries with TLQs are executed in filter-level mode. - -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]({{site.url}}{{site.baseurl}}/query-dsl/term/index/). - -### How to set the DLS evaluation mode in `opensearch.yml` - -By default, the DLS evaluation mode is set to `adaptive`. You can also explicitly set the mode in `opensearch.yml` with the `plugins.security.dls.mode` setting. Add a line to `opensearch.yml` with the desired evaluation mode. -For example, to set it to filter level, add this line: -``` -plugins.security.dls.mode: filter-level -``` - -#### DLS evaluation modes - -| Evaluation mode | Parameter | Description | Usage | -:--- | :--- | :--- | :--- | -Lucene-level DLS | `lucene-level` | This setting makes all DLS queries apply to the Lucene level. | Lucene-level DLS modifies Lucene queries and data structures directly. This is the most efficient mode but does not allow certain advanced constructs in DLS queries, including TLQs. -Filter-level DLS | `filter-level` | This setting makes all DLS queries apply to the filter level. | In this mode, OpenSearch applies DLS by modifying queries that OpenSearch receives. This allows for term-level lookup queries in DLS queries, but you can only use the `get`, `search`, `mget`, and `msearch` operations to retrieve data from the protected index. Additionally, cross-cluster searches are limited with this mode. -Adaptive | `adaptive-level` | The default setting that allows OpenSearch to automatically choose the mode. | DLS queries without TLQs are executed in Lucene-level mode, while DLS queries that contain TLQ are executed in filter- level mode. - -## DLS and multiple roles - -OpenSearch combines all DLS queries with the logical `OR` operator. However, when a role that uses DLS is combined with another security role that doesn't use DLS, the query results are filtered to display only documents matching the DLS from the first role. This filter rule also applies to roles that do not grant read documents. - -### When to enable `plugins.security.dfm_empty_overrides_all` - -When to enable the `plugins.security.dfm_empty_overrides_all` setting depends on whether you want to restrict user access to documents without DLS. - - -To ensure access is not restricted, you can set the following configuration in `opensearch.yml`: - -``` -plugins.security.dfm_empty_overrides_all: true -``` -{% include copy.html %} - - -The following examples show what level of access roles with DLS enabled and without DLS enabled, depending on the interaction. These examples can help you decide when to enable the `plugins.security.dfm_empty_overrides_all` setting. - -#### Example: Document access - -This example demonstrates that enabling `plugins.security.dfm_empty_overrides_all` is beneficial in scenarios where you need specific users to have unrestricted access to documents despite being part of a broader group with restricted access. - -**Role A with DLS**: This role is granted to a broad group of users and includes DLS to restrict access to specific documents, as shown in the following permission set: - -``` -{ - "index_permissions": [ - { - "index_patterns": ["example-index"], - "dls": "[.. some DLS here ..]", - "allowed_actions": ["indices:data/read/search"] - } - ] -} -``` - -**Role B without DLS:** This role is specifically granted to certain users, such as administrators, and does not include DLS, as shown in the following permission set: - -``` -{ - "index_permissions" : [ - { - "index_patterns" : ["*"], - "allowed_actions" : ["indices:data/read/search"] - } - ] -} -``` -{% include copy.html %} - -Setting `plugins.security.dfm_empty_overrides_all` to `true` ensures that administrators assigned Role B can override any DLS restrictions imposed by Role A. This allows specific Role B users to access all documents, regardless of the restrictions applied by Role A's DLS restrictions. - -#### Example: Search template access - -In this example, two roles are defined, one with DLS and another without DLS, granting access to search templates: - -**Role A with DLS:** - -``` -{ - "index_permissions": [ - { - "index_patterns": [ - "example-index" - ], - "dls": "[.. some DLS here ..]", - "allowed_actions": [ - "indices:data/read/search", - ] - } - ] -} -``` -{% include copy.html %} - -**Role B, without DLS**, which only grants access to search templates: - -``` -{ - "index_permissions" : [ - { - "index_patterns" : [ "*" ], - "allowed_actions" : [ "indices:data/read/search/template" ] - } - ] -} -``` -{% include copy.html %} - -When a user has both Role A and Role B permissions, the query results are filtered based on Role A's DLS, even though Role B doesn't use DLS. The DLS settings are retained, and the returned access is appropriately restricted. - -When a user is assigned both Role A and Role B and the `plugins.security.dfm_empty_overrides_all` setting is enabled, Role B's permissions Role B's permissions will override Role A's restrictions, allowing that user to access all documents. This ensures that the role without DLS takes precedence in the search query response. - - } - ] -} -``` -{% include copy.html %} - -When a user has both Role A and Role B permissions, the query results are filtered based on Role A's DLS, even though Role B doesn't use DLS. The DLS settings are retained, and the returned access is appropriately restricted. - -When a user is assigned both Role A and Role B and the `plugins.security.dfm_empty_overrides_all` setting is enabled, Role B's permissions Role B's permissions will override Role A's restrictions, allowing that user to access all documents. This ensures that the role without DLS takes precedence in the search query response. - -```json -PUT _plugins/_security/api/roles/public_data -{ - "cluster_permissions": [ - "*" - ], - "index_permissions": [{ - "index_patterns": [ - "pub*" - ], - "dls": "{\"term\": { \"public\": true}}", - "allowed_actions": [ - "read" - ] - }] -} -``` - -These queries can be as complex as you want, but we recommend keeping them simple to minimize the performance impact that the document-level security feature has on the cluster. -{: .warning } - -### 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]({{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: - -```json -{ - "bool": { - "must": { - "match": { - "user.id": "User-1" - } - } - } -} -``` - -```json -{ - "bool": { - "must": { - "match": { - "user.id": "User-2" - } - } - } -} -``` - -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). - - -## Parameter substitution - -A number of variables exist that you can use to enforce rules based on the properties of a user. For example, `${user.name}` is replaced with the name of the current user. - -This rule allows a user to read any document where the username is a value of the `readable_by` field: - -```json -PUT _plugins/_security/api/roles/user_data -{ - "cluster_permissions": [ - "*" - ], - "index_permissions": [{ - "index_patterns": [ - "pub*" - ], - "dls": "{\"term\": { \"readable_by\": \"${user.name}\"}}", - "allowed_actions": [ - "read" - ] - }] -} -``` - -This table lists substitutions. - -Term | Replaced with -:--- | :--- -`${user.name}` | Username. -`${user.roles}` | A comma-separated, quoted list of user backend roles. -`${user.securityRoles}` | A comma-separated, quoted list of user security roles. -`${attr..}` | An attribute with name `` defined for a user. `` is `internal`, `jwt`, `proxy` or `ldap` - - ## Attribute-based security You can use roles and parameter substitution with the `terms_set` query to enable attribute-based security. From 17408cd24622a7e523453a1d3668d3b9a91a57b2 Mon Sep 17 00:00:00 2001 From: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Date: Fri, 29 Mar 2024 10:10:43 +0000 Subject: [PATCH 06/14] Apply suggestions from code review Co-authored-by: Heather Halter Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --- _api-reference/document-apis/index-document.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index c829121ed4..46d0d9b621 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -41,12 +41,12 @@ POST /_create/<_id> ## Adding a sample index and documents to use the HTTP methods -Before you can search for data, you must first add documents. +To add a documents, do the following: To do this follow the steps: -1. Open OpenSearch Dashboards -2. Navigate to the hamburger menu -3. In the **Management** section, choose **Dev Tools** -4. Run the following commands in the Dev tools by pressing the green triangle play button to send the request. +1. Open OpenSearch Dashboards. +2. Navigate to the hamburger menu. +3. In the **Management** section, choose **Dev Tools**. +4. Enter a command, then press the green triangle play button to send the request. Some example commands follow. ### Create a sample-index ```json From 871c74b8b5a970abe94175d8845f9b050e92a4a9 Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Fri, 29 Mar 2024 15:22:57 +0000 Subject: [PATCH 07/14] updated introduction scentance Signed-off-by: leanne.laceybyrne@eliatra.com --- _api-reference/document-apis/index-document.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index 46d0d9b621..11ad518b8e 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -11,7 +11,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple} -Before you can search for data, you must first add documents. This operation adds a single document to your index. +You can use the Index document operation to add a single document to your index. ## Example From 3fc8d048a75206734938220d86cca3d2346668a4 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 29 Mar 2024 14:14:31 -0500 Subject: [PATCH 08/14] Update _api-reference/document-apis/index-document.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/document-apis/index-document.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index 11ad518b8e..97cc06911c 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -41,7 +41,7 @@ POST /_create/<_id> ## Adding a sample index and documents to use the HTTP methods -To add a documents, do the following: +If you want to quickly test the Document APIs, you can quickly add a document by doing the following: To do this follow the steps: 1. Open OpenSearch Dashboards. 2. Navigate to the hamburger menu. From 8a2155624a5dddef45f6b7b53b40a0c84ef1bb79 Mon Sep 17 00:00:00 2001 From: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Date: Tue, 2 Apr 2024 13:05:51 +0100 Subject: [PATCH 09/14] Update index-document.md Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --- _api-reference/document-apis/index-document.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index 97cc06911c..ba91a38ee0 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -41,8 +41,7 @@ POST /_create/<_id> ## Adding a sample index and documents to use the HTTP methods -If you want to quickly test the Document APIs, you can quickly add a document by doing the following: -To do this follow the steps: +To test the Document APIs, add a document by following the steps: 1. Open OpenSearch Dashboards. 2. Navigate to the hamburger menu. 3. In the **Management** section, choose **Dev Tools**. From ca262ff56094f1e8135f67d6075c64e7a510c075 Mon Sep 17 00:00:00 2001 From: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Date: Thu, 4 Apr 2024 18:11:29 +0100 Subject: [PATCH 10/14] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --- _api-reference/document-apis/index-document.md | 14 +++++++------- .../access-control/document-level-security.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index ba91a38ee0..f83cf51141 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -11,7 +11,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple} -You can use the Index document operation to add a single document to your index. +You can use the index document operation to add a single document to your index. ## Example @@ -33,19 +33,19 @@ PUT /_create/<_id> POST /_create/<_id> ``` -- PUT adds or updates documents with a specified ID in the index. Used for controlled document creation or updates. -- POST adds documents to the index with auto-generated IDs. Useful for adding new documents without specifying IDs. -- `_create` is a type identifier indicating document creation should only occur if the document with the specified ID doesn't already exist. -- `` represents the name of the index where the document will be added. +- PUT adds or updates documents in the index with a specified ID. Used for controlled document creation or updates. +- POST adds documents with auto-generated IDs to the index. Useful for adding new documents without specifying IDs. +- `_create` is a type identifier indicating that document creation should only occur if the document with the specified ID doesn't already exist. +- `` represents the name of the index to which the document will be added. - `<_id>` represents the unique identifier of the document. ## Adding a sample index and documents to use the HTTP methods -To test the Document APIs, add a document by following the steps: +To test the Document APIs, add a document by following these steps: 1. Open OpenSearch Dashboards. 2. Navigate to the hamburger menu. 3. In the **Management** section, choose **Dev Tools**. -4. Enter a command, then press the green triangle play button to send the request. Some example commands follow. +4. Enter a command, and then select the green triangle play button to send the request. The following are some example commands. ### Create a sample-index ```json diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index 2f439335b5..0d0d7174d3 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -8,7 +8,7 @@ redirect_from: - /security-plugin/access-control/document-level-security/ --- -# Document-level security (DLS) +# Document-level security Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section. ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) @@ -16,7 +16,7 @@ Document-level security lets you restrict a role to a subset of documents in an ## Simple roles -Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document level security** section: +Document-level security uses OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document-level security** section: ```json { From 733c177581ac3b8db670692673b607555fdd007c Mon Sep 17 00:00:00 2001 From: "leanne.laceybyrne@eliatra.com" Date: Thu, 4 Apr 2024 19:12:39 +0100 Subject: [PATCH 11/14] addressing review comments and editorial review Signed-off-by: leanne.laceybyrne@eliatra.com --- _api-reference/document-apis/index-document.md | 11 ++++++----- _security/access-control/document-level-security.md | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index f83cf51141..f6e02021f0 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -11,7 +11,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple} -You can use the index document operation to add a single document to your index. +You can use the `Index document` operation to add a single document to your index. ## Example @@ -39,11 +39,13 @@ POST /_create/<_id> - `` represents the name of the index to which the document will be added. - `<_id>` represents the unique identifier of the document. -## Adding a sample index and documents to use the HTTP methods +## Adding a sample index -To test the Document APIs, add a document by following these steps: +Sample data can be added to the index with curl commands in the terminal, or through the API. + +To test the Document APIs, add a document by following the steps: 1. Open OpenSearch Dashboards. -2. Navigate to the hamburger menu. +2. Navigate to the actions menu. 3. In the **Management** section, choose **Dev Tools**. 4. Enter a command, and then select the green triangle play button to send the request. The following are some example commands. @@ -78,7 +80,6 @@ POST /sample_index/_doc ``` {% include copy-curl.html %} - ## URL parameters In your request, you must specify the index you want to add your document to. If the index doesn't already exist, OpenSearch automatically creates the index and adds in your document. All other URL parameters are optional. diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index 0d0d7174d3..4e6d8692ae 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -9,7 +9,7 @@ redirect_from: --- # Document-level security -Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section. +Document-level security (DLS) lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section. See the Index Permissions section in OpenSearch Dashboards in the following image. ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) From 17162a957e3df6a7589772d3af7c9e5e88cad5ba Mon Sep 17 00:00:00 2001 From: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Date: Fri, 5 Apr 2024 16:22:53 +0100 Subject: [PATCH 12/14] Update _security/access-control/document-level-security.md Co-authored-by: Nathan Bower Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --- _security/access-control/document-level-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index 4e6d8692ae..d9f8fe3ebb 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -32,7 +32,7 @@ Document-level security uses OpenSearch query DSL to define which documents a ro This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`. -A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. +A typical request sent to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. ## Updating roles by accessing the REST API From feb2735dbb5dbfebb97b2f14620abaf6bab287fc Mon Sep 17 00:00:00 2001 From: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Date: Fri, 5 Apr 2024 16:23:03 +0100 Subject: [PATCH 13/14] Update _security/access-control/document-level-security.md Co-authored-by: Nathan Bower Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --- _security/access-control/document-level-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index d9f8fe3ebb..1145e8070d 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -16,7 +16,7 @@ Document-level security (DLS) lets you restrict a role to a subset of documents ## Simple roles -Document-level security uses OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document-level security** section: +Document-level security uses OpenSearch query domain-specific language (DSL) to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document-level security** section: ```json { From 7e430b27957a915f2f0ce91ffe670b530de77b0c Mon Sep 17 00:00:00 2001 From: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Date: Fri, 5 Apr 2024 16:23:34 +0100 Subject: [PATCH 14/14] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --- _api-reference/document-apis/index-document.md | 4 ++-- _security/access-control/document-level-security.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index f6e02021f0..3460fc1d50 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -41,9 +41,9 @@ POST /_create/<_id> ## Adding a sample index -Sample data can be added to the index with curl commands in the terminal, or through the API. +Sample data can be added to the index with curl commands in the terminal or through the API. -To test the Document APIs, add a document by following the steps: +To test the Document APIs, add a document by following these steps: 1. Open OpenSearch Dashboards. 2. Navigate to the actions menu. 3. In the **Management** section, choose **Dev Tools**. diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index 1145e8070d..08de85bbf7 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -9,7 +9,7 @@ redirect_from: --- # Document-level security -Document-level security (DLS) lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section. See the Index Permissions section in OpenSearch Dashboards in the following image. +Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section, shown in the following image. ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png)