docs: LDAP user provider (#1202)

Co-authored-by: Ning Sun <[email protected]>
Co-authored-by: Yiran <[email protected]>

docs/getting-started/quick-start.md

@@ -12,7 +12,7 @@ In this quick start document, we use SQL for simplicity.
 If your GreptimeDB instance is running on `127.0.0.1` with the MySQL client default port `4002` or the PostgreSQL client default port `4003`,
 you can connect to GreptimeDB using the following commands.
 
-By default, GreptimeDB does not have [authentication](/user-guide/deployments/authentication.md) enabled.
+By default, GreptimeDB does not have [authentication](/user-guide/deployments/authentication/overview.md) enabled.
 You can connect to the database without providing a username and password in this section.
 
 ```shell

docs/reference/command-lines.md

@@ -105,7 +105,7 @@ greptime frontend start --help
 - `--tls-cert-path <TLS_CERT_PATH>`: The TLS public key file path;
 - `--tls-key-path <TLS_KEY_PATH>`: The TLS private key file path;
 - `--tls-mode <TLS_MODE>`: TLS Mode;
-- `--user-provider <USER_PROVIDER>`: You can refer [authentication](/user-guide/deployments/authentication.md);
+- `--user-provider <USER_PROVIDER>`: You can refer [authentication](/user-guide/deployments/authentication/overview.md);
 
 ### Flownode subcommand options
 

docs/user-guide/deployments/authentication/ldap.md

@@ -0,0 +1,87 @@
+# LDAP User Provider
+
+:::tip NOTE
+
+**LDAP user provider is only available in GreptimeDB Enterprise.**
+
+:::
+
+## Configuration
+
+GreptimeDB can connect to an external LDAP server to authenticate users. Similar to [LDAP in PostgreSQL](https://www.postgresql.org/docs/current/auth-ldap.html), in GreptimeDB, LDAP authentication is
+operated in two modes: "simple bind" and "search bind", too.
+
+In the "simple bind" mode, GreptimeDB will bind to the "DN"(distinguished name) constructed as
+`{prefix}{username}{suffix}`. Typically, the `prefix` parameter is used to specify `cn=`, and the `suffix` is used to
+specify the remaining part of the DN. The `username`, of course, is provided by the client.
+
+Here's the configuration file example for the "simple bind" mode in GreptimeDB's LDAP user provider:
+
+```toml
+# Name or IP address of the LDAP server to connect to.
+server = "127.0.0.1"
+# Port number on LDAP server to connect to.
+port = 636
+# Set to "ldap" to use LDAP, "ldaps" to use LDAPS.
+# The connection between GreptimeDB and the LDAP server starts as an initially unencrypted one,
+# then upgrades to TLS as the first action against the server, per the LDAPv3 standard ("StartTLS").
+scheme = "ldaps"
+
+# The authentication mode to the LDAP server, either `bind = "simple"` or `bind = "search"`.
+[auth_mode]
+# The following options are used in simple bind mode only:
+bind = "simple"
+# String to prepend to the username when forming the DN to bind as, when doing simple bind authentication.
+prefix = "cn="
+# String to append to the username when forming the DN to bind as, when doing simple bind authentication.
+suffix = ",dc=example,dc=com"
+```
+
+In the "search bind" mode, GreptimeDB will first try to bind to the LDAP directory with a fixed username and password,
+which are set in the configuration file (`bind_dn` and `bind_passwd`), Then GreptimeDB performs a search for the user
+trying to log in to the database. The search will be performed over the subtree at `base_dn`, filtered by the
+`search_filter`, and will try to do an exact match of the attribute specified in `search_attribute`. Once the user has
+been found in this search, GreptimeDB re-binds to the directory as this user, using the password specified by the
+client, to verify that the login is correct. This method allows for significantly more flexibility in where the user
+objects are located in the directory, but will cause two additional requests to the LDAP server to be made.
+
+The following toml snippets show the configuration file example for the "search bind" mode in GreptimeDB's LDAP user
+provider. The common parts of `server`, `port`, and `scheme` as shown in the "simple bind" mode configuration file above
+are omitted:
+
+```toml
+[auth_mode]
+# The following options are used in search bind mode only:
+bind = "search"
+# Root DN to begin the search for the user in, when doing search bind authentication.
+base_dn = "ou=people,dc=example,dc=com"
+# DN of user to bind to the directory with to perform the search when doing search bind authentication.
+bind_dn = "cn=admin,dc=example,dc=com"
+# Password for user to bind to the directory with to perform the search when doing search bind authentication.
+bind_passwd = "secret"
+# Attribute to match against the username in the search when doing search bind authentication.
+# If no attribute is specified, the uid attribute will be used.
+search_attribute = "cn"
+# The search filter to use when doing search bind authentication.
+# Occurrences of "$username" will be replaced with the username.
+# This allows for more flexible search filters than search_attribute.
+search_filter = "(cn=$username)"
+```
+
+## Use LDAP user provider in GreptimeDB
+
+To use the LDAP user provider, first config your LDAP authentication mode like above, then start GreptimeDB with the
+`--user-provider` parameter set to `ldap_user_provider:<path to your ldap configuration file>`. For example, if you have
+a configuration file `/home/greptimedb/ldap.toml`, you can start a GreptimeDB standalone server with the following
+command:
+
+```shell
+greptime standalone start --user-provider=ldap_user_provider:/home/greptimedb/ldap.toml
+```
+
+Now you can create a connection to GreptimeDB using your LDAP user accounts.
+
+:::tip NOTE
+If you are using the MySQL CLI to connect to GreptimeDB that is configured with LDAP user provider, you need
+to specify the `--enable-cleartext-plugin` in the MySQL CLI.
+:::

docs/user-guide/deployments/authentication/overview.md

@@ -0,0 +1,10 @@
+# Authentication
+
+Authentication occurs when a user attempts to connect to the database. In GreptimeDB, users are authenticated by "user
+provider"s. There are various implementations of user providers in GreptimeDB:
+
+- [Static user provider](./static.md): A simple built-in user provider implementation that finds users from a static
+  file.
+- [LDAP user provider](./ldap.md): **Enterprise feature.** A user provider implementation that authenticates users against an external LDAP
+  server.
+

docs/user-guide/deployments/authentication.md → docs/user-guide/deployments/authentication/static.md

@@ -1,6 +1,6 @@
-# Authentication
+# Static User Provider
 
-Authentication occurs when a user attempts to connect to the database. GreptimeDB offers a simple built-in mechanism for authentication, allowing users to configure either a fixed account for convenient usage or an account file for multiple user accounts. By passing in a file, GreptimeDB loads all users listed within it.
+GreptimeDB offers a simple built-in mechanism for authentication, allowing users to configure either a fixed account for convenient usage or an account file for multiple user accounts. By passing in a file, GreptimeDB loads all users listed within it.
 
 GreptimeDB reads the user and password on each line using `=` as a separator, just like a command-line config. For example:
 

docs/user-guide/deployments/overview.md

@@ -6,7 +6,7 @@ Before deploying GreptimeDB, you need to [configure the server](configuration.md
 
 ## Authentication
 
-By default, GreptimeDB does not have authentication enabled. Learn how to [configure authentication](authentication.md) for your deployment manually.
+By default, GreptimeDB does not have authentication enabled. Learn how to [configure authentication](./authentication/overview.md) for your deployment manually.
 
 ## Deploy on Kubernetes
 

docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md

@@ -16,7 +16,7 @@ For more information, refer to [Automatic Schema Generation](/user-guide/ingest-
 
 ## Connect to database
 
-If you have set the [`--user-provider` configuration](/user-guide/deployments/authentication.md) when starting GreptimeDB,
+If you have set the [`--user-provider` configuration](/user-guide/deployments/authentication/overview.md) when starting GreptimeDB,
 you will need to provide a username and password to connect to GreptimeDB.
 The following example shows how to set the username and password when using the library to connect to GreptimeDB.
 

docs/user-guide/ingest-data/for-iot/influxdb-line-protocol.md

@@ -73,7 +73,7 @@ curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public" \
 #### Authentication
 
 GreptimeDB is compatible with InfluxDB's line protocol authentication format, both V1 and V2.
-If you have [configured authentication](/user-guide/deployments/authentication.md) in GreptimeDB, you need to provide the username and password in the HTTP request.
+If you have [configured authentication](/user-guide/deployments/authentication/overview.md) in GreptimeDB, you need to provide the username and password in the HTTP request.
 
 <Tabs>
 

docs/user-guide/ingest-data/for-observerbility/prometheus.md

@@ -26,7 +26,7 @@ remote_read:
 
 - The host and port in the URL represent the GreptimeDB server. In this example, the server is running on `localhost:4000`. You can replace it with your own server address. For the HTTP protocol configuration in GreptimeDB, please refer to the [protocol options](/user-guide/deployments/configuration.md#protocol-options).
 - The `db` parameter in the URL represents the database to which we want to write data. It is optional. By default, the database is set to `public`.
-- `basic_auth` is the authentication configuration. Fill in the username and password if GreptimeDB authentication is enabled. Please refer to the [authentication document](/user-guide/deployments/authentication.md).
+- `basic_auth` is the authentication configuration. Fill in the username and password if GreptimeDB authentication is enabled. Please refer to the [authentication document](/user-guide/deployments/authentication/overview.md).
 
 ## Data Model
 

docs/user-guide/integrations/metabase.md

@@ -23,6 +23,6 @@ information.
 - Use Greptime's Postgres protocol port `4003` as port. If you changed the
   defaults, use you own settings.
 - Username and password are optional if you didn't enable
-  [authentication](/user-guide/deployments/authentication.md).
+  [authentication](/user-guide/deployments/authentication/overview.md).
 - Use `public` as default *Database name*. When using GreptimeCloud instance,
   use the database name from your instance.

docs/user-guide/integrations/superset.md

@@ -47,7 +47,7 @@ greptimedb://<username>:<password>@<host>:<port>/<database>
 ```
 
 - Ignore `<username>:<password>@` if you don't have
-  [authentication](/user-guide/deployments/authentication.md) enabled.
+  [authentication](/user-guide/deployments/authentication/overview.md) enabled.
 - Use `4003` for default port (this extension uses Postgres protocol).
 - Use `public` as default `database`. When using GreptimeCloud instance, use the
   database name from your instance.

docs/user-guide/protocols/mysql.md

@@ -8,7 +8,7 @@ You can connect to GreptimeDB using MySQL via port `4002`.
 mysql -h <host> -P 4002 -u <username> -p
 ```
 
-- For how to setup username and password for GreptimeDB, please refer to [Authentication](/user-guide/deployments/authentication.md).
+- For how to setup username and password for GreptimeDB, please refer to [Authentication](/user-guide/deployments/authentication/overview.md).
 - If you want to use other ports for MySQL, please refer to [Protocol options](/user-guide/deployments/configuration.md#protocol-options) in the configuration document.
 
 

docs/user-guide/protocols/postgresql.md

@@ -9,7 +9,7 @@ Simply add the `-U` argument to your command, followed by your username and pass
 psql -h <host> -p 4003 -U <username> -d public
 ```
 
-- For how to setup username and password for GreptimeDB, please refer to [Authentication](/user-guide/deployments/authentication.md).
+- For how to setup username and password for GreptimeDB, please refer to [Authentication](/user-guide/deployments/authentication/overview.md).
 - If you want to use other ports for PostgreSQL, please refer to [Protocol options](/user-guide/deployments/configuration.md#protocol-options) in the configuration document.
 
 

i18n/zh/docusaurus-plugin-content-docs/current/getting-started/quick-start.md

@@ -13,7 +13,7 @@ GreptimeDB 支持[多种协议](/user-guide/protocols/overview.md)与数据库
 并且使用 MySQL 客户端默认端口 `4002` 或 PostgreSQL 客户端默认端口 `4003`，
 你可以使用以下命令连接到数据库。
 
-GreptimeDB 默认不开启[鉴权认证](/user-guide/deployments/authentication.md)。
+GreptimeDB 默认不开启[鉴权认证](/user-guide/deployments/authentication/overview.md)。
 在本章节中你可以在连接数据库时不提供用户名密码。
 
 ```shell

i18n/zh/docusaurus-plugin-content-docs/current/reference/command-lines.md

@@ -105,7 +105,7 @@ greptime frontend start --help
 - `--tls-cert-path <TLS_CERT_PATH>`: TLS 公钥文件地址
 - `--tls-key-path <TLS_KEY_PATH>`: TLS 私钥文件地址
 - `--tls-mode <TLS_MODE>`: TLS 模式
-- `--user-provider <USER_PROVIDER>`: 参考 [鉴权](/user-guide/deployments/authentication.md);
+- `--user-provider <USER_PROVIDER>`: 参考 [鉴权](/user-guide/deployments/authentication/overview.md);
 
 
 ### Flownode 子命令选项

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/authentication/ldap.md

@@ -0,0 +1,81 @@
+# LDAP User Provider
+
+:::tip NOTE
+
+**LDAP user provider 是 GreptimeDB 企业版的功能。**
+
+:::
+
+## 配置
+
+GreptimeDB 可以使用外部 LDAP 服务以验证用户。与 [PostgreSQL 中的 LDAP 机制相似](https://www.postgresql.org/docs/current/auth-ldap.html)， 在 GreptimeDB 中，LDAP 鉴权也分为两种模式："simple bind" 和 "search bind"。
+
+在 "simple bind" 模式下，GreptimeDB 会构造一个格式为 `{prefix}{username}{suffix}` 的 "DN"(distinguished name)
+，并使用客户端传来的密码向 LDAP 服务发起”绑定 (bind)“。绑定的结果就是鉴权的结果。一个典型配置是，`prefix` 参数指定 `cn=`，
+`suffix` 用于指定 DN 的其余部分。`username` 将会被替换为客户端发来的用户名。
+
+以下一个 LDAP user provider "simple bind" 模式的配置文件示例：
+
+```toml
+# LDAP 服务地址。
+server = "127.0.0.1"
+# LDAP 服务端口。
+port = 636
+# 设置为 "ldap" 以使用 LDAP scheme，"ldaps" 以使用 LDAPS。
+# GreptimeDB 和 LDAP 服务之间的连接一开始时是未加密的。连接建立后升级到 TLS。这是 LDAPv3 的 "StartTLS" 标准。
+scheme = "ldaps"
+
+# LDAP 鉴权模式。`bind = "simple"` 和 `bind = "search"` 只能选择其一。
+[auth_mode]
+# 以下配置仅在 simple bind 模式下使用：
+bind = "simple"
+# 当进行 simple bind 鉴权时，用于构造绑定 DN 的前缀。
+prefix = "cn="
+# 当进行 simple bind 鉴权时，用于构造绑定 DN 的后缀。
+suffix = ",dc=example,dc=com"
+```
+
+在 "search bind" 模式中，GreptimeDB 首先会使用配置文件中设置的固定用户名和密码（`bind_dn` 和 `bind_passwd`）尝试绑定到 LDAP
+目录。然后 GreptimeDB 会在 LDAP 目录中搜索尝试登录到数据库的用户。搜索将在 `base_dn` 下的子树中进行，由 `search_filter`
+过滤，并尝试对 `search_attribute` 中指定的属性进行精确匹配。一旦在搜索中找到用户，GreptimeDB
+会以此用户重新绑定到目录，使用客户端指定的密码，以验证登录是否正确。这种方法允许用户对象在 LDAP 目录中的位置更加灵活，但会导致向
+LDAP 服务器发出两个额外的请求。
+
+以下 toml 片段展示了 GreptimeDB LDAP user provider "search bind" 模式的配置文件示例。在上面的 "simple bind" 模式配置文件中显示的
+`server`、`port` 和 `scheme` 的公共部分被省略了：
+
+```toml
+[auth_mode]
+# 以下配置仅在 search bind 模式下使用：
+bind = "search"
+# 进行 search bind 鉴权时，开始搜索用户的根 DN。
+base_dn = "ou=people,dc=example,dc=com"
+# 进行 search bind 鉴权时，首先进行绑定的用户 DN。
+bind_dn = "cn=admin,dc=example,dc=com"
+# 进行 search bind 鉴权时，首先进行绑定的用户密码。
+bind_passwd = "secret"
+# 进行 search bind 鉴权时，用于匹配的用户属性。
+# 如果未指定属性，则将使用 uid 属性。
+search_attribute = "cn"
+# 进行 search bind 鉴权时，使用的搜索过滤器。
+# "$username" 将被替换为客户端传来的用户名。
+# 这允许比 search_attribute 更灵活的用户搜索。
+search_filter = "(cn=$username)"
+```
+
+## 在 GreptimeDB 中使用 LDAP User Provider
+
+要使用 LDAP User Provider，首先参照上文配置你的 LDAP 鉴权模式，然后在启动 GreptimeDB 时使用 `--user-provider` 参数，将其设置为
+`ldap_user_provider:<ldap 配置文件路径>`。例如，如果你有一个配置文件是 `/home/greptimedb/ldap.toml`，你可以使用以下命令启动一个
+standalone GreptimeDB：
+
+```shell
+greptime standalone start --user-provider=ldap_user_provider:/home/greptimedb/ldap.toml
+```
+
+现在你就可以使用你的 LDAP 用户账户创建一个连接到 GreptimeDB 了。
+
+:::tip 注意
+如果你使用 MySQL CLI 连接到配置了 LDAP User Provider 的 GreptimeDB，你需要在 MySQL CLI 中指定
+`--enable-cleartext-plugin`。
+:::

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/authentication/overview.md

@@ -0,0 +1,8 @@
+# 鉴权
+
+当客户端尝试连接到数据库时，将会进行身份验证。GreptimeDB 通过 “user provider” 进行身份验证。GreptimeDB 中有多种 user
+provider 实现：
+
+- [Static user provider](./static.md)：一个简单的内置 user provider 实现，从静态文件中查找用户。
+- [LDAP user provider](./ldap.md)：**企业版功能。**使用外部 LDAP 服务进行用户身份验证。
+

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/authentication.md → i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/authentication/static.md

@@ -1,6 +1,6 @@
-# 鉴权
+# Static User Provider
 
-当用户尝试连接到数据库时，将会进行身份验证。 GreptimeDB 提供了简单的内置身份验证机制，允许用户配置一个固定的帐户以方便使用，或者配置一个帐户文件以支持多个用户帐户。通过传入文件，GreptimeDB 会加载其中的所有用户。
+GreptimeDB 提供了简单的内置身份验证机制，允许用户配置一个固定的帐户以方便使用，或者配置一个帐户文件以支持多个用户帐户。通过传入文件，GreptimeDB 会加载其中的所有用户。
 
 GreptimeDB使用`=`作为分隔符，读取文件内每行中的用户和密码。例如：
 

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/overview.md

@@ -8,7 +8,7 @@
 ## 鉴权
 
 GreptimeDB 默认不启用鉴权认证。
-了解如何为你的部署手动[配置鉴权](authentication.md)。
+了解如何为你的部署手动[配置鉴权](./authentication/overview.md)。
 
 ## 部署到 Kubernetes
 

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-iot/grpc-sdks/template.md

@@ -15,7 +15,7 @@ GreptimeDB 提供了用于高吞吐量数据写入的 ingester 库。
 
 ## 连接数据库
 
-如果你在启动 GreptimeDB 时设置了 [`--user-provider`](/user-guide/deployments/authentication.md)，
+如果你在启动 GreptimeDB 时设置了 [`--user-provider`](/user-guide/deployments/authentication/overview.md)，
 则需要提供用户名和密码才能连接到 GreptimeDB。
 以下示例显示了使用 SDK 连接到 GreptimeDB 时如何设置用户名和密码。
 

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-iot/influxdb-line-protocol.md

@@ -73,7 +73,7 @@ curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public" \
 #### 鉴权
 
 GreptimeDB 与 InfluxDB 的行协议鉴权格式兼容，包括 V1 和 V2。
-如果你在 GreptimeDB 中[配置了鉴权](/user-guide/deployments/authentication.md)，需要在 HTTP 请求中提供用户名和密码。
+如果你在 GreptimeDB 中[配置了鉴权](/user-guide/deployments/authentication/overview.md)，需要在 HTTP 请求中提供用户名和密码。
 
 <Tabs>
 

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observerbility/prometheus.md

@@ -25,7 +25,7 @@ remote_read:
 
 - URL 中的 host 和 port 表示 GreptimeDB 服务器。在此示例中，服务器运行在 `localhost:4000` 上。你可以将其替换为你自己的服务器地址。有关 GreptimeDB 中 HTTP 协议的配置，请参阅 [协议选项](/user-guide/deployments/configuration.md#protocol-options)。
 - URL 中的 `db` 参数表示要写入的数据库。它是可选的。默认情况下，数据库设置为 `public`。
-- `basic_auth` 是身份鉴权配置。如果 GreptimeDB 启用了鉴权，请填写用户名和密码。请参阅 [鉴权认证文档](/user-guide/deployments/authentication.md)。
+- `basic_auth` 是身份鉴权配置。如果 GreptimeDB 启用了鉴权，请填写用户名和密码。请参阅 [鉴权认证文档](/user-guide/deployments/authentication/overview.md)。
 
 ## 数据模型
 

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/integrations/metabase.md

@@ -19,7 +19,7 @@
 进一步添加其他数据库信息：
 
 - 端口请填写 GreptimeDB 的 Postgres 协议端口 `4003`。
-- 如果没有开启[认证](/user-guide/deployments/authentication.md)，用户名和密码字段
+- 如果没有开启[认证](/user-guide/deployments/authentication/overview.md)，用户名和密码字段
   是可选的。
 - 默认填写 `public` 作为 *数据库名*。如果是使用 GreptimeCloud 的实例，可以从控制
   台复制数据库名称。