fix: Improve Deployment Docs, Single-Tenant Teams Extension, and Ingestion Error Handling (#1915)

Pavan-Microsoft · Roopan-Microsoft · AjitPadhi-Microsoft · web-flow · commit cb2e607edffc · 2025-09-22T23:13:33.000+05:30
Signed-off-by: dependabot[bot] &lt;support@github.com&gt;
Co-authored-by: Roopan-Microsoft &lt;168007406+Roopan-Microsoft@users.noreply.github.com&gt;
Co-authored-by: Ajit Padhi &lt;v-padhiajit@microsoft.com&gt;
Co-authored-by: Roopan P M &lt;v-roopanpm@microsoft.com&gt;
Co-authored-by: Ross Smith &lt;ross-p-smith@users.noreply.github.com&gt;
Co-authored-by: gpickett &lt;122489228+gpickett@users.noreply.github.com&gt;
Co-authored-by: Francia Riesco &lt;friesco@microsoft.com&gt;
Co-authored-by: Francia Riesco &lt;Fr4nc3@users.noreply.github.com&gt;
Co-authored-by: Prajwal D C &lt;v-dcprajwal@microsoft.com&gt;
Co-authored-by: Harmanpreet-Microsoft &lt;v-harmanprka@microsoft.com&gt;
Co-authored-by: UtkarshMishra-Microsoft &lt;v-utkamishra@microsoft.com&gt;
Co-authored-by: Priyanka-Microsoft &lt;v-prisinghal@microsoft.com&gt;
Co-authored-by: Prasanjeet-Microsoft &lt;v-singhprasa@microsoft.com&gt;
Co-authored-by: dependabot[bot] &lt;49699333+dependabot[bot]@users.noreply.github.com&gt;
Co-authored-by: Kiran-Siluveru-Microsoft &lt;v-ksiluveru@microsoft.com&gt;
Co-authored-by: Prashant-Microsoft &lt;v-pmalusare@microsoft.com&gt;
Co-authored-by: Rohini-Microsoft &lt;v-rwalunj@microsoft.com&gt;
Co-authored-by: Avijit-Microsoft &lt;v-aghorui@microsoft.com&gt;
Co-authored-by: RaviKiran-Microsoft &lt;v-ravikirans@microsoft.com&gt;
Co-authored-by: Somesh Joshi &lt;v-somejoshi@microsoft.com&gt;
Co-authored-by: Himanshi Agrawal &lt;v-himagrawal@microsoft.com&gt;
Co-authored-by: pradeepjha-microsoft &lt;v-pradeepjha@microsoft.com&gt;
Co-authored-by: Harmanpreet Kaur &lt;v-harmanpkau@microsoft.com&gt;
Co-authored-by: Bangarraju-Microsoft &lt;v-golib@microsoft.com&gt;
Co-authored-by: Harsh-Microsoft &lt;v-hbangera@microsoft.com&gt;
Co-authored-by: Kanchan-Microsoft &lt;v-knagshetti@microsoft.com&gt;
Co-authored-by: Cristopher Coronado &lt;cristofima@hotmail.com&gt;
Co-authored-by: Cristopher Coronado Moreira &lt;crcorona@pichincha.com&gt;
Co-authored-by: Vamshi-Microsoft &lt;v-vamolla@microsoft.com&gt;
Co-authored-by: Thanusree-Microsoft &lt;168087422+Thanusree-Microsoft@users.noreply.github.com&gt;
Co-authored-by: Niraj Chaudhari (Persistent Systems Inc) &lt;v-nirajcha@microsoft.com&gt;
Co-authored-by: Rohini-Microsoft &lt;168007985+Rohini-Microsoft@users.noreply.github.com&gt;
diff --git a/.github/workflows/group_dependabot_security_updates.yml b/.github/workflows/group_dependabot_security_updates.yml
@@ -65,9 +65,10 @@ jobs:
           git config --global user.email "github-actions@github.com"
 
       - name: Install required tools
-        uses: awalsh128/cache-apt-pkgs-action@v1.3.1
-        with:
-          packages: "jq gh"
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq gh
+        shell: bash
 
       - name: Enable strict error handling
         shell: bash
diff --git a/code/backend/pages/01_Ingest_Data.py b/code/backend/pages/01_Ingest_Data.py
@@ -55,7 +55,10 @@ def reprocess_all():
 
 def add_urls():
     urls = st.session_state["urls"].split("\n")
-    add_url_embeddings(urls)
+    result = add_url_embeddings(urls)
+    # If URLs are valid and processed, clear the textarea
+    if result:
+        st.session_state["urls"] = ""
 
 
 def sanitize_metadata_value(value):
@@ -67,7 +70,7 @@ def add_url_embeddings(urls: list[str]):
     has_valid_url = bool(list(filter(str.strip, urls)))
     if not has_valid_url:
         st.error("Please enter at least one valid URL.")
-        return
+        return False
 
     params = {}
     if env_helper.FUNCTION_KEY is not None:
@@ -80,9 +83,11 @@ def add_url_embeddings(urls: list[str]):
         )
         r = requests.post(url=backend_url, params=params, json=body)
         if not r.ok:
