[DOCS] Adds security content in the Elasticsearch Reference (#47934)

Author: lcawl

docs/reference/index.asciidoc

@@ -68,7 +68,7 @@ include::frozen-indices.asciidoc[]
 
 include::rest-api/index.asciidoc[]
 
-include::security/index.asciidoc[]
+include::{xes-repo-dir}/security/index.asciidoc[]
 
 include::{xes-repo-dir}/watcher/index.asciidoc[]
 

docs/reference/security/index.asciidoc

@@ -7,7 +7,7 @@
 
 You can configure this licensing setting in the `elasticsearch.yml` file.
 For more information, see
-{xpack-ref}/license-management.html[{xpack} License Management].
+{stack-ov}/license-management.html[License management].
 
 `xpack.license.self_generated.type`::
 Set to `basic` (default) to enable basic {xpack} features. +

docs/reference/settings/license-settings.asciidoc

@@ -69,8 +69,7 @@ See <<password-hashing-algorithms>>. Defaults to `bcrypt`.
 [[anonymous-access-settings]]
 ==== Anonymous access settings
 You can configure the following anonymous access settings in
-`elasticsearch.yml`.  For more information, see {stack-ov}/anonymous-access.html[
-Enabling anonymous access].
+`elasticsearch.yml`.  For more information, see <<anonymous-access>>.
 
 `xpack.security.authc.anonymous.username`::
 The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`.
@@ -120,8 +119,7 @@ Defaults to `48h` (48 hours).
 
 You can set the following document and field level security
 settings in `elasticsearch.yml`. For more information, see
-{stack-ov}/field-and-document-access-control.html[Setting up document and field
-level security].
+<<field-and-document-access-control>>.
 
 `xpack.security.dls_fls.enabled`::
 Set to `false` to prevent document and field level security
@@ -206,7 +204,7 @@ xpack.security.authc.realms:
 ----------------------------------------
 
 The valid settings vary depending on the realm type. For more
-information, see {stack-ov}/setting-up-authentication.html[Setting up authentication].
+information, see <<setting-up-authentication>>.
 
 [float]
 [[ref-realm-settings]]
@@ -245,8 +243,8 @@ Defaults to `ssha256`.
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 [[ref-users-settings]]
@@ -261,7 +259,7 @@ the following settings:
 `cache.ttl`::
 The time-to-live for cached user entries. A user and a hash of its credentials 
 are cached for this configured period of time. Defaults to `20m`. Specify values 
-using the standard {es} {ref}/common-options.html#time-units[time units].
+using the standard {es} <<time-units,time units>>.
 Defaults to `20m`.
 
 `cache.max_users`::
@@ -274,8 +272,8 @@ user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 [[ref-ldap-settings]]
@@ -326,14 +324,14 @@ The DN template that replaces the user name with the string `{0}`.
 This setting is multivalued; you can specify multiple user contexts.
 Required to operate in user template mode. If `user_search.base_dn` is specified, 
 this setting is not valid. For more information on
-the different modes, see {stack-ov}/ldap-realm.html[LDAP realms].
+the different modes, see <<ldap-realm>>.
 
 `authorization_realms`::
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the LDAP realm does not perform role mapping and
 instead loads the user from the listed realms. The referenced realms are
 consulted in the order that they are defined in this list.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm] 
+See <<authorization_realms>>. 
 +
 --
 NOTE: If any settings starting with `user_search` are specified, the 
@@ -350,7 +348,7 @@ to `memberOf`.
 Specifies a container DN to search for users. Required
 to operated in user search mode. If `user_dn_templates` is specified, this 
 setting is not valid. For more information on
-the different modes, see {stack-ov}/ldap-realm.html[LDAP realms].
+the different modes, see <<ldap-realm>>.
 
 `user_search.scope`::
 The scope of the user search. Valid values are `sub_tree`, `one_level` or
@@ -423,12 +421,12 @@ the filter.  If not set, the user DN is passed into the filter. Defaults to Empt
 If set to `true`, the names of any unmapped LDAP groups are used as role names 
 and assigned to the user. A group is considered to be _unmapped_ if it is not 
 referenced in a
-{stack-ov}/mapping-roles.html#mapping-roles-file[role-mapping file]. API-based 
+<<mapping-roles-file,role-mapping file>>. API-based 
 role mappings are not considered. Defaults to `false`.
 
 `files.role_mapping`::
-The <<security-files,location>> for the {stack-ov}/mapping-roles.html#mapping-roles[
-YAML role mapping configuration file]. Defaults to
+The <<security-files,location>> for the
+<<mapping-roles,YAML role mapping configuration file>>. Defaults to
 `ES_PATH_CONF/role_mapping.yml`.
 
 `follow_referrals`::
@@ -545,8 +543,8 @@ in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssha256
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 [[ref-ad-settings]]
@@ -786,7 +784,7 @@ Java Cryptography Architecture documentation]. Defaults to the value of
 `cache.ttl`::
 Specifies the time-to-live for cached user entries. A user and a hash of its 
 credentials are cached for this configured period of time. Use the
-standard Elasticsearch {ref}/common-options.html#time-units[time units]).
+standard Elasticsearch <<time-units,time units>>).
 Defaults to `20m`.
 
 `cache.max_users`::
@@ -799,8 +797,8 @@ the in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssh
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 `follow_referrals`::
@@ -841,19 +839,19 @@ for SSL. This setting cannot be used with `certificate_authorities`.
 
 `files.role_mapping`::
 Specifies the <<security-files,location>> of the
-{stack-ov}/mapping-roles.html[YAML role  mapping configuration file].
+<<mapping-roles,YAML role  mapping configuration file>>.
 Defaults to `ES_PATH_CONF/role_mapping.yml`.
 
 `authorization_realms`::
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the PKI realm does not perform role mapping and
 instead loads the user from the listed realms.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm] 
+See <<authorization_realms>>. 
 
 `cache.ttl`::
 Specifies the time-to-live for cached user entries. A user and a hash of its 
 credentials are cached for this period of time. Use the
-standard {es} {ref}/common-options.html#time-units[time units]).
+standard {es} <<time-units,time units>>).
 Defaults to `20m`.
 
 `cache.max_users`::
@@ -973,7 +971,7 @@ provided by the SAML attributes. Defaults to `true`.
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the SAML realm does not perform role mapping and
 instead loads the user from the listed realms.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm] 
+See <<authorization_realms>>.
 
 `allowed_clock_skew`::
 The maximum amount of skew that can be tolerated between the IdP's clock and the
@@ -987,7 +985,7 @@ authenticate the current user. The Authentication Context of the corresponding
 authentication response should contain at least one of the requested values.
 +
 For more information, see
-{stack-ov}/saml-guide-authentication.html#req-authn-context[Requesting specific authentication methods].
+<<req-authn-context>>.
 
 [float]
 [[ref-saml-signing-settings]]
@@ -1221,7 +1219,7 @@ cache at any given time. Defaults to 100,000.
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the Kerberos realm does not perform role mapping and
 instead loads the user from the listed realms.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm]
+See <<authorization_realms>>.
 
 [float]
 [[load-balancing]]
@@ -1264,7 +1262,7 @@ endif::[]
 
 You can configure the following TLS/SSL settings in
 `elasticsearch.yml`. For more information, see
-{stack-ov}/encrypting-communications.html[Encrypting communications]. These
+<<encrypting-communications>>. These
 settings are used unless they have been overridden by more specific
 settings such as those for HTTP or Transport.
 
@@ -1422,7 +1420,7 @@ keystore files. See <<fips-140-compliance>>.
 [[pkcs12-truststore-note]]
 [NOTE]
 Storing trusted certificates in a PKCS#12 file, although supported, is
-uncommon in practice. The {ref}/certutil.html[`elasticsearch-certutil`] tool,
+uncommon in practice. The <<certutil,`elasticsearch-certutil`>> tool,
 as well as Java's `keytool`, are designed to generate PKCS#12 files that
 can be used both as a keystore and as a truststore, but this may not be the
 case for container files that are created using other tools. Usually,
@@ -1509,7 +1507,7 @@ See also <<remote-audit-settings>>.
 [[ip-filtering-settings]]
 ==== IP filtering settings
 
-You can configure the following settings for {stack-ov}/ip-filtering.html[IP filtering].
+You can configure the following settings for <<ip-filtering,IP filtering>>.
 
 `xpack.security.transport.filter.allow`::
 List of IP addresses to allow.

docs/reference/settings/security-settings.asciidoc

@@ -11,7 +11,7 @@ https://github.com/elastic/elasticsearch/blob/{branch}/distribution/docker[Githu
 
 These images are free to use under the Elastic license. They contain open source 
 and free commercial features and access to paid commercial features.  
-{xpack-ref}/license-management.html[Start a 30-day trial] to try out all of the 
+{stack-ov}/license-management.html[Start a 30-day trial] to try out all of the 
 paid commercial features. See the 
 https://www.elastic.co/subscriptions[Subscriptions] page for information about 
 Elastic license levels.

docs/reference/setup/install/docker.asciidoc

@@ -7,7 +7,7 @@ monitoring, reporting, machine learning, and many other capabilities. By default
 when you install {es}, {xpack} is installed. 
 
 If you want to try all of the {xpack} features, you can 
-{xpack-ref}/license-management.html[start a 30-day trial]. At the end of the 
+{stack-ov}/license-management.html[start a 30-day trial]. At the end of the 
 trial period, you can purchase a subscription to keep using the full 
 functionality of the {xpack} components. For more information, see 
 https://www.elastic.co/subscriptions.

docs/reference/setup/setup-xes.asciidoc

@@ -18,7 +18,7 @@ The following is a list of the events that can be generated:
                                           realm type.
 | `access_denied`                   | | | Logged when an authenticated user attempts to execute
                                           an action they do not have the necessary
-                                          <<security-reference, privilege>> to perform.
+                                          <<security-privileges,privilege>> to perform.
 | `access_granted`                  | | | Logged when an authenticated user attempts to execute
                                           an action they have the necessary privilege to perform.
                                           When the `system_access_granted` event is included, all system
@@ -28,7 +28,7 @@ The following is a list of the events that can be generated:
                                           another user that they have the necessary privileges to do.
 | `run_as_denied`                   | | | Logged when an authenticated user attempts to <<run-as-privilege, run as>>
                                           another user action they do not have the necessary
-                                          <<security-reference, privilege>> to do so.
+                                          <<security-privileges,privilege>> to do so.
 | `tampered_request`                | | | Logged when the {security-features} detect that the request has
                                           been tampered with. Typically relates to `search/scroll`
                                           requests when the scroll ID is believed to have been

x-pack/docs/en/security/auditing/event-types.asciidoc

@@ -12,11 +12,7 @@ include::native-realm.asciidoc[]
 include::pki-realm.asciidoc[]
 include::saml-realm.asciidoc[]
 include::kerberos-realm.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/custom-realm.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/anonymous-access.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/user-cache.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/saml-guide.asciidoc[]
+include::custom-realm.asciidoc[]
+include::anonymous-access.asciidoc[]
+include::user-cache.asciidoc[]
+include::saml-guide.asciidoc[]

x-pack/docs/en/security/authentication/index.asciidoc

@@ -90,7 +90,7 @@ configure the HTTP interface to use SSL/TLS before you can enable SAML
 authentication.
 
 For more information, see
-{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications].
+<<tls-http>>.
 
 [[saml-enable-token]]
 ==== Enable the token service
@@ -378,7 +378,7 @@ successfully authenticated, the Authentication Statement of the SAML Response
 contains an indication of the restrictions that were satisfied.
 
 You can define the Authentication Context Class Reference values by using the `req_authn_context_class_ref` option in the SAML realm configuration. See 
-{ref}/security-settings.html#ref-saml-settings[SAML realm settings]. 
+<<ref-saml-settings>>. 
 
 {es} supports only the `exact` comparison method for the Authentication Context. 
 When it receives the Authentication Response from the IdP, {es} examines the 
@@ -496,7 +496,7 @@ You should consult the documentation for your IdP to determine what formats they
 support. Since PEM format is the most commonly supported format, the examples
 below will generate certificates in that format.
 
-Using the {ref}/certutil.html[`elasticsearch-certutil`] tool, you can generate a
+Using the <<certutil,`elasticsearch-certutil`>> tool, you can generate a
 signing certificate with the following command:
 
 [source, sh]
@@ -536,7 +536,7 @@ The path to the PEM formatted key file. e.g. `saml/saml-sign.key`
 
 `signing.secure_key_passphrase`::
 The passphrase for the key, if the file is encrypted. This is a
-{ref}/secure-settings.html[secure setting] that must be set with the
+<<secure-settings,secure setting>> that must be set with the
 `elasticsearch-keystore` tool.
 
 If you wish to use *PKCS#12 formatted* files or a *Java Keystore* for
@@ -550,7 +550,7 @@ The alias of the key within the keystore. e.g. `signing-key`
 
 `signing.keystore.secure_password`::
 The passphrase for the keystore, if the file is encrypted. This is a
-{ref}/secure-settings.html[secure setting] that must be set with the
+<<secure-settings,secure setting>> that must be set with the
 `elasticsearch-keystore` tool.
 
 If you wish to sign some, but not all outgoing *SAML messages*, then you
@@ -587,7 +587,7 @@ The path to the PEM formatted key file. e.g. `saml/saml-crypt.key`
 
 `encryption.secure_key_passphrase`::
 The passphrase for the key, if the file is encrypted. This is a
-{ref}/secure-settings.html[secure setting] that must be set with the
+<<secure-settings,secure setting>> that must be set with the
 `elasticsearch-keystore` tool.
 
 If you wish to use *PKCS#12 formatted* files or a *Java Keystore* for SAML
@@ -601,7 +601,7 @@ The alias of the key within the keystore. e.g. `encryption-key`
 
 `encryption.keystore.secure_password`::
 The passphrase for the keystore, if the file is encrypted. This is a
-{ref}/secure-settings.html[secure setting] that must be set with the
+<<secure-settings,secure setting>> that must be set with the
 `elasticsearch-keystore` tool.
 
 [[saml-sp-metadata]]
@@ -614,7 +614,7 @@ between the IdP and the SP.
 The Elastic Stack supports generating such a metadata file using the
 `bin/elasticsearch-saml-metadata` command in your {es} directory.
 
-The {ref}/saml-metadata.html[documentation for the elasticsearch-saml-metadata utility]
+The <<saml-metadata,documentation for the elasticsearch-saml-metadata utility>>
 describes how to run it, and the available command line options.
 
 [[saml-role-mapping]]
@@ -626,10 +626,10 @@ access any data.
 
 Your SAML users cannot do anything until they are assigned roles. This can be done
 through either the
-{ref}/security-api-put-role-mapping.html[add role mapping API], or with
+<<security-api-put-role-mapping,add role mapping API>> or with
 <<authorization_realms, authorization realms>>.
 
-NOTE: You cannot use {stack-ov}/mapping-roles.html#mapping-roles-file[role mapping files]
+NOTE: You cannot use <<mapping-roles-file,role mapping files>>
 to grant roles to users authenticating via SAML.
 
 This is an example of a simple role mapping that grants the `kibana_user` role
@@ -662,7 +662,7 @@ mapping are derived from the SAML attributes as follows:
 - `metadata`: See <<saml-user-metadata>>
 
 For more information, see <<mapping-roles>> and
-{ref}/security-api.html#security-role-mapping-apis[role mapping APIs]. 
+<<security-role-mapping-apis>>. 
 
 If your IdP has the ability to provide groups or roles to Service Providers,
 then you should map this SAML attribute to the `attributes.groups` setting in
@@ -879,5 +879,5 @@ Additionally, different security domains have different security requirements th
 specific configuration to be satisfied.
 A conscious effort has been made to mask this complexity with sane defaults and the detailed
 documentation above but in case you encounter issues while configuring a SAML realm, you can
-look through our {stack-ov}/trb-security-saml.html[SAML troubleshooting documentation] that has
+look through our <<trb-security-saml,SAML troubleshooting documentation>> that has
 suggestions and resolutions for common issues.