mirror of
https://github.com/open-webui/docs.git
synced 2025-12-13 07:59:34 +07:00
212 lines
7.3 KiB
Plaintext
212 lines
7.3 KiB
Plaintext
---
|
|
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** → **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)
|