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).

[Copilot]

Pull request overview

This PR adds custom subdomain support for Azure OpenAI and Speech Service resources in the Terraform deployment template, enabling managed identity authentication for Azure Cognitive Services data-plane operations. The changes create a new Speech Service resource with proper RBAC assignments and update the OpenAI resource configuration to support managed identity authentication.

Key changes:

• Added Speech Service resource to Terraform with custom subdomain configuration
• Enhanced OpenAI resource with custom subdomain for managed identity support
• Created RBAC role assignments for both user-assigned and system-assigned managed identities on Speech Service
• Added comprehensive documentation explaining the technical requirements and setup process

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
deployers/terraform/main.tf	Added Speech Service resource definition with custom subdomain, updated OpenAI resource with custom subdomain configuration, and added four RBAC role assignments for Speech Service access (Speech User and Speech Contributor roles for both managed identity and App Service system identity)
docs/how-to/azure_speech_managed_identity_manul_setup.md	Created detailed setup guide explaining regional vs resource-specific endpoints, why managed identity requires custom subdomains, and includes step-by-step configuration instructions with troubleshooting guidance

The merge-base changed after approval.