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

Adds documentation for permission that provides access to system indexes #4849

Merged
merged 25 commits into from
Sep 11, 2023

Conversation

cwillum
Copy link
Contributor

@cwillum cwillum commented Aug 22, 2023

Description

Document a new permission that allows normal users to modify system indexes.

Issues Resolved

Documents the new permission and the setting that enables or disables its functionality.

Fixes #4736

Checklist

  • By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
    For more information on following Developer Certificate of Origin and signing off your commits, please check here.

@cwillum cwillum added 2 - In progress Issue/PR: The issue or PR is in progress. security release-notes PR: Include this PR in the automated release notes v2.10.0 labels Aug 22, 2023
@cwillum cwillum self-assigned this Aug 22, 2023
Copy link
Member

@DarshitChanpura DarshitChanpura left a comment

Choose a reason for hiding this comment

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

Thanks for putting this PR together @cwillum. Left some comments around the permission name

@@ -65,6 +65,16 @@ Rather than individual permissions, you can often achieve your desired security
{: .tip }


### System permission

The system permission `system:admin/system_index` is unique among other permissions in that it extends some traditional admin-only accessibility to non-admin users. This permission gives normal users the ability to modify system indexes for the cluster. It excludes, however, access to the security system index `.opendistro_security`, which is used to store the configuration YAML files and remains accessible only to admins with an admin certificate.
Copy link
Member

Choose a reason for hiding this comment

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

This sounds like the permission itself is system:admin/system_index however system_index here is actually a placeholder text that should be replaced by the actual name of the system index i.e. system:admin/.opendistro-anomaly-detectors

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks for pointing this out. I didn't pick this up from my review of materials.


The system permission `system:admin/system_index` is unique among other permissions in that it extends some traditional admin-only accessibility to non-admin users. This permission gives normal users the ability to modify system indexes for the cluster. It excludes, however, access to the security system index `.opendistro_security`, which is used to store the configuration YAML files and remains accessible only to admins with an admin certificate.

Admin users that have the permission `restapi:admin/roles` are able to map the `system:admin/system_index` permission to users just as they would for a cluster or index permission. However, to preserve some control over this permission, the configuration setting `plugins.security.system_indices.additional_control.enabled` allows administrators to disable this permission by setting it to `false`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).
Copy link
Member

Choose a reason for hiding this comment

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

nit: ... disable this feature ... . Thoughts?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Agreed.


Admin users that have the permission `restapi:admin/roles` are able to map the `system:admin/system_index` permission to users just as they would for a cluster or index permission. However, to preserve some control over this permission, the configuration setting `plugins.security.system_indices.additional_control.enabled` allows administrators to disable this permission by setting it to `false`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).

Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health.
Copy link
Member

Choose a reason for hiding this comment

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

