跳到主要内容

Workload Identity 身份验证

注意

本教程由社区贡献，Open WebUI 团队不提供官方支持。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

概述​

本指南介绍了如何在 Azure Kubernetes Service (AKS) 上为 Open WebUI 配置基于 Workload Identity 身份验证的 Azure OpenAI 连接。

Workload Identity 允许您的 AKS Pod 使用 Azure Entra ID（前身为 Azure AD）向 Azure 服务进行身份验证，而无需在集群中存储任何凭证。这为访问 Azure OpenAI 提供了一个安全且易于管理的身份解决方案。

前提条件​

OpenWebUI​

Terraform 配置​

以下是用于设置 Workload Identity 身份验证的完整 Terraform 配置：

1. 创建 Kubernetes 命名空间​

我们首先需要创建一个 Kubernetes Namespace，以便在接下来的步骤中能够以编程方式将其分配给我们的 Helm 部署，以及用户分配的身份和联合身份凭证。

resource "kubernetes_namespace" "this" {
  metadata {
    name = var.kubernetes_namespace
  }
}

2. 创建用户分配身份​

我们首先创建一个 Azure 用户分配身份（Azure Assigned Identity），您的 Open WebUI Pod 将使用它来向 Azure 服务进行身份验证。

resource "azurerm_user_assigned_identity" "uai" {
  location            = var.location
  name                = var.workload_identity_name
  resource_group_name = var.resource_group_name
}

3. 创建联合身份凭证​

联合身份凭证（Federated Identity Credentials）在您的 Kubernetes 服务账号（Service Account）和 Azure 用户分配身份之间建立信任关系，允许 Pod 将 Kubernetes Token 交换为 Azure Token。

resource "azurerm_federated_identity_credential" "federated_identity" {
  name                = "federated-identity"
  resource_group_name = var.resource_group_name
  audience            = ["api://AzureADTokenExchange"]
  issuer              = data.terraform_remote_state.aks.outputs.oidc_issuer_url
  parent_id           = azurerm_user_assigned_identity.uai.id
  subject             = "system:serviceaccount:${kubernetes_namespace.this.metadata[0].name}:${var.kubernetes_service_account_name}"
}

4. 分配 Azure OpenAI 访问的 RBAC 角色​

随着 Azure 和我们的用户分配身份之间的信任关系建立，我们现在可以为该身份分配一个角色。在这种情况下，我们为其分配 Cognitive Services OpenAI User。当然，如果您将来想使用其他 Azure 功能，也可以添加更多的角色分配。

备注

默认情况下，我们的用户分配身份没有任何访问权限，需要为其授予 Azure RBAC 角色，才能允许其访问各种 Azure 资源。

注意

请务必将 YOUR_COGNITIVE_ACCOUNT_ID 替换为您的 Azure OpenAI 实例的认知服务账号 ID（Cognitive Account ID）。

resource "azurerm_role_assignment" "workload_identity_azure_openai" {
  scope                = "YOUR_COGNITIVE_ACCOUNT_ID"
  role_definition_name = "Cognitive Services OpenAI User"
  principal_id         = azurerm_user_assigned_identity.uai.principal_id
}

5. 通过 Helm 部署 Open WebUI​

这会将 Open WebUI 部署到您的 AKS 集群，并附带必要的服务账号注解（Service Account Annotations）和 Pod 标签，以启用 Workload Identity 身份验证。

resource "helm_release" "openwebui" {
  name       = "open-webui"
  repository = "https://helm.openwebui.com/"
  chart      = "open-webui"
  version    = "7.2.0"
  namespace  = kubernetes_namespace.this.metadata[0].name
  atomic     = true

  values = [
    "${file("helm.values.yaml")}"
  ]

  set {
    name  = "image.tag"
    value = "v0.6.33"
  }

  set {
    name  = "serviceAccount.name"
    value = var.kubernetes_service_account_name
  }

  set {
    name  = "serviceAccount.annotations.azure\\.workload\\.identity/client-id"
    value = azurerm_user_assigned_identity.uai.client_id
  }
}

6. UI 配置​

部署 Open WebUI 后，您可以按照以下步骤配置您的 Azure OpenAI 连接：

  1. 导航到 管理面板（Admin Panel）→ 连接（Connections）
  2. 点击 添加连接（Add Connection）
  3. 选择 Azure OpenAI 作为提供商（provider）
  4. 选择 Entra ID 作为身份验证类型
  5. 配置您的 Azure OpenAI 终结点和部署详细信息
  6. 保存连接

关键组件解释​

Service Account 注解​

服务账号（Service Account）必须包含以下注解，以将其与 Azure 用户分配身份进行关联：

azure.workload.identity/client-id: <USER_ASSIGNED_IDENTITY_CLIENT_ID>

Pod 标签​

Pod 必须包含以下标签以启用 Workload Identity：

azure.workload.identity/use: "true"

联合身份凭证​

联合身份凭证在以下对象之间创建信任关系：

  • 您的 AKS 集群的 OIDC 发行商（OIDC Issuer）
  • Kubernetes 服务账号（Service Account）
  • Azure 用户分配身份（User Assigned Identity）

subject 字段遵循以下格式：

system:serviceaccount:<namespace>:<service-account-name>

故障排除​

常见问题​

  1. 身份验证失败

    • 验证 AKS 集群上是否已启用 OIDC 发行商（OIDC Issuer）
    • 检查 AKS 集群上是否已启用 Workload Identity
    • 确认联合身份凭证的主体（subject）与命名空间和服务账号名称相匹配

  2. 权限错误

    • 确保已将 Cognitive Services OpenAI User 角色分配给用户分配的身份
    • 验证角色分配的范围（scope）是否包含您的 Azure OpenAI 资源

  3. Pod 身份问题

    • 检查 Pod 是否具有标签 azure.workload.identity/use: "true"
    • 验证服务账号是否具有正确的 azure.workload.identity/client-id 注解
    • 确认服务账号名称与联合凭证配置相匹配

验证命令​

检查服务账号注解：

kubectl get serviceaccount <service-account-name> -n <namespace> -o yaml

查看 Pod 标签：

kubectl get pod <pod-name> -n <namespace> -o yaml

检查 Workload Identity Webhook：

kubectl get mutatingwebhookconfiguration azure-wi-webhook-controller-manager-mutating-webhook-configuration

其他资源​

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.