[DOC-META] Security Plugin Documentation

[cwillum]

What do you want to do?

This issue covers multiple items raised by the security team that need attention in Security Plugin documentation. The items include topics that are missing completely from security documentation as well as topics that already exist but are in need of more detail or clarification. The overall objective is to make it easier for users to get up and running with the various security features available with OpenSearch.

These items are listed below as subtasks. As work progresses, we can create individual pull requests against each item while we go along.

Subtasks

• Build out security overview and reorganize documentation #1013
• Update documentation to include plugin permissions on a single page. Details on plugin permissions are missing from the docs. (plugin setup permissions). See https://opensearch.org/docs/latest/install-and-configure/configuring-opensearch/plugin-settings/
• Document how to enable audit logs via APIs rather than with the two-step process involving console and then Dashboards. This is handled in #746. Closed by API documentation to enable audit logging #927.
• Update cluster and index permissions with descriptions of all permissions. [DOC] Enhance documentation to provide clarity for some index level permissions used as cluster level permissions #621 and [DOC] Better documentation around Cluster and Index permissions, wrt adding indices perms as Cluster perms #2359
• [DOC-META ] Review LDAP configuration documentation and provide overall updates #1248
• Provide documentation on how to transition from Elasticsearch X-Pack security to OpenSearch security. #914
• [DOC] Add a new section in documentation for security best practices and recommendations. #5782
• [DOC] Update and validate instructions for creating read-only roles #5783
• Document how to configure customized default roles, such as administrator and read-only user.
• Review and update API documentation so there are descriptions and variations of all relevant fields for the API, with samples that avoid placeholder text like and instead use sample values like “testrole”.
• Provide explicit information on which permissions are needed at cluster and index levels for each API for open source
• Provide detailed step-by-step procedures for creating a role that displays Dashboards with read-only privileges and hides other components.
• Round out the "Default action groups" page so that information is comprehensive and complete with introductions to group types, descriptions, and references.
• Document how to setup private tenant in URL, SAML, and other supported authentication protocols. (URL parameters, security_tenant parameters)
• Document performance impacts when using FGAC, DLS/FLS, field masking and best practices when configuring for optimized performance of various sub features.

Not open source:

• Document methods for connecting an external application or AWS service to OpenSearch, including FGAC.
• Update and complete documentation on how to integrate with Identity and Access Management (IAM), including methods and examples for mapping IAM roles.
• Document how to enable SAML/Cognito on VPC domains.
• Provide explicit information on which permissions are needed at cluster and index levels for each API for managed services, such as UltraWarm.

Do you have any related resources to help us get started?

See Security Plugin documentation here.

[nateynateynate]

Someone specifically asking for a login selector here.

[cwillum]

This was closed automatically after I merged #927 because of association by mentions. Reopening.

[cwillum]

Documentation for enabling audit logging by API is covered and completed in PR #927.

[cwillum]

Putting the focus for this META issue on the following priorities for the time being:

• add individual backend authentication sections for basic auth and JWT (bearer auth). [DOC]Create a dedicated Basic authentication topic for the Authentication Backend section in Security documentation #2512
• General cleanup and updates for authentication backends, including LDAP, SAML, and OIDC.
• Better documentation around cluster and index permissions. [DOC] Better documentation around Cluster and Index permissions, wrt adding indices perms as Cluster perms #2359