We should also mention that users with permission to modify roles restapi:admin/roles can essentially grant themselves or any other user in cluster access to system indices. However, these permissions will have to be individually granted. They cannot be granted as a * permission. i.e. system:admin/* is not a valid permission.

Also, .opendistro_security index is not permission-able.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Right, covered both these points in current text. Thanks

Copy link
Contributor Author

@cwillum cwillum left a comment

Choose a reason for hiding this comment

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

@DarshitChanpura Thanks for the early review. I've addressed your comments. I'll wait to circulate this for documentation team review until Security confirms this is going into 2.10.

@@ -65,6 +65,16 @@ Rather than individual permissions, you can often achieve your desired security
{: .tip }


### System permission

The system permission `system:admin/system_index` is unique among other permissions in that it extends some traditional admin-only accessibility to non-admin users. This permission gives normal users the ability to modify system indexes for the cluster. It excludes, however, access to the security system index `.opendistro_security`, which is used to store the configuration YAML files and remains accessible only to admins with an admin certificate.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks for pointing this out. I didn't pick this up from my review of materials.


The system permission `system:admin/system_index` is unique among other permissions in that it extends some traditional admin-only accessibility to non-admin users. This permission gives normal users the ability to modify system indexes for the cluster. It excludes, however, access to the security system index `.opendistro_security`, which is used to store the configuration YAML files and remains accessible only to admins with an admin certificate.

Admin users that have the permission `restapi:admin/roles` are able to map the `system:admin/system_index` permission to users just as they would for a cluster or index permission. However, to preserve some control over this permission, the configuration setting `plugins.security.system_indices.additional_control.enabled` allows administrators to disable this permission by setting it to `false`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Agreed.


Admin users that have the permission `restapi:admin/roles` are able to map the `system:admin/system_index` permission to users just as they would for a cluster or index permission. However, to preserve some control over this permission, the configuration setting `plugins.security.system_indices.additional_control.enabled` allows administrators to disable this permission by setting it to `false`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).

Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Right, covered both these points in current text. Thanks

Copy link
Member

@DarshitChanpura DarshitChanpura left a comment

Choose a reason for hiding this comment

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

Hey @cwillum I apologize for confusion around system index permission setup. I've added some comments that hopefully clarify the feature.

_security/access-control/permissions.md Show resolved Hide resolved
```yml
plugins.security.system_indices.additional_control.enabled: true
```
When set to `false`, the permission is disabled and only admins with an admin certificate can make changes to system indexes. By default, the setting is `true` for a new cluster.
Copy link
Member

Choose a reason for hiding this comment

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

```
When set to `false`, the permission is disabled and only admins with an admin certificate can make changes to system indexes. By default, the setting is `true` for a new cluster.

To learn more about the `system:admin/<system_index_name>` permission, see [System permission]({{site.url}}{{site.baseurl}}/security/access-control/permissions/#system-permission).
Copy link
Member

Choose a reason for hiding this comment

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

Thoughts on: To learn more about the System Index Permissions, see ..


The system permission `system:admin/<system_index_name>` is unique among other permissions in that it extends some traditional admin-only accessibility to non-admin users. This permission gives normal users the ability to modify the system index specified in the permission name. For example, the permission `system:admin/.opendistro-alerting-config` gives a user permission to modify the system index that stores configurations for the Alerting plugin.

The system permission excludes, however, access to the security system index `.opendistro_security`, which is used to store Security's configuration YAML files and remains accessible only to admins with an admin certificate.
Copy link
Member

@DarshitChanpura DarshitChanpura Aug 25, 2023

Choose a reason for hiding this comment

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

Thoughts on: "The system permission, however, excludes access to the .opendistro_security system index, which stores the Security plugin's configuration, and is only accessible to admins with an admin certificate."

Copy link
Contributor Author

@cwillum cwillum left a comment

Choose a reason for hiding this comment

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

@DarshitChanpura Thanks for reviewing this part way through. I've addressed the comments. Please have another look when you get a chance. As always, thank you.

_security/access-control/permissions.md Show resolved Hide resolved
Copy link
Contributor Author

@cwillum cwillum left a comment

Choose a reason for hiding this comment

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

@peternied Thanks for the review. I've addressed your comments. Will wait to push this along further until I get word from Security that the feature is merged.


* Specifying the full name of a system index limits access to that index alone: `.opendistro-alerting-config`.
* Specifying the prefix and a partial name for a system index provides access to all system indexes that begin with the name: `.opendistro-anomaly-detector*`.
* Using `.*` is effectively the same as specifying the prefix with wildcard, as described in the previous point. This gives access to all system indexes that begin with a `.`.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@peternied Thanks for pointing this out. I've reworded the points above to bring guidance in line with this clarification. Is the additional wildcard necessary under allowed_actions only when you want to specify all system indexes under index_patterns?
One other nitpick. Are values for this configuration wrapped in single quotes or double quotes? Or doesn't it matter? I've seen both.

* Using `.*` is effectively the same as specifying the prefix with wildcard, as described in the previous point. This gives access to all system indexes that begin with a `.`.
* Entering the wildcard `*` by itself does not give access to any indexes.

Use extreme caution when using the wildcard to configure access to system indexes. We highly recommend thinking ahead and anticipating the range of access that you will be extending to users before updating your configuration files.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@peternied Good perspective on that. I removed that caution (seemed redundant, anyhow) and replaced it with a "tip" about using the GET /_cat/indices/<index> operation to verify your index pattern. Thank you for that.

@DarshitChanpura
Copy link
Member

DarshitChanpura commented Sep 6, 2023

@cwillum There have been changes in the feature flag name. I've addresses those here: https://github.com/opensearch-project/documentation-website/pull/4953/files. Please review it

* Changes the feature flag key and updates description of a consideration

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses source PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

---------

Signed-off-by: Darshit Chanpura <[email protected]>
Copy link
Member

@DarshitChanpura DarshitChanpura left a comment

Choose a reason for hiding this comment

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

all updates have been addressed. LGTM!

@DarshitChanpura
Copy link
Member

Security PR is merged: opensearch-project/security#3325

@cwillum cwillum added 5 - Editorial review PR: Editorial review in progress and removed 4 - Doc review PR: Doc review in progress labels Sep 7, 2023
Copy link
Collaborator

@natebower natebower left a comment

Choose a reason for hiding this comment

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

@cwillum Please see my comments and changes and let me know when addressed so that I can read again and approve. Thanks!

_security/access-control/permissions.md Outdated Show resolved Hide resolved
_security/access-control/permissions.md Outdated Show resolved Hide resolved
_security/access-control/permissions.md Outdated Show resolved Hide resolved
_security/access-control/permissions.md Outdated Show resolved Hide resolved
_security/access-control/permissions.md Outdated Show resolved Hide resolved

Users that have the permission [`restapi:admin/roles`]({{site.url}}{{site.baseurl}}/security/access-control/api/#access-control-for-the-api) are able to map system index permissions to all users in the same way they would for a cluster or index permission in the `roles.yml` file. However, to preserve some control over this permission, the system index permission feature is disabled by default and allows administrators to enable this feature by setting the configuration `plugins.security.system_indices.permissions.enabled` to `true`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).

Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health. An admin user should also take precautions when assigning `restapi:admin/roles` to users because this permission gives a user not only the ability to assign the system index permission to another user but also the ability to self-assign access to any system index.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health. An admin user should also take precautions when assigning `restapi:admin/roles` to users because this permission gives a user not only the ability to assign the system index permission to another user but also the ability to self-assign access to any system index.
Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health. An admin user should also take precautions when assigning the `restapi:admin/roles` permission to users because it provides not only the ability to assign the system index permission to another user but also the ability to self-assign access to any system index.

_security/configuration/yaml.md Outdated Show resolved Hide resolved
_security/configuration/yaml.md Outdated Show resolved Hide resolved
_security/configuration/yaml.md Outdated Show resolved Hide resolved
_security/configuration/yaml.md Outdated Show resolved Hide resolved
Copy link
Contributor Author

@cwillum cwillum left a comment

Choose a reason for hiding this comment

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

@natebower I've addressed your comments. At the ready to make any last changes if need be. Thanks.

_security/access-control/permissions.md Outdated Show resolved Hide resolved
Copy link
Collaborator

@natebower natebower left a comment

Choose a reason for hiding this comment

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

LGTM!

@cwillum cwillum removed the 5 - Editorial review PR: Editorial review in progress label Sep 11, 2023
@cwillum cwillum merged commit 3ec2b9c into main Sep 11, 2023
4 checks passed
@cwillum cwillum added the 3 - Done Issue is done/complete label Sep 11, 2023
vagimeli added a commit that referenced this pull request Sep 19, 2023
harshavamsi pushed a commit to harshavamsi/documentation-website that referenced this pull request Oct 31, 2023
…xes (opensearch-project#4849)

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* Fixes some wordings around system index permission access and usage (opensearch-project#4948)

* Fixes some wordings around system index permission access and usage

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses more PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

---------

Signed-off-by: Darshit Chanpura <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* Changes the feature flag key and updates some text (opensearch-project#4953)

* Changes the feature flag key and updates description of a consideration

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses source PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

---------

Signed-off-by: Darshit Chanpura <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

---------

Signed-off-by: cwillum <[email protected]>
Signed-off-by: Darshit Chanpura <[email protected]>
Co-authored-by: Darshit Chanpura <[email protected]>
vagimeli pushed a commit that referenced this pull request Dec 21, 2023
…xes (#4849)

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* Fixes some wordings around system index permission access and usage (#4948)

* Fixes some wordings around system index permission access and usage

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses more PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

---------

Signed-off-by: Darshit Chanpura <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* Changes the feature flag key and updates some text (#4953)

* Changes the feature flag key and updates description of a consideration

Signed-off-by: Darshit Chanpura <[email protected]>

* Addresses source PR feedback

Signed-off-by: Darshit Chanpura <[email protected]>

---------

Signed-off-by: Darshit Chanpura <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

* fix#4736 system index permission

Signed-off-by: cwillum <[email protected]>

---------

Signed-off-by: cwillum <[email protected]>
Signed-off-by: Darshit Chanpura <[email protected]>
Co-authored-by: Darshit Chanpura <[email protected]>
@hdhalter hdhalter deleted the fix#4736-permissionable-sys-indexes branch March 28, 2024 21:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
3 - Done Issue is done/complete release-notes PR: Include this PR in the automated release notes security v2.10.0
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[DOC] Add documentation for permission-able system indices
5 participants