跳到主要内容

Azure AD 域服务 (LDAPS) 集成

警告

本教程由社区贡献，不获得 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 设置为 true。

2. 部署 Azure AD 域服务​

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

  2. 点击**创建**。

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

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

  5. 保留 **SKU**、**副本集**等的默认设置，然后点击**审核 + 创建**。

    Azure AD DS Creation - Basics Tab

  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 值。

    Find Secure LDAP External 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. 生成密钥和证书

    # Generate a private key
    openssl genrsa -out privatekey_wildcard.key 2048

    # Create a Certificate Signing Request (CSR)
    openssl req -new -key privatekey_wildcard.key \
      -out wildcard.csr -config openssl_wildcard.cnf

    # Create a self-signed certificate (valid for 365 days)
    openssl x509 -req -days 365 -in wildcard.csr \
      -signkey privatekey_wildcard.key \
      -out certificate_wildcard.crt \
      -extensions v3_req -extfile openssl_wildcard.cnf

    # Package into a PFX file
    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** 切换为**启用**，然后点击**保存**。

    Enable Secure LDAP

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

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

NSG Inbound Rule for LDAPS

警告

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

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

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

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

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

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

    Create Entra ID Service Account

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"          # Set to true for a public CA
#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}` 和 `` 等占位符替换为您的实际值。

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

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