Merge pull request #57 from Azure-Samples/feat/keyless-auth-local-dev

feat: implement keyless authentication for local development

Author: dbarkol

LOCAL_DEVELOPMENT.md

@@ -0,0 +1,130 @@
+# Local Development Setup
+
+This document explains how local development authentication works for this Azure Functions project.
+
+## Authentication Approach
+
+This project uses **Azure Managed Identity** for authentication - both in production AND for local development. **No API keys are required!**
+
+### How It Works
+
+1. **In Azure (Production)**: The Function App uses its User-Assigned Managed Identity with the `Cognitive Services OpenAI User` role
+2. **Locally**: Developers use their own Azure credentials via `az login` with the same role
+
+## Setup Steps
+
+### 1. Run `azd up` or `azd provision`
+
+When you provision the infrastructure, the Bicep deployment automatically:
+- Creates the Azure OpenAI resource
+- Assigns the `Cognitive Services OpenAI User` role to the Function App's managed identity
+- **Assigns the same role to YOU** (the person running `azd provision`)
+
+This is done via the `principalId` parameter in `main.bicep`:
+
+```bicep
+// This assigns the role to the person running azd provision
+module openaiRoleAssignmentDeveloper 'app/rbac/openai-access.bicep' = if (!empty(principalId)) {
+  name: 'openaiRoleAssignmentDeveloper'
+  scope: rg
+  params: {
+    openAIAccountName: openai.outputs.aiServicesName
+    roleDefinitionId: CognitiveServicesOpenAIUser
+    principalId: principalId  // Your user ID
+  }
+}
+```
+
+### 2. Make Sure You're Logged In
+
+```bash
+# Login to Azure
+az login
+
+# Verify you're using the correct subscription
+az account show
+```
+
+### 3. Generate local.settings.json
+
+```bash
+# Run the postprovision script
+./scripts/generate-settings.sh
+
+# Verify it was created (notice: no API key!)
+cat src/local.settings.json
+```
+
+### 4. Run the Function App Locally
+
+```bash
+cd src
+func start
+```
+
+The Azure Functions runtime will automatically use your Azure credentials via `DefaultAzureCredential`.
+
+## Benefits of This Approach
+
+✅ **No secrets to manage** - No API keys in config files or environment variables  
+✅ **More secure** - Credentials never leave Azure's identity system  
+✅ **Production parity** - Local dev works exactly like production  
+✅ **Automatic role assignment** - Developers get the right permissions when they provision  
+✅ **Audit trail** - All API calls are tied to specific user identities
+
+## Troubleshooting
+
+### Error: "Access denied" or "Unauthorized"
+
+1. **Check your Azure login**:
+   ```bash
+   az login
+   az account show
+   ```
+
+2. **Verify your role assignment**:
+   ```bash
+   # Get your user principal ID
+   az ad signed-in-user show --query id -o tsv
+   
+   # List role assignments (replace <resource-group> and <openai-name>)
+   az role assignment list --assignee <your-principal-id> \
+     --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<openai-name>
+   ```
+
+3. **If role is missing**, run `azd provision` again or manually assign:
+   ```bash
+   az role assignment create \
+     --role "Cognitive Services OpenAI User" \
+     --assignee <your-email-or-principal-id> \
+     --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<openai-name>
+   ```
+
+### For Additional Developers
+
+If other developers join the project:
+
+**Option 1: They run `azd provision`** (if they have subscription permissions)
+- This will automatically assign them the role
+
+**Option 2: Manually assign the role** (if you're the admin)
+```bash
+az role assignment create \
+  --role "Cognitive Services OpenAI User" \
+  --assignee <developer-email> \
+  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<openai-name>
+```
+
+## FAQ
+
+**Q: Do I need an API key for local development?**  
+A: No! Just make sure you're logged in with `az login`.
+
+**Q: What if I want to use an API key anyway?**  
+A: You can manually add `AZURE_OPENAI_KEY` to your `local.settings.json`, but it's not recommended. The keyless approach is more secure.
+
+**Q: Does this work in CI/CD pipelines?**  
+A: Yes! Use a service principal or managed identity for your CI/CD pipeline with the same role assignment.
+
+**Q: What about Cosmos DB access?**  
+A: Same approach! Your user is assigned `DocumentDB Account Contributor` role during provisioning (see the `cosmosDb` module in `main.bicep`).

infra/app/apim.bicep

@@ -24,6 +24,12 @@ param skuCapacity int = 1
 @allowed(['Enabled', 'Disabled'])
 param publicNetworkAccess string = 'Enabled'
 
+@description('App Registration Client ID for MCP')
+param appRegistrationClientId string = ''
+
+@description('Azure Entra Tenant ID')
+param tenantId string = tenant().tenantId
+
 resource apiManagement 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
   name: name
   location: location
@@ -50,6 +56,36 @@ resource apiManagement 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
   }
 }
 
