[DOC]Revise Security plugin Configuration TOC structure

[cwillum]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request.
Reorganize topics in the Security plugin Configuration section to improve logic and order.

What other resources are available?
Addresses #1036 for Security.

[cwillum]

A rough, first pass at changing this section of the TOC:

Configuration https://opensearch.org/docs/latest/security-plugin/configuration/index/

• Backend configuration (the name of this topic needs more thought) https://opensearch.org/docs/latest/security-plugin/configuration/configuration/
• YAML files https://opensearch.org/docs/latest/security-plugin/configuration/yaml/
• TLS certificates https://opensearch.org/docs/latest/security-plugin/configuration/tls/
• Generate certificates https://opensearch.org/docs/latest/security-plugin/configuration/generate-certificates/
• System indexes (note re-spelling) https://opensearch.org/docs/latest/security-plugin/configuration/system-indices/
• Applying changes (proposed shortening of heading from "Apply changes with the securitytadmin script") https://opensearch.org/docs/latest/security-plugin/configuration/security-admin/
• Configuring sign-in options (previously "Multiple authentication options for Dashboards sign-in") https://opensearch.org/docs/latest/security-plugin/configuration/multi-auth/
• Disable security https://opensearch.org/docs/latest/security-plugin/configuration/disable/

Authentication (suggest Using "Authentication flow" for the index - removing "flow" - and adding a lead-in at the bottom to the next section to introduce specific protocols and options) https://opensearch.org/docs/latest/security-plugin/configuration/concepts/

• Active Directory and LDAP https://opensearch.org/docs/latest/security-plugin/configuration/ldap/
• SAML https://opensearch.org/docs/latest/security-plugin/configuration/saml/
• OpenID Connect https://opensearch.org/docs/latest/security-plugin/configuration/openid-connect/
• Proxy-based authentication https://opensearch.org/docs/latest/security-plugin/configuration/proxy/
• Client certificate authentication https://opensearch.org/docs/latest/security-plugin/configuration/client-auth/

This is going to need more thought before arriving at a final order. Additionally, I'll need to pad many of the sections with content to make it flow from one section to the next, either at the start, the end, or both. For now, the topics above capture a rough idea of how we can split the Configuration section into two. Creating the Authentication section on its own provides some balance with "Access Control", which we could rename Authorization.

[cwillum]

@cwperks @peternied Here's a proposal for reshuffling the Configuration portion of the Security TOC. Basically, the idea is to break out the authentication backends and separate them from the more universal configuration steps (e.g., configuring YAML files). Could I get your opinions about this format when you get a chance? You can use the links in the comment directly above to navigate to any of these. But here's a link to the Configuration index/landing page:
https://opensearch.org/docs/latest/security-plugin/configuration/index/

Configuration (uses the configuration overview steps as an index)

• Configuring the Security backend (previously Backend configuration - this is a universal step in security configuration, which also includes basic authorization setup, so I'm leaving it with this general configuration section.)
• Modifying the YAML files (previously just "YAML files")
• Configuring TLS certificates
• Generating self-signed certificates
• Applying changes (previously "Applying changes with the securityadmin script". Users can learn they use a securityadmin script when they get there.)
• System indexes
• Configuring sign-in options (previously "Multiple Authentication Options ..." ...)
• Disabling security

Authentication backends (will use "Authentication flow" as the index for this new heading)

• OpenID Connect
• SAML
• Active Directory and LDAP
• Proxy-based authentication
• Client certificate authentication
• (The Internal database, should this be included and documented? I don't have a clear idea of it from the mentions it gets.)

[cwperks]

For the Authentication Backends I think it makes sense to include Bearer Auth (the current JSON Web Tokens section) and Basic Auth (what you are referring to as the internal database). See the following config for an example config.yml with both Basic and Bearer auth.

config:
  dynamic:
    authc:
      basic_internal_auth_domain:
        description: "Authenticate via HTTP Basic against internal users database"
        http_enabled: true
        transport_enabled: true
        order: 0
        http_authenticator:
          type: basic
          challenge: false
        authentication_backend:
          type: intern
      jwt_auth_domain:
        http_enabled: true
        transport_enabled: true
        order: 1
        http_authenticator:
          type: jwt
          challenge: false
          config:
            signing_key: "<base64_encoded_signing_key>"
            jwt_header: "Authorization"
            jwt_url_parameter: null
            subject_key: "sub"
            roles_key: "roles"
        authentication_backend:
          type: noop

The authentication_backend portion of the config can contain one of three values: intern, noop and ldap. When using the basic_internal_auth_domain, HTTP requests to the cluster contain a header like:

"Authorization": "Basic <base_64_encoded(username:password)>"

This username and password is taken from the request header to compare with the user in the internal database (internal_users.yml).

When noop is used, no comparison is made against the internal users so opensearch takes the information passed to it as the user information (subject_key for username and roles_key for backend roles)

For the jwt_auth_domain, the HTTP requests coming to the cluster also have the Authorization header, but in the following format:

"Authorization": "Bearer <jwt>"

where you can think of the jwt as an encoded payload that contains the subject_key and roles_key

The organization proposed makes sense to me.

[hdhalter]

Hi Chris, a couple of questions on >> Applying changes (previously "Applying changes with the securityadmin script". Users can learn they use a securityadmin script when they get there.) and System indexes.

Applying changes is a little vague. Can we add what we are changing? And we might be able to replace it with a more descriptive word like 'Modifying ____'.

Is 'System indexes' a reference topic?

[cwillum]

@hdhalter When I reorganized the topic names, I tried to strike a balance between brevity and meaning/meaninglessness—trying to keep them short without losing meaning. But I get your point. I could rename the securityadmin script topic "Applying changes to configurations". Any better?
Yes, "System indexes (née, System indices)" is vague. It's more of an explanatory topic. And it needs to be explained better (at least to my understanding).
@cwperks What do you think about merging this as a heading into "About security in OpenSearch"? I will need to do some work revising it anyhow.

[cwillum]

This issue is resolved by PR #2212

[cwillum]

Reopening to fix a link in _install-and-configure/install-opensearch/docker.md.