Skip to main content

Azure AD 域服务 (LDAPS) 集成

warning

本教程是社区贡献的内容，不属于 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 或裸机部署。
caution

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

2. 部署 Azure AD 域服务​

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

  2. 点击 创建。

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

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

  5. 保持 SKU、副本集 等默认设置，然后点击 查看 + 创建。

    Azure AD DS 创建 - 基础选项卡

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

3. 查找安全 LDAP 外部 IP​

  1. 导航到您的 AAD DS 页面 → 概览。

  2. 在 安全 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。
密码上传时需要。请务必记住它。
info

对于生产环境，我们建议使用 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 页面 → 安全 LDAP。
    2. 点击 上传证书 按钮，选择 certificate_wildcard.pfx，并输入密码。
    3. 将 安全 LDAP 切换为 已启用，然后点击 保存。

    启用安全 LDAP

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

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

LDAPS 的 NSG 入站规则

warning

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

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

  1. 在 Azure 门户中，导航到 Entra ID → 用户 → 新建用户。

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

  3. 设置一个强密码，并取消勾选 用户必须在下次登录时更改密码。

  4. 转到 组 选项卡，将用户添加到 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 属性。在 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>)"

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