-            raise ValueError(f"Error {r.status_code}: {r.text}")
+            st.error(f"Error {r.status_code}: {r.text}")
+            return False
         else:
             st.success(f"Embeddings added successfully for {url}")
+    return True
 
 
 try:
diff --git a/docs/LOCAL_DEPLOYMENT.md b/docs/LOCAL_DEPLOYMENT.md
diff --git a/docs/teams_extension.md b/docs/teams_extension.md
@@ -16,7 +16,7 @@ This extension enables users to experience Chat with your data within Teams, wit
 ### Pre-requisites
 - [Visual Studio Code](https://code.visualstudio.com/)
     - Extensions
-        - [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) (optional: Teams extension only)
+        - [Microsoft 365 Agents Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) (optional: Teams extension only)
 - Install [Node.js](https://nodejs.org/en)
   - Install the LTS version (Recommended for Most Users)
 - [Enable custom Teams apps and turn on custom app uploading](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant#enable-custom-teams-apps-and-turn-on-custom-app-uploading) (optional: Teams extension only)
@@ -33,18 +33,18 @@ This extension enables users to experience Chat with your data within Teams, wit
 ![ENV](images/teams-1.png)
 
 4. Locate the environment variable _AZURE_FUNCTION_URL_.
-5. Replace the `<RESOURCE_TOKEN>`  and `<FUNCTION_APP_CLIENT_KEY>` with the name of your Function App resource and its clientKey (created in previous section)
+5. Replace the `<FUNCTION_APP_NAME>` and `<FUNCTION_KEY>` with your actual Function App name and function key
     ```env
-    AZURE_FUNCTION_URL=https://backend-<RESOURCE_TOKEN>.azurewebsites.net/api/GetConversationResponse?code=<FUNCTION_APP_CLIENT_KEY>&clientId=clientKey
+    AZURE_FUNCTION_URL=https://<FUNCTION_APP_NAME>.azurewebsites.net/api/GetConversationResponse?code=<FUNCTION_KEY>
 
     ```
     ![Env](images/teams-deploy-env.png)
 6. Save the file.
 7. Select Teams Toolkit from the navigation panel.
 
-![Teams Toolkit in VS Code](images/teams-2.png)
+![Microsoft 365 Agents Toolkit in VS Code](images/teams-2.png)
 
-8. Within the Teams Toolkit panel, login to the following accounts:
+8. Within the Microsoft 365 Agents Toolkit panel, login to the following accounts:
 
   **Sign in to Microsoft 365**: Use your Microsoft 365 work or school account with a valid E5 subscription for building your app. If you don't have a valid account, you can join [Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program) to get a free account before you start.
 
diff --git a/extensions/teams/config.ts b/extensions/teams/config.ts
@@ -2,6 +2,7 @@ const config = {
   botId: process.env.BOT_ID,
   botPassword: process.env.BOT_PASSWORD,
   azureFunctionUrl: process.env.AZURE_FUNCTION_URL,
+  tenantId: process.env.TEAMS_APP_TENANT_ID,
 };
 
 export default config;
diff --git a/extensions/teams/index.ts b/extensions/teams/index.ts
@@ -19,7 +19,8 @@ import config from "./config";
 const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
   MicrosoftAppId: config.botId,
   MicrosoftAppPassword: config.botPassword,
-  MicrosoftAppType: "MultiTenant",
+  MicrosoftAppType: "SingleTenant",
+  MicrosoftAppTenantId: config.tenantId
 });
 
 const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
diff --git a/extensions/teams/infra/azure.bicep b/extensions/teams/infra/azure.bicep
@@ -1,11 +1,14 @@
-@maxLength(20)
+@maxLength(25)
 @minLength(4)
 @description('Used to generate names for all resources in this file')
 param resourceBaseName string
 
 @description('Required when create Azure Bot service')
 param botAadAppClientId string
 
+@description('Required when using SingleTenant or UserAssignedMSI app type')
+param botAadAppTenantId string
+
 @secure()
 @description('Required by Bot Framework package in your bot project')
 param botAadAppClientSecret string
@@ -69,6 +72,10 @@ resource webApp 'Microsoft.Web/sites@2021-02-01' = {
           name: 'AZURE_FUNCTION_URL'
           value: azureFunctionURL
         }
+        {
+          name: 'TEAMS_APP_TENANT_ID'
+          value: botAadAppTenantId
+        }
       ]
       ftpsState: 'FtpsOnly'
     }
