From 8a8fd962e19abd8e44ac22afd6c6a9a0a7c3f2a2 Mon Sep 17 00:00:00 2001
From: silenceqi <silenceqi@hotmail.com>
Date: Fri, 24 Jan 2025 15:24:51 +0800
Subject: [PATCH] docs: Update LDAP integration documentation (#99)

---
 .../docs/configuration/security/_index.md     | 75 +++++++++++++++++++
 .../docs/configuration/security/_index.md     |  2 +
 2 files changed, 77 insertions(+)
 create mode 100644 docs/content.en/docs/configuration/security/_index.md

diff --git a/docs/content.en/docs/configuration/security/_index.md b/docs/content.en/docs/configuration/security/_index.md
new file mode 100644
index 00000000..2a0150ee
--- /dev/null
+++ b/docs/content.en/docs/configuration/security/_index.md
@@ -0,0 +1,75 @@
+---
+weight: 3
+title: LDAP Integration
+---
+
+# LDAP Configuration
+
+## Description
+
+In certain scenarios, after a user is authenticated through a realm, we may want to delegate user lookup and role assignment to another realm. Any realm that supports user lookup (without requiring user credentials) can be used as an authentication realm.
+
+For example, a user authenticated through a Kerberos realm can be looked up in an LDAP realm. The LDAP realm is responsible for searching for the user in LDAP and determining their roles. In this case, the LDAP realm acts as an authentication realm.
+
+## Configuration Example
+
+A reference configuration example is as follows:
+
+```
+security:
+  enabled: true
+  authc:
+    realms:
+      ldap:
+        myprovider1:
+          enabled: true
+          host: "localhost"
+          port: 3893
+          bind_dn: "cn=serviceuser,ou=svcaccts,dc=glauth,dc=com"
+          bind_password: "mysecret"
+          base_dn: "dc=glauth,dc=com"
+          user_filter: "(cn=%s)"
+          group_attribute: "ou"
+          bypass_api_key: true
+          cache_ttl: "10s"
+          role_mapping:
+            group:
+              superheros: [ "Administrator" ]
+            uid:
+              hackers: [ "Administrator" ]
+        myprovider2:
+          enabled: true
+          host: "ldap.forumsys.com"
+          port: 389
+          bind_dn: "cn=read-only-admin,dc=example,dc=com"
+          bind_password: "password"
+          base_dn: "dc=example,dc=com"
+          user_filter: "(uid=%s)"
+          cache_ttl: "10s"
+          role_mapping:
+            uid:
+              tesla: [ "readonly","data" ]
+```
+
+The above configuration uses two external LDAP servers named `myprovider1` and `myprovider2` as authentication sources. Either LDAP server can provide authentication services. The `role_mapping` settings associate the UID and Group returned by LDAP with roles in the INFINI Console.
+## Parameter Description
+
+| Name               | Type   | Description                                            |
+|--------------------|--------| ----------------------------------------------- |
+| host               | string | LDAP server address                               |
+| port               | int    | LDAP server port, default is `389`                     |
+| tls                | bool   | Whether the LDAP server uses TLS, default is `false` |
+| bind_dn            | string | User information for executing LDAP queries                        |
+| bind_password      | string | Password for executing LDAP queries                        |
+| base_dn            | string | Root domain for filtering LDAP users                            |
+| user_filter        | string | Query condition for filtering LDAP users, default is `(uid=%s)`       |
+| uid_attribute      | string | Attribute used for user ID, default is `uid`                  |
+| group_attribute    | string | Attribute used for user groups, default is `cn`                     |
+| role_mapping.uid   | map    | Permission mapping based on user UID                     |
+| role_mapping.group | map    | Permission mapping based on user Group                   |
+
+> Note: If the `uid` or `group` values in `role_mapping` contain ., please upgrade INFINI Console to version `1.28.1` or later.
+
+## Additional Resources
+* [INFINI Console LDAP Configuration Tutorial](https://www.bilibili.com/video/BV1kj411S74B/) Video Introduction
+* [FAQ](https://www.infinilabs.cn/blog/2023/console-ldap-setting/)
\ No newline at end of file
diff --git a/docs/content.zh/docs/configuration/security/_index.md b/docs/content.zh/docs/configuration/security/_index.md
index 84bd05a6..75f6044b 100644
--- a/docs/content.zh/docs/configuration/security/_index.md
+++ b/docs/content.zh/docs/configuration/security/_index.md
@@ -69,6 +69,8 @@ security:
 | role_mapping.uid   | map    | 用于基于用户 UID 的权限映射                      |
 | role_mapping.group | map    | 用于基于用户 Group 的权限映射                    |
 
+> 注意：如果 `role_mapping` 中的 `uid` 或 `group` 的配置值包含 .，请更新 INFINI Console 至 `1.28.1` 或更高版本。
+
 ## 其他资源
 * [INFINI Console LDAP 配置教程](https://www.bilibili.com/video/BV1kj411S74B/) 视频介绍
 * [常见问题](https://www.infinilabs.cn/blog/2023/console-ldap-setting/)
\ No newline at end of file