+// Named Value: APIMGateway - APIM Gateway URL
+resource namedValueAPIMGateway 'Microsoft.ApiManagement/service/namedValues@2023-05-01-preview' = {
+  parent: apiManagement
+  name: 'APIMGateway'
+  properties: {
+    displayName: 'APIMGateway'
+    value: apiManagement.properties.gatewayUrl
+  }
+}
+
+// Named Value: McpClientID - App Registration Client ID
+resource namedValueMcpClientID 'Microsoft.ApiManagement/service/namedValues@2023-05-01-preview' = if (!empty(appRegistrationClientId)) {
+  parent: apiManagement
+  name: 'McpClientID'
+  properties: {
+    displayName: 'McpClientID'
+    value: appRegistrationClientId
+  }
+}
+
+// Named Value: McpTenantID - Azure Entra Tenant ID
+resource namedValueMcpTenantID 'Microsoft.ApiManagement/service/namedValues@2023-05-01-preview' = {
+  parent: apiManagement
+  name: 'McpTenantID'
+  properties: {
+    displayName: 'McpTenantID'
+    value: tenantId
+  }
+}
+
 // Outputs
 output apiManagementId string = apiManagement.id
 output apiManagementName string = apiManagement.name

infra/app/rbac/openai-access.bicep

@@ -7,6 +7,10 @@ param roleDefinitionId string
 @description('The principal ID to assign the role to')
 param principalId string
 
+@description('The type of principal (User, Group, or ServicePrincipal)')
+@allowed(['User', 'Group', 'ServicePrincipal'])
+param principalType string = 'ServicePrincipal'
+
 resource openAIAccount 'Microsoft.CognitiveServices/accounts@2023-05-01' existing = {
   name: openAIAccountName
 }
@@ -17,6 +21,6 @@ resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
   properties: {
     roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
     principalId: principalId
-    principalType: 'ServicePrincipal'
+    principalType: principalType
   }
 }

infra/app/util/region-selector.bicep