@@ -81,6 +88,7 @@ module azureBotRegistration './botRegistration/azurebot.bicep' = {
   params: {
     resourceBaseName: resourceBaseName
     botAadAppClientId: botAadAppClientId
+    botAadAppTenantId: botAadAppTenantId
     botAppDomain: webApp.properties.defaultHostName
     botDisplayName: botDisplayName
   }
diff --git a/extensions/teams/infra/azure.parameters.json b/extensions/teams/infra/azure.parameters.json
@@ -8,6 +8,9 @@
     "botAadAppClientId": {
       "value": "${{BOT_ID}}"
     },
+    "botAadAppTenantId": {
+      "value": "${{TEAMS_APP_TENANT_ID}}"
+    },
     "botAadAppClientSecret": {
       "value": "${{SECRET_BOT_PASSWORD}}"
     },
diff --git a/extensions/teams/infra/botRegistration/azurebot.bicep b/extensions/teams/infra/botRegistration/azurebot.bicep
@@ -1,4 +1,4 @@
-@maxLength(20)
+@maxLength(25)  // Changed from 20 to 25 to match parent template
 @minLength(4)
 @description('Used to generate names for all resources in this file')
 param resourceBaseName string
@@ -10,24 +10,27 @@ param botServiceName string = resourceBaseName
 param botServiceSku string = 'F0'
 param botAadAppClientId string
 param botAppDomain string
+param botAadAppTenantId string
 
 // Register your web service as a bot with the Bot Framework
-resource botService 'Microsoft.BotService/botServices@2021-03-01' = {
+resource botService 'Microsoft.BotService/botServices@2023-09-15-preview' = {
   kind: 'azurebot'
   location: 'global'
   name: botServiceName
   properties: {
     displayName: botDisplayName
     endpoint: 'https://${botAppDomain}/api/messages'
     msaAppId: botAadAppClientId
+    msaAppType: 'SingleTenant'
+    msaAppTenantId: botAadAppTenantId
   }
   sku: {
     name: botServiceSku
   }
 }
 
 // Connect the bot service to Microsoft Teams
-resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2021-03-01' = {
+resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2023-09-15-preview' = {
   parent: botService
   location: 'global'
   name: 'MsTeamsChannel'
diff --git a/extensions/teams/package.json b/extensions/teams/package.json
@@ -16,7 +16,8 @@
         "build": "tsc --build",
         "start": "node ./lib/index.js",
         "watch": "nodemon --exec \"npm run start\"",
-        "test": "echo \"Error: no test specified\" && exit 1"
+        "test": "echo \"Error: no test specified\" && exit 1",
+        "enable-sp": "node ./scripts/enable-service-principal.js"
     },
     "repository": {
         "type": "git",
diff --git a/extensions/teams/scripts/enable-service-principal.js b/extensions/teams/scripts/enable-service-principal.js
@@ -0,0 +1,46 @@
+// Script to create a service principal for the Microsoft Entra application
+const { exec } = require('child_process');
+const util = require('util');
+const execPromise = util.promisify(exec);
+
+async function createServicePrincipal() {
+  const appId = process.env.BOT_ID;
+  
+  if (!appId) {
+    console.error('Error: BOT_ID environment variable is not set');
+    process.exit(1);
+  }
+  
+  try {
+    // Check if Azure CLI is installed and logged in
+    await execPromise('az account show');
+    
+    // Check if service principal already exists
+    const checkCmd = `az ad sp list --filter "appId eq '${appId}'"`;
+    const { stdout } = await execPromise(checkCmd);
+    
+    const existingSpList = JSON.parse(stdout);
+    if (existingSpList && existingSpList.length > 0) {
+      console.log(`Service principal for application ID ${appId} already exists. Skipping creation.`);
+      process.exit(0);
+    }
+    
+    // Create service principal
+    const createCmd = `az ad sp create --id "${appId}"`;
+    await execPromise(createCmd);
+    
+    console.log('Service principal created successfully.');
+  } catch (error) {
+    console.error('Error:', error.message);
+    if (error.message.includes('az: not found') || error.message.includes('not recognized as an internal or external command')) {
+      console.error('Azure CLI is not installed or not in PATH. Please install it first.');
+    } else if (error.message.includes('Please run az login')) {
+      console.error('You are not logged into Azure. Please run az login first.');
+    } else {
+      console.error('Failed to create service principal. Please ensure you have the right permissions.');
+    }
+    process.exit(1);
+  }
+}
+
+createServicePrincipal();
diff --git a/extensions/teams/teamsapp.yml b/extensions/teams/teamsapp.yml
@@ -27,6 +27,14 @@ provision:
       botId: BOT_ID
       # The Microsoft Entra application's client secret created for bot.
       botPassword: SECRET_BOT_PASSWORD
+      
+  # Create service principal for the Microsoft Entra application
+  - uses: cli/runNpmCommand
+    name: Enable Service Principal
+    with:
+      args: run enable-sp
+    env:
+      BOT_ID: ${{BOT_ID}}
 
   - uses: arm/deploy # Deploy given ARM templates parallelly.
     with:
diff --git a/extensions/teams/tsconfig.json b/extensions/teams/tsconfig.json
@@ -2,7 +2,8 @@
   "compilerOptions": {
     "declaration": true,
     "target": "es2021",
-    "module": "commonjs",
+    "module": "node16",
+    "moduleResolution": "node16",
     "outDir": "./lib",
     "rootDir": "./",
     "sourceMap": true,
diff --git a/infra/main.bicep b/infra/main.bicep
@@ -1344,6 +1344,7 @@ module function 'modules/app/function.bicep' = {
         DATABASE_TYPE: databaseType
         MANAGED_IDENTITY_CLIENT_ID: managedIdentityModule.outputs.clientId
         MANAGED_IDENTITY_RESOURCE_ID: managedIdentityModule.outputs.resourceId
+        AZURE_CLIENT_ID: managedIdentityModule.outputs.clientId // Required so LangChain AzureSearch vector store authenticates with this user-assigned managed identity
         APP_ENV: appEnvironment
       },
       databaseType == 'CosmosDB'
diff --git a/infra/main.json b/infra/main.json
diff --git a/infra/main.parameters.json b/infra/main.parameters.json
diff --git a/infra/main.waf.parameters.json b/infra/main.waf.parameters.json
