Add custom subdomain support for OpenAI and Speech Service in Terraform

[vivche]

Overview

This update adds custom subdomain configuration for Azure OpenAI and Speech Service resources in the Terraform deployment template. Custom subdomains are required for managed identity (MI) authentication with Azure Cognitive Services data-plane operations.

Changes Made

1. Terraform Infrastructure Updates (main.tf)

Speech Service Resource

• Added speech_service_name to locals block for consistent naming
• Created new Speech Service resource (azurerm_cognitive_account.speech)
  • Kind: SpeechServices
  • SKU: S0 (Standard tier)
  • Custom subdomain: ${base_name}-${environment}-speech
  • Location: Matches resource group location

OpenAI Resource Enhancement

• Updated OpenAI resource with custom_subdomain_name = local.open_ai_name
• Ensures managed identity authentication works for existing and new deployments

RBAC Role Assignments

Added four new role assignments for Speech Service access:

Managed Identity:

• Cognitive Services Speech User
• Cognitive Services Speech Contributor

App Service System Managed Identity:

• Cognitive Services Speech User
• Cognitive Services Speech Contributor

2. Documentation

• Created comprehensive setup guide: docs/how-to/azure_speech_managed_identity_manul_setup.md
• Explains regional vs resource-specific endpoints
• Details why MI requires custom subdomain
• Includes troubleshooting steps

Why This Change is Needed

Problem

When using managed identity authentication with Azure Cognitive Services, the AAD bearer token doesn't identify which specific resource to access. This causes authentication failures when using regional (shared) endpoints like:

• https://eastus2.api.cognitive.microsoft.com (Speech)
• https://region.api.cognitive.microsoft.com (Generic)

Solution

Custom subdomains create unique, resource-specific endpoints:

• https://{resource-name}.cognitiveservices.azure.com (Speech)
• https://{resource-name}.openai.azure.com (OpenAI)

These endpoints allow Azure to identify the target resource and properly validate the managed identity's RBAC permissions.

Authentication Comparison

Authentication Method	Regional Endpoint	Resource-Specific Endpoint
API Key	✅ Works	✅ Works
Managed Identity	❌ Fails (400)	✅ Works

Bicep Template Compatibility

Good news: The Bicep templates in deployers/bicep/modules/ already include custom subdomain configuration:

• openai.bicep (line 34): customSubDomainName: toLower('${appName}-${environment}-openai')
• speechService.bicep (line 33): customSubDomainName: toLower('${appName}-${environment}-speech')

No Bicep changes needed for this feature.

Deployment Impact

New Deployments

• Speech Service resource will be created automatically with custom subdomain
• OpenAI resource will include custom subdomain from the start
• RBAC assignments for Speech Service will be configured
• Managed identity authentication will work immediately

Existing Deployments

If you have existing Speech or OpenAI resources without custom subdomains, you must manually enable them:

# For Speech Service
az cognitiveservices account update \
  --name <speech-resource-name> \
  --resource-group <resource-group> \
  --custom-domain <speech-resource-name>

# For OpenAI
az cognitiveservices account update \
  --name <openai-resource-name> \
  --resource-group <resource-group> \
  --custom-domain <openai-resource-name>

Important: Custom subdomain enablement is a one-way operation and cannot be disabled once set.

Testing Recommendations

1. New Deployment Test

# Deploy infrastructure
terraform init
terraform plan
terraform apply

# Verify Speech Service has custom subdomain
az cognitiveservices account show \
  --name <speech-service-name> \
  --resource-group <resource-group> \
  --query "{customSubDomain: properties.customSubDomainName, endpoint: properties.endpoint}"

# Verify DNS resolution
nslookup <speech-service-name>.cognitiveservices.azure.com

2. Managed Identity Authentication Test

• Configure Admin Settings with speech_service_authentication_type: managed_identity
• Upload a test audio file (WAV, MP3, or M4V)
• Monitor App Service logs for successful transcription
• Verify no DNS or 400 BadRequest errors

3. Validate RBAC Assignments

# Check Speech Service role assignments
az role assignment list \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<speech-name> \
  --output table

Expected roles:

• Managed Identity: Speech User + Speech Contributor
• App Service MI: Speech User + Speech Contributor

Breaking Changes

None. This is a backward-compatible enhancement:

• Existing deployments continue to work with API key authentication
• Managed identity authentication becomes available when configured
• No changes required to application code (fallback logic already implemented).