跳到主要内容

使用 Entra ID 的 Azure OpenAI

注意

本教程来自社区贡献，并非 Open WebUI 官方支持内容。它仅作为演示，说明如何按你的具体场景自定义 Open WebUI。欢迎贡献更多内容，可查看 contributing 教程。

本节介绍如何通过 Azure Entra ID（原 Azure AD）实现安全、无密钥的认证方式，将 Open WebUI 与 Azure OpenAI 集成。相比管理静态 API key，这种方式能更好地利用 Azure 的身份与访问管理体系。

注意

要使用该能力，Open WebUI 版本必须为 0.6.30 或更高。

概览​

Open WebUI 支持通过 Entra ID 认证 集成 Azure OpenAI，这使你无需存储 API key 即可完成认证，带来以下优势：

  • 更高安全性：无需管理或轮换静态 API key
  • Azure RBAC 集成：可通过 Azure 角色分配实现细粒度权限控制
  • 审计追踪：所有访问都会进入 Azure 审计系统
  • 自动 Token 管理：Token 生命周期由 Azure 自动处理

认证方式​

Open WebUI 支持 DefaultAzureCredential 所支持的全部 Azure OpenAI 认证方式。

注意

默认情况下，DefaultAzureCredential 会尝试所有 Azure Credential，包括开发环境和生产环境类型。如果你已经明确知道自己希望使用哪种认证方式，那么默认行为未必理想，因为：

  • DefaultAzureCredential 会在每一次请求时依次尝试大部分认证方式，直到找到可用项
  • 某些认证方式会带来额外性能开销
  • 如果系统会去尝试你并未配置的认证方式，日志中可能会出现很多无意义的报错

为解决此问题，如果你的 Open WebUI 版本 >= 0.6.31，可通过环境变量 AZURE_TOKEN_CREDENTIALS 指定为以下某一种：

  • EnvironmentCredential
  • WorkloadIdentityCredential
  • ManagedIdentityCredential
  • VisualStudioCodeCredential
  • AzureCliCredential
  • AzurePowershellCredential
  • AzureDeveloperCliCredential
  • InteractiveBrowserCredential

这样它就只会使用你选定的 credential 类型。

如果你仍希望保留自动选择行为，但希望只在“开发环境凭证”或“生产环境凭证”之间筛选，也可以使用：

  • prod：表示只尝试 EnvironmentCredential、WorkloadIdentityCredential、ManagedIdentityCredential
  • dev：表示只尝试 SharedTokenCacheCredential、AzureCliCredential、AzurePowershellCredential、AzureDeveloperCliCredential

Azure CLI 认证​

最适合： 本地开发

Azure CLI 认证使用你本机上的 Azure 凭证来访问 Azure OpenAI。 这是最容易上手的方式，非常适合开发环境。

特点：

  • 配置简单，只需 Azure CLI
  • 可在本地机器与容器中工作
  • 使用你的个人 Azure 凭证
  • 需要预先安装 Azure CLI

→ 查看如何配置 Azure CLI 认证

Workload Identity 认证​

最适合： Azure Kubernetes Service（AKS）生产部署，以及多租户环境

  • 工作负载身份（Workload Identity） 为 AKS 集群提供托管身份方案，使 Pod 在无需存储任何集群内凭证的情况下即可访问 Azure 服务。

特点：

  • 集群中不存储任何凭证
  • Kubernetes 原生的认证方式
  • 联邦身份凭证
  • 生产就绪的安全模型
  • 通过 Terraform 实现基础设施即代码

→ 查看如何配置 Workload Identity 认证

前提条件​

无论你选择哪种认证方式，都需要以下条件：

  • Azure 订阅：拥有 Azure OpenAI 资源访问权限
  • Open WebUI：版本为 0.6.30 或更高
  • Azure RBAC 角色：你的身份需要被分配 Cognitive Services OpenAI User 角色
  • Azure OpenAI 资源：已经部署好的 Azure OpenAI 实例

快速对比​

Azure CLI 认证Workload Identity 认证
环境本地开发Azure Kubernetes Service (AKS)
配置复杂度简单中等（需要 Terraform 或一定 Azure 经验）
安全模型Azure CLI 凭证Workload Identity 认证
最适合开发与测试生产部署
凭证存储本地 .azure 目录无（federated tokens）

下一步​

请选择与你部署环境最匹配的认证方式：

这两种方式都能为 Azure OpenAI 提供安全、无密钥的认证能力，并且在基础设施准备完成后，都可通过 Open WebUI 管理界面进行配置。

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