docs(Azure OpenAI): Add initial version of Azure OpenAI with EntraID docs

2026-01-04 10:46:26 +07:00 · 2025-10-10 17:15:09 +02:00
parent 3e2aa213f7
commit 247922a43e
3 changed files with 447 additions and 0 deletions
--- a/docs/tutorials/integrations/azure-openai/azure-cli-auth.mdx
+++ b/docs/tutorials/integrations/azure-openai/azure-cli-auth.mdx
@@ -0,0 +1,122 @@
+---
+title: "Azure CLI 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.
+
+:::
+
+This guide explains how to configure Open WebUI to authenticate with Azure OpenAI using Azure CLI and Entra ID authentication.
+
+## Prerequisites
+
+- **Azure CLI**: Install from [Microsoft Learn](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
+- **Open WebUI**: Version 0.6.30 or later
+- **Azure Subscription**: With access to Azure OpenAI resources
+- **RBAC Role**: Your user or group must have the `Cognitive Services OpenAI User` role assigned to your Azure OpenAI instance
+
+## Authentication Steps
+
+### 1. Login with Azure CLI
+
+Run the following command to authenticate with your Azure subscription:
+
+```bash
+az login
+```
+
+This will open a browser window for you to log in with your Azure credentials.
+
+### 2. Verify RBAC Permissions
+
+Ensure your user account or group has been assigned the `Cognitive Services OpenAI User` role for your Azure OpenAI resource. You can verify this in the Azure Portal:
+
+1. Navigate to your Azure OpenAI resource
+2. Go to **Access control (IAM)**
+3. Check **Role assignments** to confirm you have the required role
+
+## Docker Configuration
+
+### Dockerfile
+
+Create or modify your Dockerfile to include Azure CLI:
+
+```Dockerfile title="Dockerfile"
+FROM --platform=$BUILDPLATFORM ghcr.io/open-webui/open-webui:${WEBUI_DOCKER_TAG-main}
+RUN pip install azure-cli
+CMD [ "bash", "start.sh"]
+```
+
+### Docker Compose
+
+Configure your `docker-compose.yml` to mount the Azure CLI configuration and set the appropriate environment variable:
+
+```yaml title="docker-compose.yml"
+services:
+  ollama:
+    volumes:
+      - ollama:/root/.ollama
+    container_name: ollama
+    pull_policy: always
+    tty: true
+    restart: unless-stopped
+    image: ollama/ollama:${OLLAMA_DOCKER_TAG-latest}
+
+  open-webui:
+    build:
+      context: .
+      args:
+        OLLAMA_BASE_URL: '/ollama'
+      dockerfile: Dockerfile
+    container_name: open-webui
+    volumes:
+      - open-webui:/app/backend/data
+      - ${HOME}/.azure:/app/.azure # THIS IS THE IMPORTANT BIT, FOR WINDOWS REPLACE ${HOME}/.azure with %USERPROFILE%\.azure*
+    depends_on:
+      - ollama
+    ports:
+      - ${OPEN_WEBUI_PORT-3000}:8080
+    environment:
+      - 'OLLAMA_BASE_URL=http://ollama:11434/'
+      - AZURE_CONFIG_DIR=/app/.azure # THIS IS THE IMPORTANT BIT*
+      - 'WEBUI_SECRET_KEY='
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    restart: unless-stopped
+
+volumes:
+  ollama: {}
+  open-webui: {}
+```
+
+This configuration:
+- Mounts your local Azure CLI credentials (`~/.azure` on linux, or `%USERPROFILE%\.azure` on windows) into the container
+- Sets the `AZURE_CONFIG_DIR` environment variable so Open WebUI can locate the credentials
+
+### Start the compose stack
+Start the docker compose services using:
+```bash
+docker compose up
+```
+
+### UI Configuration
+
+Once your Docker container is running:
+
+1. Navigate to **Admin Panel** &rarr; **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
+
+## Troubleshooting
+
+If you encounter authentication issues:
+
+1. **Verify Azure CLI login**: Run `az account show` to confirm you're logged in
+2. **Check permissions**: Ensure the `Cognitive Services OpenAI User` role is assigned
+3. **Volume mounting**: Verify the `.azure` directory is correctly mounted in the container
+4. **Environment variable**: Confirm `AZURE_CONFIG_DIR` is set to `/app/.azure`
--- a/docs/tutorials/integrations/azure-openai/index.mdx
+++ b/docs/tutorials/integrations/azure-openai/index.mdx
@@ -0,0 +1,114 @@
+---
+sidebar_position: 1
+title: "✨ Azure OpenAI with EntraID"
+---
+
+:::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.
+
+:::
+
+# Azure OpenAI with EntraID
+
+This sections contains guides on how to integrate Open WebUI with Azure OpenAI using secure, keyless authentication via Azure Entra ID (formerly Azure AD). Instead of managing static API keys, you can leverage Azure's identity and access management for enhanced security.
+
+:::warning
+OpenWebUI needs to be on version 0.6.30 or higher for this to work!
+:::
+
+## Overview
+
+Open WebUI supports Azure OpenAI integration with **Entra ID authentication**, allowing you to authenticate without storing API keys. This provides several benefits:
+
+- **Enhanced Security**: No static API keys to manage or rotate
+- **Azure RBAC Integration**: Fine-grained access control using Azure role assignments
+- **Audit Trail**: All access is logged through Azure's audit system
+- **Automatic Token Management**: Azure handles token lifecycle automatically
+
+## Authentication Methods
+
+Open WebUI supports all authentication methods supported by [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python) for Azure OpenAI.
+
+:::warning
+By default `DefaultAzureCredential` tries all Azure Credentials, both development
+and production types. This might not be desirable if you know what authentication
+type you want to use since:
+- `DefaultAzureCredential` is called on **every** request and tries most authentication types until it finds one that works 
+- There is a performance overhead for some authentication types
+- If you don't have certain types of authentication configured but they are tried your logs might be polluted with erroneous errors.
+
+To fix this, **if you're on version 0.6.31 or greater** you can set the environment variable `AZURE_TOKEN_CREDENTIALS` to one of these specific values:
+- `EnvironmentCredential`
+- `WorkloadIdentityCredential`
+- `ManagedIdentityCredential`
+- `VisualStudioCodeCredential`
+- `AzureCliCredential`
+- `AzurePowershellCredential`
+- `AzureDeveloperCliCredential`
+- `InteractiveBrowserCredential`
+
+_This would result in it only ever choosing the selected credential type_
+
+Or, if you prefer the automatic selection behaviour but wish to narrow it between development vs production options you can use:
+- `prod` for `EnvironmentCredential`, `WorkloadIdentityCredential`, and `ManagedIdentityCredential`.
+- `dev` for `SharedTokenCacheCredential`, `AzureCliCredential`, `AzurePowershellCredential`, and `AzureDeveloperCliCredential`.
+:::
+
+### Azure CLI Authentication
+
+**Best for:** Local development
+
+Azure CLI authentication uses your local Azure credentials to authenticate with Azure OpenAI.
+This is the simplest method for getting started and works well for development environments.
+
+**Key Features:**
+- Simple setup with Azure CLI
+- Works on local machines and containers
+- Uses your personal Azure credentials
+- Requires Azure CLI to be installed
+
+[**→ Learn how to set up Azure CLI Authentication**](./azure-cli-auth.mdx)
+
+### 2. Workload Identity Authentication
+
+**Best for:** Azure Kubernetes Service (AKS) production deployments and multi-tenant environments
+
+Workload Identity provides a managed identity solution for AKS clusters, allowing pods to authenticate to Azure services without storing any credentials in the cluster.
+
+**Key Features:**
+- No credentials stored in cluster
+- Kubernetes-native authentication
+- Federated identity credentials
+- Production-ready security model
+- Infrastructure as Code via Terraform
+
+[**→ Learn how to set up Workload Identity Authentication**](./workload-identity-auth.mdx)
+
+## Prerequisites
+
+Regardless of which authentication method you choose, you'll need:
+
+- **Azure Subscription**: With access to Azure OpenAI resources
+- **Open WebUI**: Version 0.6.30 or later
+- **Azure RBAC Role**: `Cognitive Services OpenAI User` role assigned to your identity
+- **Azure OpenAI Resource**: A deployed Azure OpenAI instance
+
+## Quick Comparison
+
+|                        | Azure CLI Auth           | Workload Identity                                 |
+|------------------------|--------------------------|---------------------------------------------------|
+| **Environment**        | Local development        | Azure Kubernetes Service (AKS)                    |
+| **Setup Complexity**   | Simple                   | Moderate (requires Terraform or Azure experience) |
+| **Security Model**     | Azure CLI credentials    | Workload identity                                 |
+| **Best For**           | Development and testing  | Production deployments                            |
+| **Credential Storage** | Local `.azure` directory | None (federated tokens)                           |
+
+## Next Steps
+
+Choose the authentication method that best fits your deployment environment:
+
+- **For local development or Docker deployments**: Start with [Azure CLI Authentication](./azure-cli-auth.mdx)
+- **For production AKS deployments**: Use [Workload Identity Authentication](./workload-identity-auth.mdx)
+
+Both methods provide secure, keyless authentication to Azure OpenAI and can be configured through the Open WebUI admin interface once the infrastructure is set up.
--- a/docs/tutorials/integrations/azure-openai/workload-identity-auth.mdx
+++ b/docs/tutorials/integrations/azure-openai/workload-identity-auth.mdx
@@ -0,0 +1,211 @@
+---
+title: "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
+
+- **Open WebUI**: Version 0.6.30 or later
+- **AKS Cluster Configuration**: your AKS cluster must have the following features enabled
+  - **OIDC Issuer**
+    - See [Microsoft Learn - Create an OpenID Connect provider on Azure Kubernetes Service (AKS)](https://learn.microsoft.com/en-us/azure/aks/use-oidc-issuer)
+    - AzureRM Terraform: [`azurerm_kubernetes_cluster.oidc_issuer_enabled`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/kubernetes_cluster#oidc_issuer_enabled-1)
+  - **Workload Identity**
+    - See [Microsoft Learn - Use Microsoft Entra Workload ID with Azure Kubernetes Service (AKS)](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview?tabs=dotnet)
+    - AzureRM Terraform: [`azurerm_kubernetes_cluster.workload_identity_enabled`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/kubernetes_cluster#workload_identity_enabled-1)
+
+## 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. 
+
+```hcl
+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.
+
+```hcl
+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.
+
+```hcl
+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.
+:::
+
+```hcl
+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.
+
+```hcl
+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** &rarr; **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:
+
+```yaml
+azure.workload.identity/client-id: <USER_ASSIGNED_IDENTITY_CLIENT_ID>
+```
+
+### Pod Labels
+
+Pods must include the following label to enable workload identity:
+
+```yaml
+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:
+```bash
+kubectl get serviceaccount <service-account-name> -n <namespace> -o yaml
+```
+
+View pod labels:
+```bash
+kubectl get pod <pod-name> -n <namespace> -o yaml
+```
+
+Check workload identity webhook:
+```bash
+kubectl get mutatingwebhookconfiguration azure-wi-webhook-controller-manager-mutating-webhook-configuration
+```
+
+## Additional Resources
+
+- [Azure Workload Identity Documentation](https://azure.github.io/azure-workload-identity/)
+- [AKS Workload Identity Overview](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview)
+- [Open WebUI Helm Chart](https://github.com/open-webui/helm-charts)