Skip to main content

Workload Identity Authentication

Overview​

This guide explains how to configure HridaAI 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​

HridaAI​

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 HridaAI 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 HridaAI via Helm​

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

resource "helm_release" "hridaai" {
  name       = "hrida-ai"
  repository = "https://helm.hrida.ai/"
  chart      = "hrida-ai"
  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 HridaAI 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
Custom / private endpoint hostnames

If you front Azure OpenAI with a private endpoint, API gateway, or other custom domain (i.e. the base URL is not a standard *.openai.azure.com / *.cognitiveservices.azure.com host — common in AKS/enterprise setups), selecting the Azure OpenAI provider is sufficient: HridaAI applies Azure request handling based on the chosen provider, not on hostname pattern matching. Older versions only recognized Azure connections by the azure.* hostname, so a custom-hostname Azure connection would fail Verify Connection and model listing — if you hit that, upgrade to v1.0.0 or later.

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​

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Hrida AI is proprietary software owned by Zlabs Innovation, provided "as is." See your license for applicable terms. © 2026 Zlabs Innovation. All rights reserved.