Azure AD LDAP

注意

本教程为社区贡献，Open WebUI 团队不提供官方支持。它仅作为如何针对您的特定使用场景自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

本指南介绍了如何将 Open WebUI 与 Azure AD Domain Services (AAD DS) 集成，以实现安全 LDAP (LDAPS) 身份验证。

1. 前提条件

项目	描述
Azure 账户	拥有部署 AAD DS 和修改 NSG 权限的账户。
OpenSSL 3.x	生成用于测试的自签名 PFX 证书所需。
域名	我们将以 openwebui.onmicrosoft.com 为例（您的 AAD 主域名）。
Open WebUI 服务器	一个正在运行的 Open WebUI 实例，通过 Docker 或裸机部署。

警告

在生产环境中，请使用由公共证书颁发机构 (CA) 颁发的 PFX 证书，并设置 LDAP_VALIDATE_CERT=true。

2. 部署 Azure AD Domain Services

1. 在 Azure Portal 中，搜索并选择 Azure AD Domain Services。

2. 点击 Create。

3. 选择您的 Subscription 和 Resource Group（或新建一个）。

4. 对于 DNS domain name，输入您的域名（例如，openwebui.onmicrosoft.com）。该值稍后将用于 LDAP_SEARCH_BASE。

5. 保持 SKU、Replica Set 等的默认设置，点击 Review + create。

   

6. 部署完成后，导航到 Azure AD DS 边栏并记录 Virtual network / Subnet。如果您的 Open WebUI 服务器不在同一个 VNet 中，您必须创建一个 NSG 规则以允许端口 636 上的流量。

3. 查找安全 LDAP 外部 IP

1. 导航到您的 AAD DS 边栏 → Overview。

2. 在 Secure LDAP 下，找到 External IP addresses。

3. 该 IP（例如，1.222.222.222）将是您 .env 文件中的 LDAP_SERVER_HOST 值。

   

4. 启用安全 LDAP (LDAPS)

4.1. 证书 (PFX) 要求

属性	要求
格式	PKCS #12 (.pfx)
加密	RSA 2048 / SHA-256
使用者可选名称 (SAN)	必须包含通配符：*.{your_domain}.onmicrosoft.com 和 {your_domain}.onmicrosoft.com。
密码	上传所需。请务必记住它。

信息

对于生产环境，我们建议使用 Let's Encrypt 或其他公共 CA。以下自签名过程仅用于测试目的。

4.2. 使用 OpenSSL 生成通配符 PFX（用于测试）

1. 创建 openssl_wildcard.cnf：

   [ req ]
   distinguished_name = req_distinguished_name
   x509_extensions = v3_ca
   req_extensions  = v3_req
   prompt = no
   
   [ req_distinguished_name ]
   C  = US
   ST = CA
   L  = San Francisco
   O  = MyTestOrg
   OU = TestDepartment
   CN = *.{your_domain}.onmicrosoft.com
   
   [ v3_ca ]
   subjectKeyIdentifier = hash
   authorityKeyIdentifier = keyid:always,issuer
   basicConstraints     = critical, CA:FALSE
   keyUsage             = critical, digitalSignature, keyEncipherment
   extendedKeyUsage     = serverAuth
   subjectAltName       = @alt_names
   
   [ v3_req ]
   basicConstraints  = CA:FALSE
   keyUsage          = digitalSignature, keyEncipherment
   extendedKeyUsage  = serverAuth
   subjectAltName    = @alt_names
   
   [ alt_names ]
   DNS.1 = *.{your_domain}.onmicrosoft.com
   DNS.2 = {your_domain}.onmicrosoft.com

   将 {your_domain} 替换为您实际的域名。

2. 生成密钥和证书：

   # 生成私钥
   openssl genrsa -out privatekey_wildcard.key 2048
   
   # 创建证书签名请求 (CSR)
   openssl req -new -key privatekey_wildcard.key \
     -out wildcard.csr -config openssl_wildcard.cnf
   
   # 创建自签名证书（有效期 365 天）
   openssl x509 -req -days 365 -in wildcard.csr \
     -signkey privatekey_wildcard.key \
     -out certificate_wildcard.crt \
     -extensions v3_req -extfile openssl_wildcard.cnf
   
   # 打包为 PFX 文件
   openssl pkcs12 -export -out certificate_wildcard.pfx \
     -inkey privatekey_wildcard.key -in certificate_wildcard.crt