@@ -3,6 +3,18 @@ func getAdjustedRegion(location string, map object) string =>
 
 // See https://learn.microsoft.com/azure/ai-services/openai/concepts/models#model-summary-table-and-region-availability
 var modelRegionMap = {
+  'text-embedding-ada-002': {
+    // Widely available in most Azure OpenAI regions
+    supportedRegions: [
+      'australiaeast', 'brazilsouth', 'canadaeast', 'eastus', 'eastus2', 'francecentral', 'japaneast'
+      'northcentralus', 'norwayeast', 'southcentralus', 'swedencentral', 'switzerlandnorth', 'uksouth', 'westeurope', 'westus'
+    ]
+    overrides: {
+      westus2: 'westus'
+      westus3: 'westus'
+    }
+    default: 'eastus'
+  }
   'text-embedding-3-small': {
     // Currently supported regions: 
     //    Australia East, Canada East, East US, East US 2, Japan East, Switzerland North, UAE North, West US

infra/main.bicep

@@ -170,6 +170,19 @@ module openaiRoleAssignment 'app/rbac/openai-access.bicep' = {
     openAIAccountName: openai.outputs.aiServicesName
     roleDefinitionId: CognitiveServicesOpenAIUser
     principalId: apiUserAssignedIdentity.outputs.principalId
+    principalType: 'ServicePrincipal'
+  }
+}
+
+// Assign Cognitive Services OpenAI User role to the developer (for local development)
+module openaiRoleAssignmentDeveloper 'app/rbac/openai-access.bicep' = if (!empty(principalId)) {
+  name: 'openaiRoleAssignmentDeveloper'
+  scope: rg
+  params: {
+    openAIAccountName: openai.outputs.aiServicesName
+    roleDefinitionId: CognitiveServicesOpenAIUser
+    principalId: principalId
+    principalType: 'User'
   }
 }
 
@@ -237,7 +250,11 @@ module apim './app/apim.bicep' = {
     publisherEmail: apimPublisherEmail
     skuName: 'BasicV2'
     skuCapacity: 1
+    appRegistrationClientId: appRegistrationClientId
   }
+  dependsOn: [
+    appRegistration
+  ]
 }
 
 // App Registration for MCP Server

scripts/generate-settings.ps1

@@ -2,15 +2,14 @@
 
 # Get values from azd environment
 Write-Host "Getting environment values from azd..."
-$azdValues = azd env get-values
-$COSMOS_ENDPOINT = ($azdValues | Select-String 'COSMOS_ENDPOINT="(.*?)"').Matches.Groups[1].Value
-$PROJECT_CONNECTION_STRING = ($azdValues | Select-String 'PROJECT_CONNECTION_STRING="(.*?)"').Matches.Groups[1].Value
-$AZURE_OPENAI_ENDPOINT = ($azdValues | Select-String 'AZURE_OPENAI_ENDPOINT="(.*?)"').Matches.Groups[1].Value
-$AZURE_OPENAI_KEY = ($azdValues | Select-String 'AZURE_OPENAI_KEY="(.*?)"').Matches.Groups[1].Value
-$AZUREWEBJOBSSTORAGE = ($azdValues | Select-String 'AZUREWEBJOBSSTORAGE="(.*?)"').Matches.Groups[1].Value
+$envValues = azd env get-values | Out-String
+$cosmosEndpoint = ($envValues | Select-String 'COSMOS_ENDPOINT="([^"]*)"').Matches.Groups[1].Value
+$azureOpenAIEndpoint = ($envValues | Select-String 'AZURE_OPENAI_ENDPOINT="([^"]*)"').Matches.Groups[1].Value
+$azureWebJobsStorage = ($envValues | Select-String 'AZUREWEBJOBSSTORAGE="([^"]*)"').Matches.Groups[1].Value
 
-# Create the JSON content
-$jsonContent = @"
+# Create or update local.settings.json
+Write-Host "Generating local.settings.json in src directory..."
+$settingsJson = @"
 {
   "IsEncrypted": false,
   "Values": {
@@ -22,16 +21,17 @@ $jsonContent = @"
     "BLOB_CONTAINER_NAME": "snippet-backups",
     "EMBEDDING_MODEL_DEPLOYMENT_NAME": "text-embedding-3-small",
     "AGENTS_MODEL_DEPLOYMENT_NAME": "gpt-4o-mini",
-    "COSMOS_ENDPOINT": "$COSMOS_ENDPOINT",
-    "PROJECT_CONNECTION_STRING": "$PROJECT_CONNECTION_STRING",
-    "AZURE_OPENAI_ENDPOINT": "$AZURE_OPENAI_ENDPOINT",
-    "AZURE_OPENAI_KEY": "$AZURE_OPENAI_KEY"
+    "COSMOS_ENDPOINT": "$cosmosEndpoint",
+    "AZURE_OPENAI_ENDPOINT": "$azureOpenAIEndpoint"
   }
 }
 "@
 
