跳到主要内容

OneDrive & SharePoint

信息

本教程提供了将 Open WebUI 与 Microsoft OneDrive for Business & SharePoint 进行集成的分步指南，同时也涵盖了针对 个人版 Microsoft OneDrive 账户的独立可选集成。您可以启用其中一种或同时启用这两种集成。截至 Open WebUI v0.6.37，本篇文档是最新的。

配置 OneDrive 与 SharePoint 集成

本指南将向您展示配置 Open WebUI 的完整流程，以允许用户直接从其 Microsoft 账户附加文件。该过程包括在 Microsoft Azure 门户中创建一到两个应用注册（Application Registrations），并在您的 Open WebUI 实例中设置正确的环境变量。

Prerequisites​

要成功完成本教程，您需要：

  • 一个活跃的 Microsoft Azure 账户，且拥有创建和管理应用注册（App Registrations）的管理员权限。
  • 可以访问并修改您的 Open WebUI 实例的环境变量（例如，通过 .env 文件或 Docker 环境变量设置）。

适用于商业版 OneDrive 与 SharePoint（工作/学校）的集成

这是适用于组织机构使用的主要集成。请按照以下步骤操作，允许用户访问其工作或学校账户中的文件。

Step 1: Create the Azure App Registration​

首先，您需要在组织的 Microsoft Entra ID（前身为 Azure AD）租户中注册一个应用程序。

  1. 导航至 Microsoft Entra ID 管理中心。
  2. 转到 ID (Identity) > 应用程序 (Applications) > 应用注册 (App registrations)。
  3. 选择 + 新注册 (+ New registration)。
  4. 为您的应用程序起一个描述性的名称，例如“Open WebUI Business Integration”。
  5. 在“受受支持的账户类型”下，选择 “仅此组织目录中的账户(仅单租户)” 或 “任何组织目录中的账户(任何 Microsoft Entra ID 租户 - 多租户)”。
  6. 暂时保留“重定向 URI”部分为空。点击 注册 (Register)。

Step 2: Configure the SPA Redirect URI​

Open WebUI 是一个单页应用程序（Single-Page Application，简称 SPA），并使用 Microsoft 认证库（Microsoft Authentication Library，简称 MSAL）。正确配置重定向 URI（Redirect URI）至关重要。

  1. 在新注册的应用程序概述页面中，转到 身份验证 (Authentication) 选项卡。
  2. 点击 + 添加平台 (+ Add a platform) 并选择 单页应用程序 (SPA)。
  3. 在“重定向 URI”下，输入您的 Open WebUI 实例的基准 URL（例如，https://open-webui.yourdomain.com）。
  4. 在“隐式授予和混合流”部分，勾选启用“访问令牌 (Access tokens)”和“ID 令牌 (ID tokens)”。
  5. 点击 配置 (Configure)。

Step 3: Configure API Permissions​

接下来，授予该应用程序代表用户从 OneDrive 和 SharePoint 中读取文件的权限。

  1. 从应用注册菜单中，转到 API 权限 (API permissions) 选项卡。
  2. 点击 + 添加权限 (+ Add a permission) 并选择 Microsoft Graph。
  3. 选择 委托的权限 (Delegated permissions)。
  4. 在搜索框中，找到并添加以下权限：
    • Files.Read：允许应用程序读取已登录用户有权访问的文件。
    • Files.Read.All：允许应用程序读取已登录用户可以访问的所有文件。
    • Sites.Read.All：允许应用程序读取已登录用户可以访问的所有网站集中的项。
    • User.Read：允许应用程序读取已登录用户的个人资料。
    • AllSites.Read：用于读取网站数据的旧版 SharePoint 权限。
    • MyFiles.Read：允许应用程序读取用户的个人云端硬盘。
    • Sites.Search.All：启用跨网站的文件搜索功能。
  5. 如果您的组织单独使用 SharePoint API 权限，请重复上述过程，选择 SharePoint 而不是 Microsoft Graph，并添加适用的委托权限。
  6. 添加所有权限后，您必须授予管理员同意。点击 “代表 [您的租户名称] 授予管理员同意” 按钮。这些权限的状态应变为“已授予”。
注意

管理员同意是强制性的

Open WebUI 使用 .default 作用域以提供无缝的企业级体验，这意味着它依赖于预先批准的权限。如果在此处未授予管理员同意，非管理员用户在登录时将被阻止，并显示“需要管理员批准”的错误。

Step 4: Gather Credentials for Business Integration​

从您刚刚创建的应用注册的 概述 (Overview) 页面中，复制以下值：

  • 应用程序 (客户端) ID：这将是您的 ONEDRIVE_CLIENT_ID_BUSINESS。
  • 目录 (租户) ID：这将是您的 ONEDRIVE_SHAREPOINT_TENANT_ID。

Step 5: Configure Environment Variables for Business Integration​