3. 上传到 AAD DS：

   1. 导航到您的 AAD DS 边栏 → Secure LDAP。
   2. 点击 Upload certificate 按钮，选择 certificate_wildcard.pfx 并输入密码。
   3. 将 Secure LDAP 切换为 Enabled 并点击 Save。

   

5. 配置网络安全组 (NSG)

设置	示例值
名称	Allow-LDAPS
优先级	310
源	Any
目标端口	636
协议	TCP
操作	Allow

注意

如果允许从互联网访问，请将源 IP 范围限制为安全所需的最小值。如果 Open WebUI 在同一个 VNet 中，则可以跳过此步骤。

6. 在 Entra ID 中创建服务账户

1. 在 Azure Portal 中，导航到 Entra ID → Users → New user。

2. 设置用户名（例如，ldap@{your_domain}.onmicrosoft.com）。

3. 设置强密码并取消勾选 User must change password at next sign-in。

4. 前往 Groups 选项卡并将该用户添加到 AAD DC Administrators 群组（查询所有用户所需）。

   

7. 配置 Open WebUI 环境变量 (.env)

以下是您的 .env 文件配置示例：

###############################################
# LDAP
###############################################
ENABLE_LDAP="true"
LDAP_SERVER_LABEL="Azure AD DS"
LDAP_SERVER_HOST="1.222.222.222"
LDAP_SERVER_PORT="636"

# TLS Options
LDAP_USE_TLS="true"
LDAP_VALIDATE_CERT="false"          # 对于公共 CA 设置为 true

#LDAP_CA_CERT_FILE="/etc/ssl/certs/openwebui_ca.crt"

# Bind Account
LDAP_APP_DN="ldap@{your_domain}.onmicrosoft.com"
LDAP_APP_PASSWORD="<STRONG-PASSWORD>"

# Search Scope
LDAP_SEARCH_BASE="DC={your_domain},DC=onmicrosoft,DC=com"
LDAP_ATTRIBUTE_FOR_USERNAME="sAMAccountName"
LDAP_ATTRIBUTE_FOR_MAIL="userPrincipalName"
LDAP_SEARCH_FILTER="(&(objectClass=user)(objectCategory=person))"

# Group Synchronization (Optional)
# ENABLE_LDAP_GROUP_MANAGEMENT="true"
# ENABLE_LDAP_GROUP_CREATION="true"
# LDAP_ATTRIBUTE_FOR_GROUPS="memberOf"

将 {your_domain} 和 <STRONG-PASSWORD> 等占位符替换为您实际的值。

8. 配置群组同步（可选）

Open WebUI 可以直接从您的 LDAP 目录同步群组成员身份。当用户登录时，他们的群组信息将被获取并在 Open WebUI 中更新。

要启用此功能，请添加以下环境变量：

• ENABLE_LDAP_GROUP_MANAGEMENT="true"：启用群组管理功能。
• ENABLE_LDAP_GROUP_CREATION="true"：如果 Open WebUI 中不存在来自 LDAP 的群组，它将被自动创建。
• LDAP_ATTRIBUTE_FOR_GROUPS="memberOf"：指定包含用户群组成员身份的 LDAP 属性。在 Active Directory 环境中，memberOf 是用于此目的的常用属性。

9. 向服务器添加 CA 证书（可选）

要启用完整的 TLS 验证（LDAP_VALIDATE_CERT="true"）：

sudo cp certificate_wildcard.crt /usr/local/share/ca-certificates/openwebui.crt
sudo update-ca-certificates

做出更改后重启 Open WebUI。

10. 测试 LDAPS 连接

10.1. OpenSSL 握手检查

openssl s_client -connect 1.222.222.222:636 -showcerts

查找 Verify return code: 0 (ok) 以确认证书受信任。

10.2. ldapsearch（绑定测试）

ldapsearch -H ldaps://1.222.222.222 \
  -D "ldap@openwebui.onmicrosoft.com" -w '<PASSWORD>' \
  -b "DC=openwebui,DC=onmicrosoft,DC=com" \
  -s sub "(sAMAccountName=<test_user_id>)"

成功搜索将返回指定用户的详细信息。