Skip to main content

Workload Identity Authentication

warning

This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.

Overview​

This guide explains how to configure Open WebUI on Azure Kubernetes Service (AKS) with Workload Identity authentication for Azure OpenAI.

Workload Identity allows your AKS pods to authenticate to Azure services using Azure Entra ID (formerly Azure AD) without storing credentials in your cluster. This provides a secure, managed identity solution for accessing Azure OpenAI.

Prerequisites​

OpenWebUI​

Terraform Configuration​

Below is a complete Terraform configuration for setting up Workload Identity authentication:

1. Create a Kubernetes Namespace​

We need to create a Kubernetes namespace first so that we can programmatically assign this to our helm deployment but also to our user-assigned identity and federated identity credential in the next steps.

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

2. Create a User Assigned Identity​

We first create a Azure Assigned Identity that your Open WebUI pods will use to authenticate to Azure services.

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

3. Create Federated Identity Credential​

The Federated Identity Credentials establishes a trust relationship between your Kubernetes service account and the Azure User Assigned Identity, allowing pods to exchange Kubernetes tokens for Azure tokens.

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. Assign RBAC Role for Azure OpenAI Access​

With the trust relationship established between Azure and our User Assigned Identity we can now assign this identity a role. In this case we assign it Cognitive Services OpenAI User but if you want to use other Azure features you could ofcourse add more role assignments in the future.

note

By default our User Assigned Identity has no access to anything and will need to be given Azure RBAC roles to allow it access to various Azure resources.

warning

Make sure to replace YOUR_COGNITIVE_ACCOUNT_ID with the cognitive account id of your Azure OpenAI instance.

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. Deploy Open WebUI via Helm​

This deploys Open WebUI to your AKS cluster with the necessary service account annotations and pod labels to enable Workload Identity authentication.

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 Configuration​

After deploying Open WebUI you can follow these steps to configure your Azure OpenAI connection:

  1. Navigate to Admin Panel → Connections
  2. Click Add Connection
  3. Select Azure OpenAI as the provider
  4. Choose Entra ID as the authentication type
  5. Configure your Azure OpenAI endpoint and deployment details
  6. Save the connection

Key Components Explained​

Service Account Annotations​

The service account must have the following annotation to link it with the Azure User Assigned Identity:

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

Pod Labels​

Pods must include the following label to enable workload identity:

azure.workload.identity/use: "true"

Federated Identity Credential​

The federated identity credential creates a trust relationship between:

  • Your AKS cluster's OIDC issuer
  • The Kubernetes service account
  • The Azure User Assigned Identity

The subject field follows the format:

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

Troubleshooting​

Common Issues​

  1. Authentication Failures

    • Verify OIDC issuer is enabled on AKS cluster
    • Check workload identity is enabled on AKS cluster
    • Confirm federated identity credential subject matches namespace and service account name

  2. Permission Errors

    • Ensure Cognitive Services OpenAI User role is assigned to the user-assigned identity
    • Verify the scope of the role assignment includes your Azure OpenAI resource

  3. Pod Identity Issues

    • Check pod has the label azure.workload.identity/use: "true"
    • Verify service account has the correct azure.workload.identity/client-id annotation
    • Confirm the service account name matches the federated credential configuration

Verification Commands​

Check service account annotations:

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

View pod labels:

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

Check workload identity webhook:

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

Additional Resources​