Reorganize Configuration section of the Security TOC

_security-plugin/access-control/api.md

@@ -2,7 +2,7 @@
 layout: default
 title: API
 parent: Access control
-nav_order: 90
+nav_order: 120
 ---
 
 # API
@@ -678,11 +678,11 @@ PUT _plugins/_security/api/roles/<role>
 }
 ```
 
->Due to word boundaries associated with Unicode special characters, the Unicode standard analyzer cannot index a [text field type](https://opensearch.org/docs/2.2/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.
+>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.
 >
 >For example, since the values in the fields ```"user.id": "User-1"``` and ```"user.id": "User-2"``` contain the hyphen/minus sign, this special character will prevent the analyzer from distinguishing between the two different users for `user.id` and interpret them as one and the same. This can lead to unintentional filtering of documents and potentially compromise control over their access.
 >
->To avoid this circumstance, you can use a custom analyzer or map the field as `keyword`, which performs an exact-match search. See [Keyword field type](https://opensearch.org/docs/2.2/opensearch/supported-field-types/keyword/) for the latter option.
+>To avoid this circumstance, 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).
 {: .warning}
@@ -1424,7 +1424,7 @@ The following API is available for audit logging in the security plugin.
 
 This API allows you to enable or disable audit logging, define the configuration for audit logging and compliance, and make updates to settings.
 
-For details on using audit logging to track access to OpenSearch clusters, as well as information on further configurations, see [Audit logs](https://opensearch.org/docs/latest/security-plugin/audit-logs/index/).
+For details on using audit logging to track access to OpenSearch clusters, as well as information on further configurations, see [Audit logs]({{site.url}}{{site.baseurl}}/security-plugin/audit-logs/index/).
 
 You can do an initial configuration of audit logging in the `audit.yml` file, found in the `opensearch-project/security/config` directory. Thereafter, you can use the REST API or Dashboards for further changes to the configuration.
 {: note.}
@@ -1525,7 +1525,7 @@ PUT /_opendistro/_security/api/audit/config
 
 A PATCH call is used to update specified fields in the audit configuration. The PATCH method requires an operation, a path, and a value to complete a valid request. For details on using the PATCH method, see the following [Patching resources](https://en.wikipedia.org/wiki/PATCH_%28HTTP%29#Patching_resources) description at Wikipedia.
 
-Using the PATCH method also requires a user to have a security configuration that includes admin certificates for encryption. To find out more about these certificates, see [Configure admin certificates](https://opensearch.org/docs/latest/security-plugin/configuration/tls/#configure-admin-certificates).
+Using the PATCH method also requires a user to have a security configuration that includes admin certificates for encryption. To find out more about these certificates, see [Configure admin certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/#configure-admin-certificates).
 
 ```bash
 curl -X PATCH -k -i --cert <admin_cert file name> --key <admin_cert_key file name> <domain>/_opendistro/_security/api/audit -H 'Content-Type: application/json' -d'[{"op":"add","path":"/config/enabled","value":"true"}]'

_security-plugin/access-control/cross-cluster-search.md

@@ -2,7 +2,7 @@
 layout: default
 title: Cross-cluster search
 parent: Access control
-nav_order: 40
+nav_order: 105
 ---
 
 # Cross-cluster search

_security-plugin/access-control/default-action-groups.md

@@ -2,7 +2,7 @@
 layout: default
 title: Default action groups
 parent: Access control
-nav_order: 51
+nav_order: 115
 ---
 
 # Default action groups

_security-plugin/access-control/document-level-security.md

@@ -2,7 +2,7 @@
 layout: default
 title: Document-level security
 parent: Access control
-nav_order: 10
+nav_order: 85
 ---
 
 # Document-level security (DLS)
@@ -57,7 +57,7 @@ These queries can be as complex as you want, but we recommend keeping them simpl
 
 ### 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](https://opensearch.org/docs/2.2/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.
+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:
 
