Implement workload identity support

Author: ehrnst

api/v1alpha1/backendsecurity_policy.go

@@ -234,21 +234,24 @@ type BackendSecurityPolicyGCPCredentials struct {
 // Otherwise, exactly one of ClientSecretRef or OIDCExchangeToken must be specified.
 //
 // +kubebuilder:validation:XValidation:rule="has(self.useManagedIdentity) && self.useManagedIdentity ? (!has(self.clientSecretRef) && !has(self.oidcExchangeToken)) : ((has(self.clientSecretRef) && !has(self.oidcExchangeToken)) || (!has(self.clientSecretRef) && has(self.oidcExchangeToken)))",message="When useManagedIdentity is true, clientSecretRef and oidcExchangeToken must not be specified. Otherwise, exactly one of clientSecretRef or oidcExchangeToken must be specified"
-// +kubebuilder:validation:XValidation:rule="has(self.useManagedIdentity) && self.useManagedIdentity && !has(self.clientID) ? true : has(self.clientID)",message="clientID is optional for system-assigned managed identity but required otherwise"
 type BackendSecurityPolicyAzureCredentials struct {
 	// ClientID is a unique identifier for an application in Azure.
-	// This field is optional when using system-assigned managed identity,
-	// but required for user-assigned managed identity and other authentication methods.
+	// This field is optional when using managed identity or workload identity,
+	// as the value will be provided via environment variables (AZURE_CLIENT_ID).
+	// Required for other authentication methods.
 	//
 	// +optional
 	// +kubebuilder:validation:MinLength=1
-	ClientID string `json:"clientID"`
+	ClientID string `json:"clientID,omitempty"`
 
 	// TenantId is a unique identifier for an Azure Active Directory instance.
+	// This field is optional when using workload identity with service account annotations,
+	// as the value will be provided via environment variables (AZURE_TENANT_ID).
+	// Required for other authentication methods.
 	//
-	// +kubebuilder:validation:Required
+	// +optional
 	// +kubebuilder:validation:MinLength=1
-	TenantID string `json:"tenantID"`
+	TenantID string `json:"tenantID,omitempty"`
 
 	// ClientSecretRef is the reference to the secret containing the Azure client secret.
 	// ai-gateway must be given the permission to read this secret.

examples/basic/azure_openai.yaml

@@ -3,6 +3,29 @@
 # The full text of the Apache license is available in the LICENSE file at
 # the root of the repo.
 
+# Azure OpenAI Authentication Examples
+#
+# This file demonstrates two authentication methods for Azure OpenAI:
+# 1. Client Secret (default, uncommented)
+# 2. Managed Identity / Workload Identity (commented alternatives)
+#
+# For AKS Workload Identity setup, configure the service account during Helm install:
+#
+#   helm upgrade --install ai-gateway-controller envoyproxy/ai-gateway-helm \
+#     --set controller.serviceAccount.annotations."azure\.workload\.identity/client-id"="<your-managed-identity-client-id>" \
+#     --set controller.serviceAccount.annotations."azure\.workload\.identity/tenant-id"="<your-tenant-id>" \
+#     --create-namespace \
+#     -n envoy-ai-gateway-system
+#
+#   # Add the required label:
+#   kubectl label serviceaccount ai-gateway-controller \
+#     azure.workload.identity/use=true \
+#     -n envoy-ai-gateway-system
+#
+# For complete Azure infrastructure setup, see:
+# https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster
+
+---
 apiVersion: aigateway.envoyproxy.io/v1alpha1
 kind: AIGatewayRoute
 metadata:
@@ -39,6 +62,7 @@ spec:
     kind: Backend
     group: gateway.envoyproxy.io
 ---
+# Option 1: Client Secret Authentication (Default)
 apiVersion: aigateway.envoyproxy.io/v1alpha1
 kind: BackendSecurityPolicy
 metadata:
@@ -57,6 +81,26 @@ spec:
       name: envoy-ai-gateway-basic-azure-client-secret
       namespace: default
 ---
+# Option 2: Managed Identity / Workload Identity Authentication
+# Uncomment this section and comment out Option 1 to use Managed Identity.
+#
+# For AKS Workload Identity: Configure service account annotations during Helm install
+# (see header comment above for helm upgrade command)
+#
+# apiVersion: aigateway.envoyproxy.io/v1alpha1
+# kind: BackendSecurityPolicy
+# metadata:
+#   name: envoy-ai-gateway-basic-azure-credentials
+#   namespace: default
+# spec:
+#   targetRefs:
+#     - group: aigateway.envoyproxy.io
+#       kind: AIServiceBackend
+#       name: envoy-ai-gateway-basic-azure
+#   type: AzureCredentials
+#   azureCredentials:
+#     useManagedIdentity: true
+---
 apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: Backend
 metadata:

examples/basic/azure_openai_managed_identity.yaml

@@ -23,21 +23,43 @@ type azureManagedIdentityTokenProvider struct {
 	tokenOption policy.TokenRequestOptions
 }
 
-// NewAzureManagedIdentityTokenProvider creates a new TokenProvider using Azure DefaultAzureCredential.
+// NewAzureManagedIdentityTokenProvider creates a new TokenProvider using Azure credentials.
 // This supports:
+// - AKS Workload Identity (via AZURE_FEDERATED_TOKEN_FILE environment variable)
 // - Environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, AZURE_FEDERATED_TOKEN_FILE)
-// - AKS Workload Identity (via service account annotations and federated token file)
-// - System-assigned managed identity (when clientID is empty)
-// - User-assigned managed identity (when clientID is provided)
+// - System-assigned managed identity (when clientID is empty and no workload identity)
+// - User-assigned managed identity (when clientID is provided and no workload identity)
 // - Azure CLI credentials (for development scenarios).
 func NewAzureManagedIdentityTokenProvider(_ context.Context, clientID string, tokenOption policy.TokenRequestOptions) (TokenProvider, error) {
 	clientOptions := GetDefaultAzureCredentialOptions()
 
 	var credential azcore.TokenCredential
 	var err error
 
-	if clientID != "" {
+	// Check if running in AKS Workload Identity environment
+	federatedTokenFile := os.Getenv("AZURE_FEDERATED_TOKEN_FILE")
+	tenantID := os.Getenv("AZURE_TENANT_ID")
+	envClientID := os.Getenv("AZURE_CLIENT_ID")
+
+	if federatedTokenFile != "" && tenantID != "" {
+		// Use Workload Identity - this is the AKS Workload Identity pattern
+		// Use clientID from environment if not explicitly provided
+		if clientID == "" && envClientID != "" {
+			clientID = envClientID
+		}
+		
+		workloadIDOptions := &azidentity.WorkloadIdentityCredentialOptions{
+			ClientID:      clientID,
+			TenantID:      tenantID,
+			TokenFilePath: federatedTokenFile,
+		}
+		if clientOptions != nil {
+			workloadIDOptions.ClientOptions = clientOptions.ClientOptions
+		}
+		credential, err = azidentity.NewWorkloadIdentityCredential(workloadIDOptions)
+	} else if clientID != "" {
 		// User-assigned managed identity - specify the client ID.
+		// This uses Azure VM/VMSS Managed Identity via IMDS
 		managedIDOptions := &azidentity.ManagedIdentityCredentialOptions{
 			ID: azidentity.ClientID(clientID),
 		}

internal/controller/tokenprovider/azure_managed_identity_token_provider.go

@@ -1655,8 +1655,9 @@ spec:
                   clientID:
                     description: |-
                       ClientID is a unique identifier for an application in Azure.
-                      This field is optional when using system-assigned managed identity,
-                      but required for user-assigned managed identity and other authentication methods.
+                      This field is optional when using managed identity or workload identity,
+                      as the value will be provided via environment variables (AZURE_CLIENT_ID).
+                      Required for other authentication methods.
                     minLength: 1
                     type: string
                   clientSecretRef:
@@ -3063,8 +3064,11 @@ spec:
                     - oidc
                     type: object
                   tenantID:
-                    description: TenantId is a unique identifier for an Azure Active
-                      Directory instance.
+                    description: |-
+                      TenantId is a unique identifier for an Azure Active Directory instance.
+                      This field is optional when using workload identity with service account annotations,
+                      as the value will be provided via environment variables (AZURE_TENANT_ID).
+                      Required for other authentication methods.
                     minLength: 1
                     type: string
                   useManagedIdentity:
@@ -3076,8 +3080,6 @@ spec:
                       - System-assigned managed identity (when clientID is not specified)
                       - User-assigned managed identity (when clientID is specified)
                     type: boolean
-                required:
-                - tenantID
                 type: object
                 x-kubernetes-validations:
                 - message: When useManagedIdentity is true, clientSecretRef and oidcExchangeToken
@@ -3087,10 +3089,6 @@ spec:
                     (!has(self.clientSecretRef) && !has(self.oidcExchangeToken)) :
                     ((has(self.clientSecretRef) && !has(self.oidcExchangeToken)) ||
                     (!has(self.clientSecretRef) && has(self.oidcExchangeToken)))'
-                - message: clientID is optional for system-assigned managed identity
-                    but required otherwise
-                  rule: 'has(self.useManagedIdentity) && self.useManagedIdentity &&
-                    !has(self.clientID) ? true : has(self.clientID)'
               gcpCredentials:
                 description: GCPCredentials is a mechanism to access a backend(s).
                   GCP specific logic will be applied.

manifests/charts/ai-gateway-crds-helm/templates/aigateway.envoyproxy.io_backendsecuritypolicies.yaml

@@ -8,27 +8,27 @@ sidebar_position: 3
 
 This guide will help you configure Envoy AI Gateway to work with Azure OpenAI's foundation models.
 
-There are two ways to do the [Azure OpenAI authentication](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#authentication): Microsoft Entra ID and API Key.
+Azure OpenAI supports two authentication methods:
 
-We will use Microsoft Entra ID to authenticate an application to use the Azure OpenAI service. You can obtain an access token using the OAuth 2.0 client credentials grant flow. This process involves registering the application in Microsoft Entra ID (formerly Azure Active Directory), configuring the appropriate permissions, and acquiring a token from the Microsoft identity platform. The access token is then used as proof of authorization in API requests to the Azure OpenAI endpoint.
+1. **API Key**: Simple authentication using an API key from your Azure OpenAI resource.
 
-For detailed steps, refer to the official [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow#get-a-token).
+2. **Microsoft Entra ID**: OAuth-based authentication with two options:
+   - **Client Secret**: Uses client credentials (client ID, tenant ID, and secret)
+   - **Managed Identity / Workload Identity**: Uses Azure Managed Identity/Workload identity (recommended for production on Azure Kubernetes Clusters)
 
-API Key authentication is not supported yet.
+This guide focuses on Microsoft Entra ID authentication. For API Key authentication, refer to the [Azure OpenAI API documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#authentication).
 
 ## Prerequisites
 
 Before you begin, you'll need:
 
-- Azure credentials with access to OpenAI service.
+- Azure OpenAI resource with model access enabled (e.g., "GPT-4o")
 - Basic setup completed from the [Basic Usage](../basic-usage.md) guide
 - Basic configuration removed as described in the [Advanced Configuration](./index.md) overview
 
-## Azure Credential Setup
-
-1. An Azure account with OpenAI service access enabled
-2. Your Azure tenant ID, client ID, and client secret key
-3. Enabled model access to "GPT-4o"
+For Microsoft Entra ID authentication, additionally:
+- Azure tenant ID, client ID, and either a client secret OR a configured Managed Identity
+- For AKS Workload Identity: See [Azure documentation](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster) for infrastructure setup
 
 ## Configuration Steps
 
@@ -40,15 +40,37 @@ curl -O https://raw.githubusercontent.com/envoyproxy/ai-gateway/main/examples/ba
 
 ### 2. Configure Azure Credentials
 
+The `azure_openai.yaml` file includes examples for both Entra ID authentication methods. By default, it uses client secret authentication.
+
+#### Client Secret Authentication (Default)
+
 Edit the `azure_openai.yaml` file to replace these placeholder values:
 
 - `AZURE_TENANT_ID`: Your Azure tenant ID
 - `AZURE_CLIENT_ID`: Your Azure client ID
 - `AZURE_CLIENT_SECRET`: Your Azure client secret
 
+#### Managed Identity / Workload Identity Authentication
+
+To use Workload Identity instead, see the commented examples in `azure_openai.yaml`. And configure the service account annotations during Helm installation:
+
+```shell
+helm upgrade --install ai-gateway-controller envoyproxy/ai-gateway-helm \
+  --set controller.serviceAccount.annotations."azure\.workload\.identity/client-id"="<your-managed-identity-client-id>" \
+  --set controller.serviceAccount.annotations."azure\.workload\.identity/tenant-id"="<your-tenant-id>" \
+  --create-namespace \
+  -n envoy-ai-gateway-system
+
+# Add the required label:
+kubectl label serviceaccount ai-gateway-controller \
+  azure.workload.identity/use=true \
+  -n envoy-ai-gateway-system
+```
+
+Then use the Managed Identity `BackendSecurityPolicy` example from the YAML file (uncomment Option 2, comment out Option 1). Omitting the `CLIENT_ID`, `CLIENT_SECRET` and only specify `useManagedIdentity: true`. When configuring the identity on Azure your federated subject should look something like this `system:serviceaccount:envoy-ai-gateway-system:ai-gateway-controller`.
+
 :::caution Security Note
 Keep your Azure credentials secure and never commit them to version control.
-The credentials will be stored in Kubernetes secrets.
 :::
 
 ### 3. Apply Configuration