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 服务器通过 Docker 或裸机部署的运行中的 Open WebUI 实例。
caution

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

2. 部署 Azure AD 域服务​

  1. 在 Azure 门户中，搜索并选择 Azure AD 域服务。

  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
源任何
目标端口636
协议TCP
操作允许

LDAPS 的 NSG 入站规则

warning

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

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

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

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

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

  4. 转到 组 选项卡并将用户添加到 AAD DC 管理员 组（查询所有用户所需）。

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

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