@@ -85,7 +85,7 @@ The examples below illustrate values containing special characters that will be
 }
 ```
 
-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](https://opensearch.org/docs/2.2/opensearch/supported-field-types/keyword/) for the latter option.
+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).
 
@@ -165,7 +165,7 @@ You can perform term-level lookup queries (TLQs) with document-level security (D
 
 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](https://opensearch.org/docs/latest/opensearch/query-dsl/term/).
+To learn more about OpenSearch queries, see [Term-level queries]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/term/).
 
 ### How to set the DLS evaluation mode in `opensearch.yml`
 

_security-plugin/access-control/field-level-security.md

@@ -2,7 +2,7 @@
 layout: default
 title: Field-level security
 parent: Access control
-nav_order: 11
+nav_order: 90
 ---
 
 # Field-level security
@@ -93,7 +93,7 @@ someonerole:
 
 ### REST API
 
-See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role).
+See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#create-role).
 
 
 ## Interaction with multiple roles

_security-plugin/access-control/field-masking.md

@@ -2,7 +2,7 @@
 layout: default
 title: Field masking
 parent: Access control
-nav_order: 12
+nav_order: 95
 ---
 
 # Field masking
@@ -68,7 +68,7 @@ someonerole:
 
 ### REST API
 
-See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role).
+See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#create-role).
 
 
 ## (Advanced) Use an alternative hash algorithm

_security-plugin/access-control/impersonation.md

@@ -2,7 +2,7 @@
 layout: default
 title: User impersonation
 parent: Access control
-nav_order: 20
+nav_order: 100
 ---
 
 # User impersonation

_security-plugin/access-control/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Access control
-nav_order: 30
+nav_order: 75
 has_children: true
 has_toc: false
 redirect_from:
@@ -10,7 +10,7 @@ redirect_from:
 
 # Access control
 
-After you [configure the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) to use your own certificates and preferred authentication backend, you can start adding users, creating roles, and mapping roles to users.
+After you [configure the Security plugin]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) to use your own certificates and preferred authentication backend, you can start adding users, creating roles, and mapping roles to users.
 
 This section of the documentation covers what a user is allowed to see and do after successfully authenticating.
 

_security-plugin/access-control/permissions.md

@@ -2,7 +2,7 @@
 layout: default
 title: Permissions
 parent: Access control
-nav_order: 50
+nav_order: 110
 ---
 
 # Permissions
@@ -41,7 +41,7 @@ These permissions also allow you add, update, or delete documents (e.g. `PUT tes
 
 ## Test permissions
 
