[DOCS] Adds LDAP realm configuration details (#30214)

Author: lcawl

x-pack/docs/en/security/authentication/configuring-ldap-realm.asciidoc

@@ -0,0 +1,214 @@
+[role="xpack"]
+[[configuring-ldap-realm]]
+=== Configuring an LDAP realm
+
+You can configure {security} to communicate with a Lightweight Directory Access
+Protocol (LDAP) server to authenticate users. To integrate with LDAP, you
+configure an `ldap` realm and map LDAP groups to user roles.
+
+For more information about LDAP realms, see 
+{xpack-ref}/ldap-realm.html[LDAP User Authentication].
+
+. Determine which mode you want to use. The `ldap` realm supports two modes of 
+operation, a user search mode and a mode with specific templates for user DNs. 
++
+--
+LDAP user search is the most common mode of operation. In this mode, a specific
+user with permission to search the LDAP directory is used to search for the DN 
+of the authenticating user based on the provided username and an LDAP attribute. 
+Once found, the user is authenticated by attempting to bind to the LDAP server 
+using the found DN and the provided password.
+
+If your LDAP environment uses a few specific standard naming conditions for
+users, you can use user DN templates to configure the realm. The advantage of
+this method is that a search does not have to be performed to find the user DN.
+However, multiple bind operations might be needed to find the correct user DN.
+--
+
+. To configure an `ldap` realm with user search:
+
+.. Add a realm configuration of type `ldap` to `elasticsearch.yml` under the
+`xpack.security.authc.realms` namespace. At a minimum, you must set the realm 
+`type` to `ldap`, specify the `url` of the LDAP server, and set 
+`user_search.base_dn` to the container DN where the users are searched for. If 
+you are configuring multiple realms, you should also explicitly set the `order` 
+attribute to control the order in which the realms are consulted during 
+authentication. See <<ref-ldap-settings>> for all of the options you can set for 
+an `ldap` realm.
++
+--
+For example, the following snippet shows an LDAP realm configured with a user search:
+
+[source, yaml]
+------------------------------------------------------------
+xpack:
+  security:
+    authc:
+      realms:
+        ldap1:
+          type: ldap
+          order: 0
+          url: "ldaps://ldap.example.com:636"
+          bind_dn: "cn=ldapuser, ou=users, o=services, dc=example, dc=com"
+          user_search:
+            base_dn: "dc=example,dc=com"
+            attribute: cn
+          group_search:
+            base_dn: "dc=example,dc=com"
+          files:
+            role_mapping: "CONFIG_DIR/x-pack/role_mapping.yml"
+          unmapped_groups_as_roles: false
+------------------------------------------------------------
+
+The password for the `bind_dn` user should be configured by adding the appropriate
+`secure_bind_password` setting to the {es} keystore.
+For example, the following command adds the password for the example realm above:
+
+[source, shell]
+------------------------------------------------------------
+bin/elasticsearch-keystore add \
+xpack.security.authc.realms.ldap1.secure_bind_password
+------------------------------------------------------------
+
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
+realms you specify are used for authentication. If you also want to use the
+`native` or `file` realms, you must include them in the realm chain.
+
+--
+
+. To configure an `ldap` realm with user DN templates:
+
+.. Add a realm configuration of type `ldap` to `elasticsearch.yml` in the
+`xpack.security.authc.realms` namespace. At a minimum, you must set the realm 
+`type` to `ldap`, specify the `url` of the LDAP server, and specify at least one 
+template with the `user_dn_templates` option. If you are configuring multiple 
+realms, you should also explicitly set the `order` attribute to control the 
+order in which the realms are consulted during authentication. See 
+<<ref-ldap-settings>> for all of the options you can set for an `ldap` realm.
++
+--
+For example, the following snippet shows an LDAP realm configured with user DN 
+templates:
+
+[source, yaml]
+------------------------------------------------------------
+xpack:
+  security:
+    authc:
+      realms:
+        ldap1:
+          type: ldap
+          order: 0
+          url: "ldaps://ldap.example.com:636"
+          user_dn_templates:
+            - "cn={0}, ou=users, o=marketing, dc=example, dc=com"
+            - "cn={0}, ou=users, o=engineering, dc=example, dc=com"
+          group_search:
+            base_dn: "dc=example,dc=com"
+          files:
+            role_mapping: "/mnt/elasticsearch/group_to_role_mapping.yml"
+          unmapped_groups_as_roles: false
+------------------------------------------------------------
+
+IMPORTANT: The `bind_dn` setting is not used in template mode.
+All LDAP operations run as the authenticating user.
+
+--
+
+. (Optional) Configure how {security} should interact with multiple LDAP servers. 
++ 
+--
+The `load_balance.type` setting can be used at the realm level. {security} 
+supports both failover and load balancing modes of operation. See 
+<<ref-ldap-settings>>.
+--
+
+. (Optional) To protect passwords, 
+<<tls-ldap,encrypt communications between {es} and the LDAP server>>. 
+
+. Restart {es}. 
+
+. Map LDAP groups to roles. 
++
+--
+The `ldap` realm enables you to map LDAP users to to roles via their LDAP
+groups, or other metadata. This role mapping can be configured via the
+{ref}/security-api-role-mapping.html[role-mapping API] or by using a file stored
+on each node. When a user authenticates with LDAP, the privileges
+for that user are the union of all privileges defined by the roles to which
+the user is mapped.
+
+Within a mapping definition, you specify groups using their distinguished
+names. For example, the following mapping configuration maps the LDAP
+`admins` group to both the `monitoring` and `user` roles, and maps the
+`users` group to the `user` role.
+
+Configured via the role-mapping API:
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/admins
+{
+  "roles" : [ "monitoring" , "user" ],
+  "rules" : { "field" : {
+    "groups" : "cn=admins,dc=example,dc=com" <1>
+  } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The LDAP distinguished name (DN) of the `admins` group.
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/basic_users
+{
+  "roles" : [ "user" ],
+  "rules" : { "field" : {
+    "groups" : "cn=users,dc=example,dc=com" <1>
+  } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The LDAP distinguished name (DN) of the `users` group.
+
+Or, alternatively, configured via the role-mapping file:
+[source, yaml]
+------------------------------------------------------------
+monitoring: <1>
+  - "cn=admins,dc=example,dc=com" <2>
+user:
+  - "cn=users,dc=example,dc=com" <3>
+  - "cn=admins,dc=example,dc=com"
+------------------------------------------------------------
+<1> The name of the mapped role.
+<2> The LDAP distinguished name (DN) of the `admins` group.
+<3> The LDAP distinguished name (DN) of the `users` group.
+
+For more information, see 
+{xpack-ref}/ldap-realm.html#mapping-roles-ldap[Mapping LDAP Groups to Roles] 
+and 
+{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles].
+--
+
+. (Optional) Configure the `metadata` setting on the LDAP realm to include extra 
+fields in the user's metadata. 
++
+--
+By default, `ldap_dn` and `ldap_groups` are populated in the user's metadata. 
+For more information, see 
+{xpack-ref}/ldap-realm.html#ldap-user-metadata[User Metadata in LDAP Realms]. 
+
+The example below includes the user's common name (`cn`) as an additional
+field in their metadata.
+[source,yaml]
+--------------------------------------------------
+xpack:
+  security:
+    authc:
+      realms:
+        ldap1:
+          type: ldap
+          metadata: cn
+--------------------------------------------------
+--