Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addition of full file paths in security documentation #8113

Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ nav_order: 40

The Security plugin provides a number of YAML configuration files that are used to store the necessary settings that define the way the Security plugin manages users, roles, and activity within the cluster. For a full list of the Security plugin configuration files, see [Modifying the YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/).

The following sections describe security-related settings in `opensearch.yml`. To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/).
The following sections describe security-related settings in `opensearch.yml`, typically found at `/path/to/opensearch-{{site.opensearch_version}}/config/opensearch.yml`. To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/).
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

## Common settings

Expand Down
2 changes: 1 addition & 1 deletion _security/configuration/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,4 @@ The Security plugin has several default users, roles, action groups, permissions
{: .note }

For a full list of `opensearch.yml` Security plugin settings, Security plugin settings, see [Security settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/security-settings/).
{: .note}
{: .note}
4 changes: 2 additions & 2 deletions _security/configuration/security-admin.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,13 @@ The `securityadmin.sh` script requires SSL/TLS HTTP to be enabled for your OpenS

## A word of caution

If you make changes to the configuration files in `config/opensearch-security`, OpenSearch does _not_ automatically apply these changes. Instead, you must run `securityadmin.sh` to load the updated files into the index.
If you make changes to the configuration files in `config/opensearch-security`, OpenSearch does _not_ automatically apply these changes. Instead, you must run `securityadmin.sh` to load the updated files into the index. The `securityadmin.sh` file can typically be found at `<OPENSEARCH_HOME>/plugins/opensearch-security/tools/securityadmin.[sh|bat]`
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

Running `securityadmin.sh` **overwrites** one or more portions of the `.opendistro_security` index. Run it with extreme care to avoid losing your existing resources. Consider the following example:

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/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` (Typically found at `<OPENSEARCH_HOME>/config/opensearch-security/internal_users.yml`)
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
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.

Expand Down
13 changes: 6 additions & 7 deletions _security/configuration/yaml.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,7 @@ The approach we recommend for using the YAML files is to first configure [reserv


## internal_users.yml

This file contains any initial users that you want to add to the Security plugin's internal user database.
Typically found at `<OPENSEARCH_HOME>/config/opensearch-security/internal_users.yml`, this file contains any initial users that you want to add to the Security plugin's internal user database.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

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.

Expand Down Expand Up @@ -93,8 +92,7 @@ snapshotrestore:
```

## opensearch.yml

In addition to many OpenSearch settings, this file contains paths to TLS certificates and their attributes, such as distinguished names and trusted certificate authorities.
Typically found at `<OPENSEARCH_HOME>/config/opensearch.yml`. In addition to many OpenSearch settings, this file contains paths to TLS certificates and their attributes, such as distinguished names and trusted certificate authorities.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```yml
plugins.security.ssl.transport.pemcert_filepath: esnode.pem
Expand Down Expand Up @@ -196,8 +194,7 @@ The following example shows the response from the [Create user]({{site.url}}{{si
```

## allowlist.yml

You can use `allowlist.yml` to add any endpoints and HTTP requests to a list of allowed endpoints and requests. If enabled, all users except the super admin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is added to the allow list, users cannot submit PUT requests to `_cluster/settings` to update cluster settings.
Typically found at `<OPENSEARCH_HOME>/config/opensearch-security/allowlist.yml`, this file can be used to add any endpoints and HTTP requests to a list of allowed endpoints and requests. If enabled, all users except the super admin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is added to the allow list, users cannot submit PUT requests to `_cluster/settings` to update cluster settings.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

Note that while you can configure access to endpoints this way, for most cases, it is still best to configure permissions using the Security plugin's users and roles, which have more granular settings.

Expand Down Expand Up @@ -249,7 +246,7 @@ requests: # Only allow GET requests to /sample-index1/_doc/1 and /sample-index2/

## roles.yml

This file contains any initial roles that you want to add to the Security plugin. Aside from some metadata, the default file is empty, because the Security plugin has a number of static roles that it adds automatically.
Typically found at `<OPENSEARCH_HOME>/config/opensearch-security/roles.yml`, this file contains any initial roles that you want to add to the Security plugin. Aside from some metadata, the default file is empty, because the Security plugin has a number of static roles that it adds automatically.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```yml
---
Expand Down Expand Up @@ -284,6 +281,8 @@ _meta:

## roles_mapping.yml

Typically found at `<OPENSEARCH_HOME>/config/opensearch-security/roles_mapping.yml`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file contains any role mappings required for your security configuration. You can find the role_mapping.yml file in <OPENSEARCH_HOME>/config/opensearch-security/roles_mapping.yml.

Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```yml
---
manage_snapshots:
Expand Down
Loading