Skip to main content

工作负载身份 (Workload Identity) 身份验证

warning

本教程由社区贡献，不属于 Open WebUI 官方团队的支持范畴。它仅作为如何根据您的特定用例自定义 Open WebUI 的演示。想贡献代码？请查看贡献教程。

概述​

本指南说明了如何在 Azure Kubernetes 服务 (AKS) 上为 Open WebUI 配置 Azure OpenAI 的工作负载身份 (Workload Identity) 身份验证。

工作负载身份允许您的 AKS Pod 使用 Azure Entra ID（原 Azure AD）向 Azure 服务进行身份验证，而无需在集群中存储凭据。这为访问 Azure OpenAI 提供了一个安全且受管理的身份解决方案。

前提条件​

OpenWebUI​

Terraform 配置​

下面是设置工作负载身份身份验证的完整 Terraform 配置：

1. 创建 Kubernetes 命名空间​

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

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

2. 创建用户分配标识 (User Assigned Identity)​

我们首先创建一个 Azure 用户分配标识，您的 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 Credential)​

联合身份凭据在 Kubernetes 服务帐户和 Azure 用户分配标识之间建立信任关系，允许 Pod 将 Kubernetes 令牌交换为 Azure 令牌。

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 功能，以后当然可以添加更多角色分配。

note

默认情况下，我们的用户分配标识没有任何访问权限，需要被赋予 Azure RBAC 角色才能访问各种 Azure 资源。

warning

请务必将 YOUR_COGNITIVE_ACCOUNT_ID 替换为您的 Azure OpenAI 实例的认知账户 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 集群，并附带必要的服务帐户注释和 Pod 标签，以启用工作负载身份身份验证。

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 作为提供商
  4. 选择 Entra ID 作为身份验证类型
  5. 配置您的 Azure OpenAI 端点和部署详情
  6. 保存连接

关键组件说明​

服务帐户注释 (Service Account Annotations)​

服务帐户必须具有以下注释，以便将其与 Azure 用户分配标识链接起来：

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

Pod 标签 (Pod Labels)​

Pod 必须包含以下标签以启用工作负载身份：

azure.workload.identity/use: "true"

联合身份凭据 (Federated Identity Credential)​

联合身份凭据在以下各项之间创建信任关系：

  • AKS 集群的 OIDC 发行者 (OIDC Issuer)
  • Kubernetes 服务帐户
  • Azure 用户分配标识

subject 字段遵循以下格式：

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

故障排除​

常见问题​

  1. 身份验证失败

    • 验证 AKS 集群上是否启用了 OIDC 发行者
    • 检查 AKS 集群上是否启用了工作负载身份
    • 确认联合身份凭据的 subject 与命名空间和服务帐户名称匹配

  2. 权限错误

    • 确保已将 Cognitive Services OpenAI User 角色分配给用户分配标识
    • 验证角色分配的范围是否包含您的 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