-If you want a user to have the absolute minimum set of permissions necessary to perform some function---the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)----the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response:
+If you want a user to have the absolute minimum set of permissions necessary to perform some function—the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)—the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response:
 
 ```json
 GET _cat/shards?v

_security-plugin/access-control/users-roles.md

@@ -2,7 +2,7 @@
 layout: default
 title: Users and roles
 parent: Access control
-nav_order: 1
+nav_order: 80
 ---
 
 # Users and roles
@@ -11,7 +11,7 @@ The security plugin includes an internal user database. Use this database in pla
 
 Roles are the core way of controlling access to your cluster. Roles contain any combination of cluster-wide permissions, index-specific permissions, document- and field-level security, and tenants. Then you map users to these roles so that users gain those permissions.
 
-Unless you need to create new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#reserved-and-hidden-resources), we **highly** recommend using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use.
+Unless you need to create new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#reserved-and-hidden-resources), we **highly** recommend using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use.
 {: .warning }
 
 ---
@@ -39,12 +39,12 @@ You can create users using OpenSearch Dashboards, `internal_users.yml`, or the R
 
 ### internal_users.yml
 
-See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#internal_usersyml).
+See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#internal_usersyml).
 
 
 ### REST API
 
-See [Create user]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user).
+See [Create user]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#create-user).
 
 
 ## Create roles
@@ -65,12 +65,12 @@ Just like users, you can create roles using OpenSearch Dashboards, `roles.yml`,
 
 ### roles.yml
 
-See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#rolesyml).
+See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#rolesyml).
 
 
 ### REST API
 
-See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role).
+See [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#create-role).
 
 
 ## Map users to roles
@@ -89,12 +89,12 @@ Just like users and roles, you create role mappings using OpenSearch Dashboards,
 
 ### roles_mapping.yml
 
-See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml#roles_mappingyml).
+See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#roles_mappingyml).
 
 
 ### REST API
 
-See [Create role mapping]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role-mapping).
+See [Create role mapping]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#create-role-mapping).
 
 
 ## Predefined roles
@@ -119,7 +119,7 @@ Role | Description
 `manage_snapshots` | Grants permissions to manage snapshot repositories, take snapshots, and restore snapshots.
 `readall` | Grants permissions for cluster-wide searches like `msearch` and search permissions for all indices.
 `readall_and_monitor` | Same as `readall`, but with added cluster monitoring permissions.
-`security_rest_api_access` | A special role that allows access to the REST API. See `plugins.security.restapi.roles_enabled` in `opensearch.yml` and [Access control for the API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#access-control-for-the-api).
+`security_rest_api_access` | A special role that allows access to the REST API. See `plugins.security.restapi.roles_enabled` in `opensearch.yml` and [Access control for the API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#access-control-for-the-api).
 `reports_read_access` | Grants permissions to generate on-demand reports, download existing reports, and view report definitions, but not to create report definitions.
 `reports_instances_read_access` | Grants permissions to generate on-demand reports and download existing reports, but not to view or create report definitions.
 `reports_full_access` | Grants full permissions to reports.

_security-plugin/audit-logs/field-reference.md

@@ -2,7 +2,7 @@
 layout: default
 title: Audit log field reference
 parent: Audit logs
-nav_order: 1
+nav_order: 130
 ---
 
 # Audit log field reference

_security-plugin/audit-logs/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Audit logs
-nav_order: 40
+nav_order: 125
 has_children: true
 has_toc: false
 redirect_from:

_security-plugin/audit-logs/storage-types.md

@@ -2,7 +2,7 @@
 layout: default
 title: Audit log storage types
 parent: Audit logs
-nav_order: 10
+nav_order: 135
 ---
 
 # Audit log storage types

_security-plugin/configuration/concepts.md → _security-plugin/authentication-backends/authc-index.md

@@ -1,23 +1,28 @@
 ---
 layout: default
-title: Authentication flow
-parent: Configuration
-nav_order: 1
+title: Authentication backends
+nav_order: 45
+has_children: true
+has_toc: false
+redirect_from:
+  - /security-plugin/authentication-backends/
 ---
 
-# Authentication flow
+# Authentication backends
 
-Understanding the authentication flow is a great way to get started with configuring the security plugin.
+Authentication backend configurations determine the method or methods you use for authenticating users and the way users pass their credentials and sign in to OpenSearch. Having an understanding of the basic authentication flow before getting started can help with the configuration process for whichever backend you choose. Consider the high-level sequence of events in the description that follows, and then refer to the detailed steps for configuring the authentication type you choose to use with OpenSearch.
 
-1. To identify a user who wants to access the cluster, the security plugin needs the user's credentials.
+## Authentication flow
+
+1. To identify a user who wants to access the cluster, the Security plugin needs the user's credentials.
 
    These credentials differ depending on how you've configured the plugin. For example, if you use basic authentication, the credentials are a user name and password. If you use a JSON web token, the credentials are stored within the token itself. If you use TLS certificates, the credentials are the distinguished name (DN) of the certificate.
 
-2. The security plugin authenticates the user's credentials against a backend: the internal user database, Lightweight Directory Access Protocol (LDAP), Active Directory, Kerberos, or JSON web tokens.
+2. The Security plugin authenticates the user's credentials against a backend: the internal user database (basic authentictation), Lightweight Directory Access Protocol (LDAP)/Active Directory, JSON web tokens, SAML, or another authentication protocol.
 
    The plugin supports chaining backends in `config/opensearch-security/config.yml`. If more than one backend is present, the plugin tries to authenticate the user sequentially against each until one succeeds. A common use case is to combine the internal user database of the security plugin with LDAP/Active Directory.
 
-3. After a backend verifies the user's credentials, the plugin collects any backend roles. These roles can be arbitrary strings in the internal user database, but in most cases, these backend roles come from LDAP/Active Directory.
+3. After a backend verifies the user's credentials, the plugin collects any backend roles. These roles can be arbitrary strings in the internal user database, roles retrieved from the LDAP/Active Directory server, or roles that are kept as attributes with the SAML protocol.
 
 4. After the user is authenticated and any backend roles are retrieved, the security plugin uses the role mapping to assign security roles to the user.