-# Write content to local.settings.json
-$settingsPath = Join-Path (Get-Location) "src" "local.settings.json"
-$jsonContent | Out-File -FilePath $settingsPath -Encoding utf8
-
-Write-Host "local.settings.json generated successfully in src directory!"
+$settingsJson | Out-File -FilePath "src/local.settings.json" -Encoding utf8
+Write-Host ""
+Write-Host "✅ local.settings.json generated successfully!" -ForegroundColor Green
+Write-Host ""
+Write-Host "📝 Note: This configuration uses Azure credential authentication (no API key)." -ForegroundColor Cyan
+Write-Host "   - Make sure you're logged in: az login" -ForegroundColor Cyan
+Write-Host "   - You should have been automatically assigned the 'Cognitive Services OpenAI User' role" -ForegroundColor Cyan
+Write-Host "   - If you get authentication errors, verify your role assignment in the Azure Portal" -ForegroundColor Cyan

scripts/generate-settings.sh

@@ -3,9 +3,7 @@
 # Get values from azd environment
 echo "Getting environment values from azd..."
 COSMOS_ENDPOINT=$(azd env get-values | grep COSMOS_ENDPOINT | cut -d'"' -f2)
-PROJECT_CONNECTION_STRING=$(azd env get-values | grep PROJECT_CONNECTION_STRING | cut -d'"' -f2)
 AZURE_OPENAI_ENDPOINT=$(azd env get-values | grep AZURE_OPENAI_ENDPOINT | cut -d'"' -f2)
-AZURE_OPENAI_KEY=$(azd env get-values | grep AZURE_OPENAI_KEY | cut -d'"' -f2)
 AZUREWEBJOBSSTORAGE=$(azd env get-values | grep AZUREWEBJOBSSTORAGE | cut -d'"' -f2)
 
 # Create or update local.settings.json
@@ -23,11 +21,15 @@ cat > src/local.settings.json << EOF
     "EMBEDDING_MODEL_DEPLOYMENT_NAME": "text-embedding-3-small",
     "AGENTS_MODEL_DEPLOYMENT_NAME": "gpt-4o-mini",
     "COSMOS_ENDPOINT": "$COSMOS_ENDPOINT",
-    "PROJECT_CONNECTION_STRING": "$PROJECT_CONNECTION_STRING",
-    "AZURE_OPENAI_ENDPOINT": "$AZURE_OPENAI_ENDPOINT",
-    "AZURE_OPENAI_KEY": "$AZURE_OPENAI_KEY"
+    "AZURE_OPENAI_ENDPOINT": "$AZURE_OPENAI_ENDPOINT"
   }
 }
 EOF
 
-echo "local.settings.json generated successfully in src directory!"
+echo ""
+echo "✅ local.settings.json generated successfully!"
+echo ""
+echo "📝 Note: This configuration uses Azure credential authentication (no API key)."
+echo "   - Make sure you're logged in: az login"
+echo "   - You should have been automatically assigned the 'Cognitive Services OpenAI User' role"
+echo "   - If you get authentication errors, verify your role assignment in the Azure Portal"

src/local.settings.example.json

@@ -10,8 +10,6 @@
     "EMBEDDING_MODEL_DEPLOYMENT_NAME": "text-embedding-3-small",
     "AGENTS_MODEL_DEPLOYMENT_NAME": "gpt-4o",
     "COSMOS_ENDPOINT": "https://<cosmos-account-name>.documents.azure.com:443/",
-    "PROJECT_CONNECTION_STRING": "<region>.api.azureml.ms;<workspace-id>;<project-name>;<project-name>",
-    "AZURE_OPENAI_ENDPOINT": "https://<service-id>.openai.azure.com/",
-    "AZURE_OPENAI_KEY": "<your-azure-openai-key>"
+    "AZURE_OPENAI_ENDPOINT": "https://<service-id>.openai.azure.com/"
   }
 }