English documentation about LDAP interaction (#11223)

Co-authored-by: Ivan Blinkov <[email protected]>

2 files changed, 159 insertions, 1 deletions

diff --git a/ydb/docs/en/core/concepts/auth.md b/ydb/docs/en/core/concepts/auth.md
index 8eff465d1af..429b63e0275 100644
--- a/ydb/docs/en/core/concepts/auth.md
+++ b/ydb/docs/en/core/concepts/auth.md
@@ -57,4 +57,106 @@ Authentication by username and password includes the following steps:
 
 To enable username/password authentication, use `true` in the `enforce_user_token_requirement` key of the cluster's [configuration file](../reference/configuration/index.md#auth).
 
-To learn how to manage roles and users, see [{#T}](../security/access-management.md).
\ No newline at end of file
+To learn how to manage roles and users, see [{#T}](../security/access-management.md).
+
+## LDAP directory integration {#ldap-auth-provider}
+
+{{ ydb-short-name }} supports authentication and authorization via an [LDAP directory](https://en.wikipedia.org/wiki/LDAP). To use this feature, an LDAP directory service must be deployed and accessible from the {{ ydb-short-name }} servers.
+
+Examples of supported LDAP implementations include [OpenLDAP](https://openldap.org/) and [Active Directory](https://azure.microsoft.com/en-us/products/active-directory/).
+
+### Authentication
+
+Authentication using the LDAP protocol is similar to the static credentials authentication process (using a login and password). The difference is that the LDAP directory acts as the authentication component. The LDAP directory is used solely to verify the login/password pair.
+
+{% note info %}
+
+Since the LDAP directory is an external, independent service, {{ ydb-short-name }} cannot manage user accounts within it. For successful authentication, the user must already exist in the LDAP directory. The commands `CREATE USER`, `CREATE GROUP`, `ALTER USER`, `ALTER GROUP`, `DROP USER`, and `DROP GROUP` do not affect the list of users and groups in the LDAP directory. Information on managing accounts should be found in the documentation for the specific LDAP directory implementation in use.
+
+{% endnote %}
+
+Currently, {{ ydb-short-name }} supports only one method of LDAP authentication, known as the `search+bind` method, which involves several steps. Upon receiving the username and password of the user being authenticated, a *bind* operation is performed using the credentials of a special service account specified in the [ldap_authentication](../reference/configuration/index.md#ldap-auth-config) section. These credentials are defined by the **bind_dn** and **bind_password** configuration parameters. After the service account is successfully authenticated, a search is conducted in the LDAP directory for the user attempting to authenticate in the system. The *search* operation is performed across the entire subtree rooted at the location specified by the **base_dn** configuration parameter and uses the filter defined in the **search_filter** configuration parameter.
+
+Once the user entry is found, {{ ydb-short-name }} performs another *bind* operation using the found user's entry and the password provided earlier. The success of this second *bind* operation determines whether the user authentication is successful.
+
+After successful authentication, a token is generated. This token is then used in place of the username and password, speeding up the authentication process and enhancing security.
+
+{% note info %}
+
+When using LDAP authentication, no user passwords are stored in {{ ydb-short-name }}.
+
+{% endnote %}
+
+### Token verification
+
+After a user is authenticated in the system, a token is generated and verified before executing the requested operation. During the token verification process, the system determines on whose behalf the action is being requested and identifies the groups the user belongs to. For users from the LDAP directory, the token does not include information about group memberships. Therefore, after the token is verified, an additional query is made to the LDAP server to retrieve the list of groups the user is a member of.
+
+Groups, like users, are entities that can have assigned access rights to perform operations on database schema objects and other resources. These assigned rights determine which operations a user is authorized to perform.
+
+The process of retrieving a user's group list from an LDAP directory is similar to the steps taken during authentication. First, a *bind* operation is performed using the service user credentials specified by the **bind_dn** and **bind_password** parameters in the [ldap_authentication](../reference/configuration/index.md#ldap-auth-config) section of the configuration file. After successful authentication, a search is conducted for the user entry associated with the previously generated token. This search uses the **search_filter** parameter. If the user still exists, the result of the *search* operation will be a list of attribute values specified by the **requested_group_attribute** parameter. If this parameter is not set, the *memberOf* attribute is used as the default for reverse group membership. The *memberOf* attribute contains the distinguished names (DNs) of the groups to which the user belongs.
+
+#### Group search
+
+By default, {{ ydb-short-name }} only searches for groups in which the user is a direct member. However, by enabling the **extended_settings.enable_nested_groups_search** flag in the [ldap_authentication](../reference/configuration/index.md#ldap-auth-config) section, {{ ydb-short-name }} will attempt to retrieve groups at all levels of nesting, not just those the user directly belongs to. If {{ ydb-short-name }} is configured to work with Active Directory, the Active Directory-specific matching rule [LDAP_MATCHING_RULE_IN_CHAIN](https://learn.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax?redirectedfrom=MSDN) will be used to find all nested groups. This rule allows for the retrieval of all nested groups with a single query. For LDAP servers based on OpenLDAP, group searches will be conducted using recursive graph traversal, which generally requires multiple queries. In both Active Directory and OpenLDAP configurations, the group search is performed only within the subtree specified by the **base_dn** parameter.
+
+{% note info %}
+
+In the current implementation, the group names that {{ ydb-short-name }} uses match the values stored in the *memberOf* attribute. These names can be long and difficult to read.
+
+Example:
+
+```text
+cn=Developers,ou=Groups,dc=mycompany,dc=net@ldap
+```
+
+{% endnote %}
+
+{% note info %}
+
+In the configuration file section that specifies authentication information, the refresh rate for user and group information can be set using the **refresh_time** parameter. For more detailed information about configuration files, refer to the [cluster configuration](../reference/configuration/index.md#auth-config) section.
+
+{% endnote %}
+
+{% note warning %}
+
+It should be noted that currently, {{ ydb-short-name }} does not have the capability to track group renaming on the LDAP server side. Consequently, a group with a new name will not retain the rights assigned to the group under its previous name.
+
+{% endnote %}
+
+### LDAP users and groups in {{ ydb-short-name }}
+
+Since {{ ydb-short-name }} supports various methods of user authentication (login and password authentication, IAM provider usage, LDAP directory), it is often helpful to identify the specific source of authentication when handling user and group names. For all authentication types except login and password, a suffix in the format `<username>@<domain>` is appended to user and group names.
+
+For LDAP users, the `<domain>` is determined by the **ldap_authentication_domain** configuration parameter in the [configuration section](../reference/configuration/index.md#ldap-auth-config). By default, this parameter is set to `ldap`, so all usernames authenticated through the LDAP directory, as well as their corresponding group names in {{ ydb-short-name }}, will follow this format:
+
+- `user1@ldap`
+- `group1@ldap`
+- `group2@ldap`
+
+{% note warning %}
+
+To indicate that the entered login should be recognized as a username from the LDAP directory, rather than for login and password authentication, you need to append the LDAP authentication domain suffix. This suffix is specified through the **ldap_authentication_domain** configuration parameter.
+
+Below are examples of authenticating the user `user1` using the [{{ ydb-short-name }} CLI](../reference/ydb-cli/index.md):
+
+* Authentication of a user from the LDAP directory: `ydb --user user1@ldap -p ydb_profile scheme ls`
+* Authentication of a user using the internal {{ ydb-short-name }} mechanism: `ydb --user user1 -p ydb_profile scheme ls`
+
+{% endnote %}
+
+### TLS connection {#ldap-tls}
+
+Depending on the specified configuration parameters, {{ ydb-short-name }} can establish either an encrypted or unencrypted connection. An encrypted connection with the LDAP server is established using the TLS protocol, which is recommended for production clusters. There are two ways to enable a TLS connection:
+
+* Automatically via the [`ldaps`](#ldaps) connection scheme.
+* Using the [`StartTls`](#starttls) LDAP protocol extension*.
+
+When using an unencrypted connection, all data transmitted in requests to the LDAP server, including passwords, will be sent in plain text. This method is easier to set up and is more suited for experimentation or testing purposes.
+
+#### LDAPS {#ldaps}
+
+To have {{ ydb-short-name }} automatically establish an encrypted connection with the LDAP server, the **scheme** value in the [configuration parameter](../reference/configuration/index.md#ldap-auth-config) should be set to `ldaps`. The TLS handshake will be initiated on the port specified in the configuration. If no port is specified, the default port 636 will be used for the `ldaps` scheme. The LDAP server must be configured to accept TLS connections on the specified ports.
+
+#### LDAP protocol extension `StartTls` {#starttls}
+
+`StartTls` is an LDAP protocol extension that enables message encryption using the TLS protocol. It allows a combination of encrypted and plain-text message transmission within a single connection to the LDAP server. {{ ydb-short-name }} sends a `StartTls` request to the LDAP server to initiate a TLS connection. In {{ ydb-short-name }}, enabling or disabling TLS within an active session is not supported. Therefore, once an encrypted connection is established using `StartTls`, all subsequent messages sent to the LDAP server will be encrypted. One advantage of using this extension, provided the LDAP server is appropriately configured, is the capability to initiate a TLS connection over an unencrypted port. The extension can be enabled in the [`use_tls` section](../reference/configuration/index.md#ldap-auth-config) of the configuration file.
diff --git a/ydb/docs/en/core/reference/configuration/index.md b/ydb/docs/en/core/reference/configuration/index.md
index df20a3929f4..02db6042329 100644
--- a/ydb/docs/en/core/reference/configuration/index.md
+++ b/ydb/docs/en/core/reference/configuration/index.md
@@ -601,6 +601,62 @@ blob_storage_config:
 
 For a configuration located in 3 availability zones, specify 3 rings. For a configuration within a single availability zone, specify exactly one ring.
 
+## Configuring authentication providers {#auth-config}
+
+{{ ydb-short-name }} supports various user authentication methods. The configuration for authentication providers is specified in the `auth_config` section.
+
+### Configuring LDAP authentication {#ldap-auth-config}
+
+One of the user authentication methods in {{ ydb-short-name }} is with an LDAP directory. More details about this type of authentication can be found in the section on [interacting with the LDAP directory](../../concepts/auth.md#ldap-auth-provider). To configure LDAP authentication, the `ldap_authentication` section must be defined.
+
+Example of the `ldap_authentication` section:
+
+```yaml
+auth_config:
+  #...
+  ldap_authentication:
+    hosts:
+      - "ldap-hostname-01.example.net"
+      - "ldap-hostname-02.example.net"
+      - "ldap-hostname-03.example.net"
+    port: 389
+    base_dn: "dc=mycompany,dc=net"
+    bind_dn: "cn=serviceAccaunt,dc=mycompany,dc=net"
+    bind_password: "serviceAccauntPassword"
+    search_filter: "uid=$username"
+    use_tls:
+      enable: true
+      ca_cert_file: "/path/to/ca.pem"
+      cert_require: DEMAND
+  ldap_authentication_domain: "ldap"
+  scheme: "ldap"
+  requested_group_attribute: "memberOf"
+  extended_settings:
+      enable_nested_groups_search: true
+
+  refresh_time: "1h"
+  #...
+```
+
+| Parameter | Description |
+| --- | --- |
+| `hosts` | A list of hostnames where the LDAP server is running. |
+| `port` | The port used to connect to the LDAP server. |
+| `base_dn` | The root of the subtree in the LDAP directory from which the user entry search begins. |
+| `bind_dn` | The Distinguished Name (DN) of the service account used to search for the user entry. |
+| `bind_password` | The password for the service account used to search for the user entry. |
+| `search_filter` | A filter for searching the user entry in the LDAP directory. The filter string can include the sequence *$username*, which is replaced with the username requested for authentication in the database. |
+| `use_tls` | Configuration settings for the TLS connection between {{ ydb-short-name }} and the LDAP server. |
+| `enable` | Determines if a TLS connection [using the `StartTls` request](../../concepts/auth.md#starttls) will be attempted. When set to `true`, the `ldaps` connection scheme should be disabled by setting `ldap_authentication.scheme` to `ldap`. |
+| `ca_cert_file` | The path to the certification authority's certificate file. |
+| `cert_require` | Specifies the certificate requirement level for the LDAP server.<br>Possible values:<ul><li>`NEVER` - {{ ydb-short-name }} does not request a certificate or accepts any presented certificate.</li><li>`ALLOW` - {{ ydb-short-name }} requests a certificate from the LDAP server but will establish the TLS session even if the certificate is not trusted.</li><li>`TRY` - {{ ydb-short-name }} requires a certificate from the LDAP server and terminates the connection if it is not trusted.</li><li>`DEMAND`/`HARD` - These are equivalent to `TRY` and are the default setting, with the value set to `DEMAND`.</li></ul> |
+| `ldap_authentication_domain` | An identifier appended to the username to distinguish LDAP directory users from those authenticated using other providers. The default value is `ldap`. |
+| `scheme` | The connection scheme to the LDAP server.<br>Possible values:<ul><li>`ldap` - Connects without encryption, sending passwords in plain text. This is the default value.</li><li>`ldaps` - Connects using TLS encryption from the first request. To use `ldaps`, disable the [`StartTls` request](../../concepts/auth.md#starttls) by setting `ldap_authentication.use_tls.enable` to `false`, and provide certificate details in `ldap_authentication.use_tls.ca_cert_file` and set the certificate requirement level in `ldap_authentication.use_tls.cert_require`.</li><li>Any other value defaults to `ldap`.</li></ul> |
+| `requested_group_attribute` | The attribute used for reverse group membership. The default is `memberOf`. |
+| `extended_settings.enable_nested_groups_search` | A flag indicating whether to perform a request to retrieve the full hierarchy of groups to which the user's direct groups belong. |
+| `host` | The hostname of the LDAP server. This parameter is deprecated and should be replaced with the `hosts` parameter. |
+| `refresh_time` | Specifies the interval for refreshing user information. The actual update will occur within the range from `refresh_time/2` to `refresh_time`. |
+
 ## Enabling stable node names {#node-broker-config}
 
 Node names are assigned through the Node Broker, which is a system tablet that registers dynamic nodes in the {{ ydb-short-name }} cluster.