跳到主要内容

Azure AD LDAP

注意

本教程由社区贡献，不受 Open WebUI 团队官方维护或审核。它仅作为演示，说明如何根据你的具体场景自定义 Open WebUI。想参与贡献？请查看贡献教程。

本指南说明如何将 Open WebUI 与 Azure AD 域服务（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 域服务​

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

  2. 点击 Create（创建）。

  3. 选择您的订阅和资源组（或创建新的）。

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

  5. 保留 SKU、Replica Set 等的默认设置，点击 Review + create（审查 + 创建）。

    Azure AD DS 创建 - 基本信息标签

  6. 部署完成后，导航至 Azure AD DS 页面，记录虚拟网络/子网。如果您的 Open WebUI 服务器不在同一 VNet 中，则必须创建 NSG 规则以允许端口 636 上的流量。

3. 查找安全 LDAP 外部 IP​

  1. 导航至 AAD DS 页面 → Overview（概述）。

  2. 在 Secure LDAP（安全 LDAP） 下，查找外部 IP 地址。

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

    查找安全 LDAP 外部 IP

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（安全 LDAP）。
    2. 点击 Upload certificate（上传证书） 按钮，选择 certificate_wildcard.pfx，并输入密码。
    3. 将 Secure LDAP 切换为 Enabled（已启用） 并点击 Save（保存）。

    启用安全 LDAP

5. 配置网络安全组（NSG）​

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

LDAPS 的 NSG 入站规则

注意

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

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

  1. 在 Azure 门户中，导航至 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 群组（查询所有用户所必需）。

    创建 Entra ID 服务账户

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 选项
LDAP_USE_TLS="true"
LDAP_VALIDATE_CERT="false"          # 公共 CA 请设置为 true

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

# 绑定账户
LDAP_APP_DN="ldap@{your_domain}.onmicrosoft.com"
LDAP_APP_PASSWORD="<STRONG-PASSWORD>"

# 搜索范围
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))"

# 群组同步（可选）

# 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"：如果 LDAP 中的群组在 Open WebUI 中不存在，将自动创建。
  • LDAP_ATTRIBUTE_FOR_GROUPS="memberOf"：指定包含用户群组成员资格的 LDAP 属性。memberOf 是 Active Directory 环境中此目的的标准属性。

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>)"

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

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议 以了解适用条款。