在您的 Open WebUI 部署中设置以下环境变量，以启用工作/学校集成：

# 全局启用 OneDrive 集成功能
ENABLE_ONEDRIVE_INTEGRATION=true

# --- 商业版与 SharePoint 配置 ---

# 商业版应用注册中的“应用程序 (客户端) ID”
ONEDRIVE_CLIENT_ID_BUSINESS="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 商业版应用注册中的“目录 (租户) ID”
ONEDRIVE_SHAREPOINT_TENANT_ID="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"

# 您的 SharePoint 实例的根 URL
ONEDRIVE_SHAREPOINT_URL="https://your-tenant-name.sharepoint.com"
信息

设置这些变量并重启 Open WebUI 后，您还必须在管理员面板中启用 OneDrive 开关。详情请参见下方的“最终步骤”部分。

适用于个人版 OneDrive 的集成（可选）

要启用对个人 Microsoft 账户的支持，您必须为个人消费者创建 第二个独立的应用注册。

Step 1: Create a Separate App Registration for Personal Accounts​

  1. 返回 Microsoft Entra ID 中的 应用注册 (App registrations) 并选择 + 新注册 (+ New registration)。
  2. 给它起一个明显的名称，例如“Open WebUI Personal Integration”。
  3. 在“受支持的账户类型”下，选择：“任何组织目录(任何 Microsoft Entra ID 租户 - 多租户)中的账户和个人 Microsoft 账户(例如 Skype、Xbox)”。
  4. 像为商业版应用所做的那样，使用您的 Open WebUI 基准 URL 配置 SPA 重定向 URI。
  5. 在“隐式授予和混合流”部分，勾选启用“访问令牌 (Access tokens)”和“ID 令牌 (ID tokens)”。
  6. 对于此个人注册，不需要特殊的 API 权限或管理员同意，因为用户将单独同意 OneDrive.ReadWrite 权限。

Step 2: Gather the Client ID for Personal Integration​

在此全新的“个人版”应用注册的 概述 (Overview) 页面中，复制 应用程序 (客户端) ID。这将被用于另一个环境变量。

Step 3: Configure the Environment Variable for Personal Integration​

将以下环境变量添加到您的 Open WebUI 部署中：


# --- 个人账户配置（可选） ---

# 您的“第二个”个人版应用注册中的“应用程序 (客户端) ID”
ONEDRIVE_CLIENT_ID_PERSONAL="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"

Final Step: Enable OneDrive Integration in Admin Settings​

设置好环境变量并重启 Open WebUI 实例后，您必须在管理员面板中显式启用该功能。仅设置环境变量并不会激活此集成。

  1. 导航至 设置 → 管理员 (Admin) → 文档 (Documents)。
  2. 打开 “OneDrive” 开关。
  3. 刷新浏览器，或者退出登录并重新登录。
注意

必须在管理员设置中开启

尽管您已经在环境中设置了 ENABLE_ONEDRIVE_INTEGRATION=true，但此步骤依然是强制性的。Open WebUI 中的某些配置项是持久化的数据库设置，它们在首次启动时被初始化，但必须通过管理员界面激活。

Verifying the Integration​

在管理员开关启用并刷新后，验证集成是否正常工作：

  1. 在 Open WebUI 中，打开聊天输入框中的附件菜单 (+)。您应该会看到 “Microsoft OneDrive (工作/学校)” 和/或 “Microsoft OneDrive (个人)” 的菜单项，具体取决于您的配置。
  2. 点击其中任何一个选项都应触发 Microsoft 身份验证的弹窗。
警告

禁用弹窗拦截器！

OneDrive 文件选择器和身份验证流程是在弹窗中进行的。如果点击 OneDrive 选项时没有任何反应，您的浏览器几乎肯定拦截了弹窗。您必须为您 Open WebUI 的域名禁用弹窗拦截器，以使该集成正常工作。请注意，与其他浏览器（如 Edge）相比，某些浏览器（如 Chrome）可能会有额外的限制。

Troubleshooting​

附件菜单中没有出现 OneDrive 选项：

  • 验证“设置” → “管理员” → “文档”中的管理员开关是否已启用
  • 启用开关后刷新浏览器
  • 检查环境变量是否正确设置且容器已重启

文件未加载或文件夹无法点击：

  • 完全退出 Open WebUI 并重新登录以刷新您的身份验证令牌
  • 验证 Azure 应用注册权限配置是否正确，且已授予管理员同意
  • 检查浏览器控制台是否存在任何身份验证错误

未出现身份验证弹窗：

  • 针对您的 Open WebUI 域名禁用弹窗拦截器
  • 尝试使用不同的浏览器（对于 Microsoft 身份验证流，Edge 的工作稳定性通常比 Chrome 更好）

您现在已成功配置 OneDrive 集成，为您的用户提供了无缝的文件访问体验。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.