Merge branch 'Development' of https://github.com/vivche/simplechat-development into Development

Author: Chen, Vivien

deployers/terraform/main.tf

@@ -172,6 +172,7 @@ locals {
   cosmos_db_name              = "${var.param_base_name}-${var.param_environment}-cosmos"
   open_ai_name                = "${var.param_base_name}-${var.param_environment}-oai"
   doc_intel_name              = "${var.param_base_name}-${var.param_environment}-docintel"
+  speech_service_name         = "${var.param_base_name}-${var.param_environment}-speech"
   key_vault_name              = "${var.param_base_name}-${var.param_environment}-kv"
   log_analytics_name          = "${var.param_base_name}-${var.param_environment}-la"
   managed_identity_name       = "${var.param_base_name}-${var.param_environment}-id"
@@ -625,13 +626,14 @@ resource "azurerm_cosmosdb_account" "cosmos" {
 
 # --- Azure OpenAI Service (Cognitive Services) ---
 resource "azurerm_cognitive_account" "openai" {
-  count               = var.param_use_existing_openai_instance ? 0 : 1 # Only create if not using existing
-  name                = local.open_ai_name
-  location            = azurerm_resource_group.rg.location
-  resource_group_name = azurerm_resource_group.rg.name
-  kind                = "OpenAI"
-  sku_name            = "S0" # Standard tier
-  tags                = local.common_tags
+  count                 = var.param_use_existing_openai_instance ? 0 : 1 # Only create if not using existing
+  name                  = local.open_ai_name
+  location              = azurerm_resource_group.rg.location
+  resource_group_name   = azurerm_resource_group.rg.name
+  kind                  = "OpenAI"
+  sku_name              = "S0" # Standard tier
+  custom_subdomain_name = local.open_ai_name # Required for managed identity authentication
+  tags                  = local.common_tags
 }
 
 # Data source for existing OpenAI instance
@@ -643,13 +645,24 @@ data "azurerm_cognitive_account" "existing_openai" {
 
 # --- Document Intelligence Service (Cognitive Services) ---
 resource "azurerm_cognitive_account" "docintel" {
-  name                = local.doc_intel_name
-  location            = azurerm_resource_group.rg.location
-  resource_group_name = azurerm_resource_group.rg.name
-  kind                = "FormRecognizer"
-  sku_name            = "S0" # Standard tier
-  custom_subdomain_name = local.doc_intel_name # Maps to --custom-domain
-  tags                = local.common_tags
+  name                  = local.doc_intel_name
+  location              = azurerm_resource_group.rg.location
+  resource_group_name   = azurerm_resource_group.rg.name
+  kind                  = "FormRecognizer"
+  sku_name              = "S0" # Standard tier
+  custom_subdomain_name = local.doc_intel_name # Required for managed identity authentication
+  tags                  = local.common_tags
+}
+
+# --- Speech Service (Cognitive Services) ---
+resource "azurerm_cognitive_account" "speech" {
+  name                  = local.speech_service_name
+  location              = azurerm_resource_group.rg.location
+  resource_group_name   = azurerm_resource_group.rg.name
+  kind                  = "SpeechServices"
+  sku_name              = "S0" # Standard tier
+  custom_subdomain_name = local.speech_service_name # Required for managed identity authentication
+  tags                  = local.common_tags
 }
 
 # https://medium.com/expert-thinking/mastering-azure-search-with-terraform-a-how-to-guide-7edc3a6b1ee3
@@ -702,6 +715,20 @@ resource "azurerm_role_assignment" "managed_identity_storage_contributor" {
   principal_id         = azurerm_user_assigned_identity.id.principal_id
 }
 
+# Cognitive Services Speech User on Speech Service
+resource "azurerm_role_assignment" "managed_identity_speech_user" {
+  scope                = azurerm_cognitive_account.speech.id
+  role_definition_name = "Cognitive Services Speech User"
+  principal_id         = azurerm_user_assigned_identity.id.principal_id
+}
+
+# Cognitive Services Speech Contributor on Speech Service
+resource "azurerm_role_assignment" "managed_identity_speech_contributor" {
+  scope                = azurerm_cognitive_account.speech.id
+  role_definition_name = "Cognitive Services Speech Contributor"
+  principal_id         = azurerm_user_assigned_identity.id.principal_id
+}
+
 # App Registration Service Principal RBAC
 # Cognitive Services OpenAI Contributor on OpenAI
 resource "azurerm_role_assignment" "app_reg_sp_openai_contributor" {
@@ -732,13 +759,27 @@ resource "azurerm_role_assignment" "app_service_smi_storage_contributor" {
   principal_id         = azurerm_linux_web_app.app.identity[0].principal_id
 }
 
-# Storage Blob Data Contributor on Storage Account
+# AcrPull on Container Registry
 resource "azurerm_role_assignment" "acr_pull" {
   scope                = data.azurerm_container_registry.acrregistry.id
   role_definition_name = "AcrPull"
   principal_id         = azurerm_linux_web_app.app.identity[0].principal_id
 }
 
+# Cognitive Services Speech User on Speech Service
+resource "azurerm_role_assignment" "app_service_smi_speech_user" {
+  scope                = azurerm_cognitive_account.speech.id
+  role_definition_name = "Cognitive Services Speech User"
+  principal_id         = azurerm_linux_web_app.app.identity[0].principal_id
+}
+
+# Cognitive Services Speech Contributor on Speech Service
+resource "azurerm_role_assignment" "app_service_smi_speech_contributor" {
+  scope                = azurerm_cognitive_account.speech.id
+  role_definition_name = "Cognitive Services Speech Contributor"
+  principal_id         = azurerm_linux_web_app.app.identity[0].principal_id
+}
+
 
 ##################################################
 #

docs/how-to/azure_speech_managed_identity_manul_setup.md

@@ -0,0 +1,261 @@
+# Azure Speech Service with Managed Identity Setup
+
+## Overview
+
+This guide explains the critical difference between key-based and managed identity authentication when configuring Azure Speech Service, and the required steps to enable managed identity properly.
+
+## Authentication Methods: Regional vs. Resource-Specific Endpoints
+
+### Regional Endpoint (Shared Gateway)
+
+**Endpoint format**: `https://<region>.api.cognitive.microsoft.com`
+- Example: `https://eastus2.api.cognitive.microsoft.com`
+- This is a **shared endpoint** for all Speech resources in that Azure region
+- Acts as a gateway that routes requests to individual Speech resources
+
+### Resource-Specific Endpoint (Custom Subdomain)
+
+**Endpoint format**: `https://<resource-name>.cognitiveservices.azure.com`
+- Example: `https://simplechat6-dev-speech.cognitiveservices.azure.com`
+- This is a **unique endpoint** dedicated to your specific Speech resource
+- Requires custom subdomain to be enabled on the resource
+
+---
+
+## Why Regional Endpoint Works with Key but NOT Managed Identity
+
+### Key-Based Authentication ✅ Works with Regional Endpoint
+
+When using subscription key authentication:
+
+```http
+POST https://eastus2.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe
+Headers:
+  Ocp-Apim-Subscription-Key: abc123def456...
+```
+
+**Why it works:**
+1. The subscription key **directly identifies** your specific Speech resource
+2. The regional gateway uses the key to look up which resource it belongs to
+3. The request is automatically routed to your resource
+4. Authorization succeeds because the key proves ownership
+
+### Managed Identity (AAD Token) ❌ Fails with Regional Endpoint
+
+When using managed identity authentication:
+
+```http
+POST https://eastus2.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe
+Headers:
+  Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
+```
+
+**Why it fails (returns 400 BadRequest):**
+1. The Bearer token proves your App Service identity to Azure AD
+2. The token does NOT specify which Speech resource you want to access
+3. The regional gateway cannot determine:
+   - Which specific Speech resource you're authorized for
+   - Whether your managed identity has RBAC roles on that resource
+4. **Result**: The gateway rejects the request with 400 BadRequest
+
+### Managed Identity ✅ Works with Resource-Specific Endpoint
+
+When using managed identity with custom subdomain:
+
+```http
+POST https://simplechat6-dev-speech.cognitiveservices.azure.com/speechtotext/transcriptions:transcribe
+Headers:
+  Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
+```
+
+**Why it works:**
+1. The hostname **itself identifies** your specific Speech resource
+2. Azure validates your managed identity Bearer token against that resource's RBAC
+3. If your App Service MI has `Cognitive Services Speech User` role → authorized
+4. The request proceeds to your dedicated Speech resource instance
+
+---
+
+## Required Setup for Managed Identity
+
+### Prerequisites
+
+1. **Azure Speech Service resource** created in your subscription
+2. **System-assigned or user-assigned managed identity** on your App Service
+3. **RBAC role assignments** on the Speech resource
+
+### Step 1: Enable Custom Subdomain on Speech Resource
+
+**Why needed**: By default, Speech resources use the regional endpoint and do NOT have custom subdomains. Managed identity requires the resource-specific endpoint.
+
+**How to enable**:
+
+```bash
+az cognitiveservices account update \
+  --name <speech-resource-name> \
+  --resource-group <resource-group-name> \
+  --custom-domain <speech-resource-name>
+```
+
+**Example**:
+
+```bash
+az cognitiveservices account update \
+  --name simplechat6-dev-speech \
+  --resource-group sc-simplechat6-dev-rg \
+  --custom-domain simplechat6-dev-speech
+```
+
+**Important notes**:
+- Custom subdomain name must be **globally unique** across Azure
+- Usually use the same name as your resource: `<resource-name>`
+- **One-way operation**: Cannot be disabled once enabled
+- After enabling, the resource's endpoint property changes from regional to resource-specific
+
+**Verify custom subdomain is enabled**:
+
+```bash
+az cognitiveservices account show \
+  --name <speech-resource-name> \
+  --resource-group <resource-group-name> \
+  --query "{customSubDomainName:properties.customSubDomainName, endpoint:properties.endpoint}"
+```
+
+Expected output:
+```json
+{
+  "customSubDomainName": "simplechat6-dev-speech",
+  "endpoint": "https://simplechat6-dev-speech.cognitiveservices.azure.com/"
+}
+```
+
+### Step 2: Assign RBAC Roles to Managed Identity
+
+Grant your App Service managed identity the necessary roles on the Speech resource:
+
+```bash
+# Get the Speech resource ID
+SPEECH_RESOURCE_ID=$(az cognitiveservices account show \
+  --name <speech-resource-name> \
+  --resource-group <resource-group-name> \
+  --query id -o tsv)
+
+# Get the App Service managed identity principal ID
+MI_PRINCIPAL_ID=$(az webapp identity show \
+  --name <app-service-name> \
+  --resource-group <resource-group-name> \
+  --query principalId -o tsv)
+
+# Assign Cognitive Services Speech User role (data-plane read access)
+az role assignment create \
+  --assignee $MI_PRINCIPAL_ID \
+  --role "Cognitive Services Speech User" \
+  --scope $SPEECH_RESOURCE_ID
+
+# Assign Cognitive Services Speech Contributor role (if needed for write operations)
+az role assignment create \
+  --assignee $MI_PRINCIPAL_ID \
+  --role "Cognitive Services Speech Contributor" \
+  --scope $SPEECH_RESOURCE_ID
+```
+
+**Verify role assignments**:
+
+```bash
+az role assignment list \
+  --assignee $MI_PRINCIPAL_ID \
+  --scope $SPEECH_RESOURCE_ID \
+  -o table
+```
+
+### Step 3: Configure Admin Settings
+
+In the Admin Settings → Search & Extract → Multimedia Support section:
+
+| Setting | Value | Example |
+|---------|-------|---------|
+| **Enable Audio File Support** | ✅ Checked | |
+| **Speech Service Endpoint** | Resource-specific endpoint (with custom subdomain) | `https://simplechat6-dev-speech.cognitiveservices.azure.com` |
+| **Speech Service Location** | Azure region | `eastus2` |
+| **Speech Service Locale** | Language locale for transcription | `en-US` |
+| **Authentication Type** | Managed Identity | |
+| **Speech Service Key** | (Leave empty when using MI) | |
+
+**Critical**: 
+- Endpoint must be the resource-specific URL (custom subdomain)
+- Do NOT use the regional endpoint for managed identity
+- Remove trailing slash from endpoint: ✅ `https://..azure.com` ❌ `https://..azure.com/`
+
+### Step 4: Test Audio Upload
+
+1. Upload a short WAV or MP3 file
+2. Monitor application logs for transcription progress
+3. Expected log output:
+   ```
+   File size: 1677804 bytes
+   Produced 1 WAV chunks: ['/tmp/tmp_chunk_000.wav']
+   [Debug] Transcribing WAV chunk: /tmp/tmp_chunk_000.wav
+   [Debug] Speech config obtained successfully
+   [Debug] Received 5 phrases
+   Creating 3 transcript pages
+   ```
+
+---
+
+## Troubleshooting
+
+### Error: NameResolutionError - Failed to resolve hostname
+
+**Symptom**: `Failed to resolve 'simplechat6-dev-speech.cognitiveservices.azure.com'`
+
+**Cause**: Custom subdomain not enabled on Speech resource
+
+**Solution**: Enable custom subdomain using Step 1 above
+
+### Error: 400 BadRequest when using MI with regional endpoint
+
+**Symptom**: `400 Client Error: BadRequest for url: https://eastus2.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe`
+
+**Cause**: Managed identity requires resource-specific endpoint, not regional
+
+**Solution**: Update Admin Settings endpoint to use `https://<resource-name>.cognitiveservices.azure.com`
+
+### Error: 401 Authentication error with MI
+
+**Symptom**: `WebSocket upgrade failed: Authentication error (401)`
+
+**Cause**: Missing RBAC role assignments
+
+**Solution**: Assign required roles using Step 2 above
+
+### Key auth works but MI fails
+
+**Diagnosis checklist**:
+- [ ] Custom subdomain enabled on Speech resource?
+- [ ] Admin Settings endpoint is resource-specific (not regional)?
+- [ ] Managed identity has RBAC roles on Speech resource?
+- [ ] Authentication Type set to "Managed Identity" in Admin Settings?
+
+---
+
+## Summary
+
+| Authentication Method | Endpoint Type | Example | Works? |
+|----------------------|---------------|---------|--------|
+| **Key** | Regional | `https://eastus2.api.cognitive.microsoft.com` | ✅ Yes |
+| **Key** | Resource-specific | `https://simplechat6-dev-speech.cognitiveservices.azure.com` | ✅ Yes |
+| **Managed Identity** | Regional | `https://eastus2.api.cognitive.microsoft.com` | ❌ No (400 BadRequest) |
+| **Managed Identity** | Resource-specific | `https://simplechat6-dev-speech.cognitiveservices.azure.com` | ✅ Yes (with custom subdomain) |
+
+**Key takeaway**: Managed identity for Azure Cognitive Services data-plane operations requires:
+1. Custom subdomain enabled on the resource
+2. Resource-specific endpoint configured in your application
+3. RBAC roles assigned to the managed identity at the resource scope
+
+---
+
+## References
+
+- [Azure Cognitive Services custom subdomain documentation](https://learn.microsoft.com/azure/cognitive-services/cognitive-services-custom-subdomains)
+- [Authenticate with Azure AD using managed identity](https://learn.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-azure-active-directory)
+- [Azure Speech Service authentication](https://learn.microsoft.com/azure/ai-services/speech-service/rest-speech-to-text-short)