From 24c1acb55060a708e1e9b93b1daa6fb1fd81e7df Mon Sep 17 00:00:00 2001 From: Pranjal-MSFT Date: Fri, 27 Mar 2026 14:27:15 +0530 Subject: [PATCH 01/11] Update add-authentication.md --- .../authentication/add-authentication.md | 181 ++++++++++++------ 1 file changed, 118 insertions(+), 63 deletions(-) diff --git a/msteams-platform/bots/how-to/authentication/add-authentication.md b/msteams-platform/bots/how-to/authentication/add-authentication.md index d4793477efb..84239bbd783 100644 --- a/msteams-platform/bots/how-to/authentication/add-authentication.md +++ b/msteams-platform/bots/how-to/authentication/add-authentication.md @@ -5,7 +5,7 @@ description: Learn how to enable authentication using third-party provider to a ms.topic: how-to ms.localizationpriority: high ms.owner: ryanbliss -ms.date: 03/16/2026 +ms.date: 03/27/2026 --- # Add authentication to your Teams bot @@ -32,11 +32,11 @@ In this article you'll learn: - Azure account. If needed, you can create an [Azure free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). - The following sample: - | Sample | BotBuilder version | Demonstrates | + | Sample | |:---|:---:|:---| - | **Bot authentication** in [cs-auth-sample][teams-auth-bot-cs] | v4 | OAuthCard support | - | **Bot authentication** in [js-auth-sample][teams-auth-bot-js] | v4 | OAuthCard support | - | **Bot authentication** in [py-auth-sample][teams-auth-bot-py] | v4 | OAuthCard support | + | **Bot authentication** in [cs-auth-sample][teams-auth-bot-cs] | + | **Bot authentication** in [js-auth-sample][teams-auth-bot-js] | + | **Bot authentication** in [py-auth-sample][teams-auth-bot-py] | ## Create the resource group @@ -92,7 +92,7 @@ The Azure Bot resource registration registers your web service as a bot with the 1. Select **Type of App** as **User-Assigned Managed Identity** or **Single Tenant** for **Microsoft App ID**. >[!IMPORTANT] - > The **Multi Tenant** bot type in **Azure Bot Service** is deprecated. Existing Multi Tenant bots continues to work for now.
All new bot registrations must either use the **Single Tenant** bot type or the **User-Assigned Managed Identity** type.
When registering your Entra app in Azure portal, you can still select the **Accounts in any organizational directory (Multi Tenant)** option. This enables your bot to work across multiple tenants, even outside the tenant where the app is registered, when using one of the supported bot types.
In all cases, the **MicrosoftAppTenantId** must be set to the **Tenant ID of the Azure tenant where the Microsoft Entra ID app is registered**. + > The **Multi Tenant** bot type in **Azure Bot Service** is deprecated. Existing Multi Tenant bots continues to work for now.
All new bot registrations must either use the **Single Tenant** bot type or the **User-Assigned Managed Identity** type.
When registering your Entra app in Azure portal, you can still select the **Accounts in any organizational directory (Multi Tenant)** option. This enables your bot to work across multiple tenants, even outside the tenant where the app is registered, when using one of the supported bot types.
In all cases, the **TENANT_ID** must be set to the **Tenant ID of the Azure tenant where the Microsoft Entra ID app is registered**. :::image type="content" source="../../../assets/images/adaptive-cards/single-tenant.png" alt-text="Screenshot shows how to select multitenant for Microsoft AppID."::: @@ -292,9 +292,9 @@ With the preliminary settings done, let's focus on the creation of the bot to us 1. From the toolbar, select **File > Open > Project/Solution** and open the bot project. 1. In C#, Update **appsettings.json** as follows: - - Set `ConnectionName` to the name of the identity provider connection you added to the bot registration. The name we used in this example is *BotTeamsAuthADv1*. - - Set `MicrosoftAppId` to the **bot App ID** you saved at the time of the bot registration. - - Set `MicrosoftAppPassword` to the **customer secret** you saved at the time of the bot registration. + - Set `CONNECTION_NAME` to the name of the identity provider connection you added to the bot registration. The name we used in this example is *BotTeamsAuthADv1*. + - Set `CLIENT_ID` to the **bot App ID** you saved at the time of the bot registration. + - Set `CLIENT_SECRET` to the **customer secret** you saved at the time of the bot registration. Depending on the characters in your bot secret, you might need to XML escape the password. For example, any ampersands (&) must be encoded as `&`. @@ -314,9 +314,9 @@ With the preliminary settings done, let's focus on the creation of the bot to us `npm install` 1. Update the **.env** configuration as follows: - - Set `MicrosoftAppId` to the **bot App ID** you saved at the time of the bot registration. - - Set `MicrosoftAppPassword` to the **customer secret** you saved at the time of the bot registration. - - Set the `connectionName` to the name of the identity provider connection. + - Set `CLIENT_ID` to the **bot App ID** you saved at the time of the bot registration. + - Set `CLIENT_SECRET` to the **customer secret** you saved at the time of the bot registration. + - Set the `CONNECTION_NAME` to the name of the identity provider connection. Depending on the characters in your bot secret, you might need to XML escape the password. For example, any ampersands (&) must be encoded as `&`. [!code-javascript[settings](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/.env)] @@ -331,8 +331,8 @@ With the preliminary settings done, let's focus on the creation of the bot to us 1. Clone [py-auth-sample][teams-auth-bot-py] from the GitHub repository. 1. Update **config.py**: - - Set `ConnectionName` to the name of the OAuth connection setting you added to your bot. - - Set `MicrosoftAppId` and `MicrosoftAppPassword` to your bot's app ID and app secret. + - Set `CONNECTION_NAME` to the name of the OAuth connection setting you added to your bot. + - Set `CLIENT_ID` and `CLIENT_SECRET` to your bot's app ID and app secret. Depending on the characters in your bot secret, you might need to XML escape the password. For example, any ampersands (&) must be encoded as `&`. @@ -538,48 +538,103 @@ It launches ngrok to listen on the port you specify. In return, it gives you an This manifest contains information needed by Teams to connect with the bot: ```json -{ - "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json", - "manifestVersion": "1.5", - "version": "1.0.0", - "id": "", - "developer": { - "name": "TeamsBotAuth", - "websiteUrl": "https://www.microsoft.com", - "privacyUrl": "https://www.teams.com/privacy", - "termsOfUseUrl": "https://www.teams.com/termsofuse" - }, - "icons": { - "color": "color.png", - "outline": "outline.png" - }, - "name": { - "short": "TeamsBotAuth", - "full": "Teams Bot Authentication" - }, - "description": { - "short": "TeamsBotAuth", - "full": "Teams Bot Authentication" - }, - "accentColor": "#FFFFFF", - "bots": [ - { - "botId": "", - "scopes": [ - "personal", - "groupchat", - "team" - ], - "supportsFiles": false, - "isNotificationOnly": false - } - ], - "permissions": [ - "identity", - "messageTeamMembers" - ], - "validDomains": [ "token.botframework.com" ] -} +{ + + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json", + + "manifestVersion": "1.19", + + "version": "1.0.0", + + "id": "${{TEAMS_APP_ID}}", + + "developer": { + + "name": "Teams App, Inc.", + + "websiteUrl": "https://example.azurewebsites.net", + + "privacyUrl": "https://example.azurewebsites.net/privacy", + + "termsOfUseUrl": "https://example.azurewebsites.net/termsofuse" + + }, + + "icons": { + + "color": "color.png", + + "outline": "outline.png" + + }, + + "name": { + + "short": "Auth Bot", + + "full": "Auth Bot" + + }, + + "description": { + + "short": "Teams bot with SSO authentication and Graph API integration.", + + "full": "This bot demonstrates SSO authentication in Microsoft Teams using Azure AD, and uses Microsoft Graph API to retrieve the user profile." + + }, + + "accentColor": "#FFFFFF", + + "bots": [ + + { + + "botId": "${{BOT_ID}}", + + "scopes": [ + + "personal", + + "groupChat", + + "team" + + ], + + "supportsFiles": false, + + "isNotificationOnly": false + + } + + ], + + "permissions": [ + + "identity", + + "messageTeamMembers" + + ], + + "validDomains": [ + + "token.botframework.com", + + "${{BOT_DOMAIN}}" + + ], + + "webApplicationInfo": { + + "id": "${{BOT_ID}}", + + "resource": "api://botid-${{BOT_ID}}" + + } + +} ``` With authentication, Teams behaves differently than other channels. @@ -693,12 +748,12 @@ Within the following dialog step, check for the presence of a token in the resul ## Code sample -This section provides Bot authentication v3 SDK sample. +This sample demonstrates how to implement Single Sign-On (SSO) authentication for Microsoft Teams bots using Azure Active Directory. -| **Sample name** | **Description** | **.NET** | **Node.js** | **Python** | **Manifest**| +| **Sample name** | **Description** | **.NET** | **Node.js** | **Python** | |---------------|------------|------------|-------------|---------------|---------------| -| Bot authentication | This sample app demonstrates how a bot can use Teams authentication. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/nodejs) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/python) |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/csharp/demo-manifest/bot-teams-authentication.zip) -| Tab, Bot, and Message Extension (ME) SSO | This sample app demonstrates Teams SSO integration for tabs, bots, and message extensions, using C# and Microsoft Entra ID for secure authentication. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsJS/app-sso/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsJS/app-sso/nodejs) | NA | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsJS/app-sso/csharp/demo-manifest/App-SSO.zip) +| Bot Auth Quickstart | This sample demonstrates how to implement Single Sign-On (SSO) authentication for Microsoft Teams bots using Azure Active Directory. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/dotnet/bot-auth-quickstart) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/nodejs/bot-auth-quickstart) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/python/bot-auth-quickstart) | +| Tab, Bot, and Message Extension (ME) SSO | This sample app demonstrates Teams SSO integration for tabs, bots, and message extensions, using C# and Microsoft Entra ID for secure authentication. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsJS/app-sso/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsJS/app-sso/nodejs) | NA | ## See also @@ -714,8 +769,8 @@ This section provides Bot authentication v3 SDK sample. [concept-dialogs]: /azure/bot-service/bot-builder-concept-dialog?view=azure-bot-service-4.0&preserve-view=true [simple-dialog]: /azure/bot-service/bot-builder-dialog-manage-conversation-flow?view=azure-bot-service-4.0&preserve-view=true -[teams-auth-bot-cs]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/csharp +[teams-auth-bot-cs]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/dotnet/bot-auth-quickstart -[teams-auth-bot-py]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/python +[teams-auth-bot-py]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/python/bot-auth-quickstart -[teams-auth-bot-js]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-teams-authentication/nodejs +[teams-auth-bot-js]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/nodejs/bot-auth-quickstart From a125c6d4bbfbc54631a43b58ab5bcdc4929d9f2f Mon Sep 17 00:00:00 2001 From: Pranjal-MSFT Date: Fri, 27 Mar 2026 15:48:45 +0530 Subject: [PATCH 02/11] Update add-authentication.md --- .../authentication/add-authentication.md | 157 ++---------------- 1 file changed, 11 insertions(+), 146 deletions(-) diff --git a/msteams-platform/bots/how-to/authentication/add-authentication.md b/msteams-platform/bots/how-to/authentication/add-authentication.md index 84239bbd783..da820194361 100644 --- a/msteams-platform/bots/how-to/authentication/add-authentication.md +++ b/msteams-platform/bots/how-to/authentication/add-authentication.md @@ -10,14 +10,12 @@ ms.date: 03/27/2026 # Add authentication to your Teams bot -You can create bots in Microsoft Teams that access resources on behalf of the user, such as a mail service. You can use Azure Bot Service v4 SDK authentication, based on OAuth 2.0. This method makes it easier to develop a bot that can use authentication tokens based on the user's credentials. The key is the use of **identity providers**. +You can create bots in Microsoft Teams that access resources on behalf of the user, such as a mail service. You can use Teams SDK authentication, based on OAuth 2.0. This method makes it easier to develop a bot that can use authentication tokens based on the user's credentials. The key is the use of **identity providers**. OAuth 2.0 is an open standard for authentication and authorization used by Microsoft Entra ID and many other identity providers. A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams. See [OAuth 2 Simplified](https://aka.ms/oauth2-simplified) for a basic understanding, and [OAuth 2.0](https://oauth.net/2/) for the complete specification. -For more information about how the Azure Bot Service handles authentication, see [user authentication within a conversation](/azure/bot-service/bot-builder-concept-authentication?view=azure-bot-service-4.0&preserve-view=true). - In this article you'll learn: - **How to create an authentication-enabled bot**. Use [cs-auth-sample][teams-auth-bot-cs] to handle user sign-in credentials and the generating the authentication token. @@ -26,7 +24,7 @@ In this article you'll learn: ## Prerequisites -- Knowledge of [bot basics][concept-basics], [managing state][concept-state], the [dialogs library][concept-dialogs], and how to [implement sequential conversation flow][simple-dialog]. +- Knowledge of [bot basics](/microsoftteams/platform/bots/bot-concepts) and the [Teams SDK](/microsoftteams/platform/bots/bot-concepts). - Knowledge of Azure and OAuth 2.0 development. - The latest versions of Microsoft Visual Studio and Git. - Azure account. If needed, you can create an [Azure free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). @@ -42,7 +40,7 @@ In this article you'll learn: The resource group and the service plan aren't strictly necessary, but they allow you to conveniently release the resources you create. We recommend that you keep your resources organized and manageable. -You use a resource group to create individual resources for the Bot Framework. For performance, ensure that these resources are located in the same Azure region. +You use a resource group to create individual resources for the bot. For performance, ensure that these resources are located in the same Azure region. 1. In your browser, sign into the [**Microsoft Azure portal**][azure-portal]. 1. In the left navigation panel, select **Resource groups**. @@ -79,10 +77,10 @@ You use a resource group to create individual resources for the Bot Framework. F ## Create Azure Bot resource registration -The Azure Bot resource registration registers your web service as a bot with the Bot Framework, which provides you with a Microsoft App ID and App password (client secret). +The Azure Bot resource registration registers your web service as a bot with the Azure Bot Service, which provides you with a Microsoft App ID and App password (client secret). > [!IMPORTANT] -> You only need to register your bot if it's not hosted in Azure. If you [created a bot](/azure/bot-service/abs-quickstart?view=azure-bot-service-4.0&viewFallbackFrom=azure-bot-service-3.0&preserve-view=true) through the Azure portal then it's already registered with the service. If you created your bot through the [Bot Framework](https://dev.botframework.com/bots/new) or [Developer Portal](../../../concepts/build-and-test/teams-developer-portal.md) your bot isn't registered in Azure. +> You only need to register your bot if it's not hosted in Azure. If you [created a bot](/azure/bot-service/abs-quickstart?view=azure-bot-service-4.0&viewFallbackFrom=azure-bot-service-3.0&preserve-view=true) through the Azure portal then it's already registered with the service. If you created your bot through the [Developer Portal](../../../concepts/build-and-test/teams-developer-portal.md) your bot isn't registered in Azure. 1. Visit [**Azure portal**][azure-portal] and search for **Azure Bot** in **Create a resource** section. 1. Open the **Azure Bot** and select **Create**. @@ -375,30 +373,7 @@ Alternatively, while in Visual Studio, you can follow these steps: > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Deploy+the+bot+to+Azure&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cpython-sample%23deploy-the-bot-to-azure&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) -## Test the bot using the Emulator - -Install [Microsoft Bot Framework Emulator](https://aka.ms/bot-framework-emulator-readme). For more information, see [test and debug with the Emulator](/azure/bot-service/bot-service-debug-emulator?view=azure-bot-service-4.0&tabs=csharp&preserve-view=true). - -In order for the bot sample sign-in to work, you must configure the Emulator. - -### Configure the Emulator for authentication - -If a bot requires authentication, you must configure the Emulator. To configure: - -1. Start the Emulator. -1. In the Emulator, select the gear icon ⚙ in the bottom left, or the **Emulator Settings** tab in the upper right. -1. Check the box by **Use version 1.0 authentication tokens**. -1. Enter the local path to the **ngrok** tool. *See* the Bot Framework Emulator / ngrok tunneling integration [Wiki](https://github.com/Microsoft/BotFramework-Emulator/wiki/Tunneling-(ngrok)). For more tool information, see [ngrok](https://ngrok.com/). -1. Check the box by **Run ngrok when the Emulator starts up**. -1. Select the **Save** button. - -When the bot displays a sign-in card and the user selects the sign-in button, the Emulator opens a page that the user can use to sign in with the authentication provider. -Once the user does so, the provider generates a user token and sends it to the bot. After that, the bot can act on behalf of the user. - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Configure+the+Emulator+for+authentication&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cpython-sample%23configure-the-emulator-for-authentication&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -### Test the bot locally +## Test the bot locally After you configure the authentication mechanism, you can perform the actual bot testing. @@ -433,7 +408,7 @@ After you configure the authentication mechanism, you can perform the actual bot It releases the user token, and the bot won't be able to act on your behalf until you sign in again. > [!NOTE] -> Bot authentication requires use of the **Bot Connector Service**. The service accesses the bots registration information for your bot. +> Bot authentication requires use of the **Azure Bot Service**. The service accesses the bot registration information for your bot. > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Test+the+bot+locally&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cdotnet-sample%23test-the-bot-locally&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -466,7 +441,7 @@ and when for these, and just reference that from here, along with the set of ste > [!NOTE] > If you're having problems signing in, try to test the connection again as described in the previous steps. This could recreate the authentication token. -> With the Bot Framework Web Chat client in Azure, you may need to sign in several times before the authentication is established correctly. +> With the Web Chat client in Azure, you may need to sign in several times before the authentication is established correctly. > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Test+the+deployed+bot&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cdotnet-sample%23test-the-deployed-bot&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -520,7 +495,7 @@ It launches ngrok to listen on the port you specify. In return, it gives you an 1. In the left panel, select **Settings**. 1. In the right panel, in the **Messaging endpoint** box, enter the ngrok URL, in our example, `https://dea822bf.ngrok.io/api/messages`. 1. Start your bot locally, for example in Visual Studio debug mode. -1. Test the bot while running locally using the Bot Framework portal's **Test Web chat**. Like the Emulator, this test doesn't allow you to access Teams-specific functionality. +1. Test the bot while running locally using the Azure portal's **Test in Web Chat**. 1. In the terminal window where `ngrok` is running you can see HTTP traffic between the bot and the web chat client. If you want a more detailed view, in a browser window enter `http://127.0.0.1:4040` you obtained from the previous terminal window. The following image is an example: :::image type="content" source="../../../assets/images/authentication/auth-bot-teams-ngrok-testing.png" alt-text="Screenshot shows auth bot teams ngrok testing."::: @@ -540,9 +515,9 @@ This manifest contains information needed by Teams to connect with the bot: ```json { - "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.22/MicrosoftTeams.schema.json", - "manifestVersion": "1.19", + "manifestVersion": "1.22", "version": "1.0.0", @@ -642,110 +617,6 @@ With authentication, Teams behaves differently than other channels. > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+TeamsAppManifest%2Fmanifest.json&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cpython-sample%23teamsappmanifestmanifestjson&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) -### Handling Invoke Activity - -An **Invoke Activity** is sent to the bot rather than the Event Activity used by other channels, which is done by subclassing the **ActivityHandler**. - -# [C#/.NET](#tab/dotnet-sample) - -**Bots/DialogBot.cs** - -[!code-csharp[ActivityHandler](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/csharp/Bots/DialogBot.cs?range=19-51)] - -**Bots/TeamsBot.cs** - -The *Invoke Activity* must be forwarded to the dialog if the **OAuthPrompt** is used. - -[!code-csharp[ActivityHandler](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/csharp/Bots/TeamsBot.cs?range=34-42)] - -#### TeamsActivityHandler.cs - -```csharp - -protected virtual Task OnInvokeActivityAsync(ITurnContext turnContext, CancellationToken cancellationToken) -{ - switch (turnContext.Activity.Name) - { - case "signin/verifyState": - return OnSigninVerifyStateAsync(turnContext, cancellationToken); - - default: - return Task.CompletedTask; - } -} - -protected virtual Task OnSigninVerifyStateAsync(ITurnContext turnContext, CancellationToken cancellationToken) -{ - return Task.CompletedTask; -} -``` - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Handling+Invoke+Activity+using+C%23%2F.NET&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cdotnet-sample%23handling-invoke-activity&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -# [JavaScript](#tab/node-js-dialog-sample) - -**bots/dialogBot.js** - -[!code-javascript[ActivityHandler](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/bots/dialogBot.js?range=4-46)] - -**bots/teamsBot.js** - -The *Invoke Activity* must be forwarded to the dialog if the **OAuthPrompt** is used. - -[!code-javascript[ActivityHandler](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/bots/teamsBot.js?range=4-33)] - -**dialogs/mainDialog.js** - -Within a dialog step, use `beginDialog` to start the OAuth prompt, which asks the user to sign in. - -- If the user is already signed in, it generates a token response event, without prompting the user. -- Otherwise, it prompts the user to sign in. The Azure Bot Service sends the token response event after the user attempts to sign in. - -[!code-javascript[AddOAuthPrompt](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/dialogs/mainDialog.js?range=50-52)] - -Within the following dialog step, check for the presence of a token in the result from the previous step. If it isn't null, then the user successfully signed in. - -[!code-javascript[AddOAuthPrompt](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/dialogs/mainDialog.js?range=50-64)] - -**dialogs/logoutDialog.js** - -[!code-javascript[allow-logout](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/dialogs/logoutDialog.js?range=31-42&highlight=7)] - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Handling+Invoke+Activity+using+JavaScript&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cnode-js-dialog-sample%23handling-invoke-activity&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -# [Python](#tab/python-sample) - -**bots/dialog_bot.py** - -[!code-python[ActivityHandler](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/python/bots/dialog_bot.py?range=10-42)] - -**bots/teams_bot.py** - -The *Invoke Activity* must be forwarded to the dialog if the **OAuthPrompt** is used. - -[!code-python[on_token_response_event](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/python/bots/teams_bot.py?range=38-45)] - -**dialogs/main_dialog.py** - -Within a dialog step, use `begin_dialog` to start the OAuth prompt, which asks the user to sign in. If the user is already signed in, it generates a token response event, without prompting the user. Otherwise, it prompts the user to sign in. The Azure Bot Service sends the token response event after the user attempts to sign in. - -[!code-python[Add OAuthPrompt](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/python/dialogs/main_dialog.py?range=48-49)] - -Within the following dialog step, check for the presence of a token in the result from the previous step. If it isn't null, then the user successfully signed in. - -[!code-python[Add OAuthPrompt](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/python/dialogs/main_dialog.py?range=51-61)] - -**dialogs/logout_dialog.py** - -[!code-python[allow logout](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/python/dialogs/logout_dialog.py?range=29-36&highlight=6)] - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Handling+Invoke+Activity+using+Python&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cpython-sample%23handling-invoke-activity&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - ---- - ## Code sample This sample demonstrates how to implement Single Sign-On (SSO) authentication for Microsoft Teams bots using Azure Active Directory. @@ -757,18 +628,12 @@ This sample demonstrates how to implement Single Sign-On (SSO) authentication fo ## See also -- [Add authentication through Azure Bot Service](/azure/bot-service/bot-builder-authentication?view=azure-bot-service-4.0&tabs=userassigned%2Caadv2%2Ccsharp&preserve-view=true) - [Get access on behalf of a user](/graph/auth-v2-user) [azure-portal]: https://ms.portal.azure.com -[concept-basics]: /azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0&preserve-view=true -[concept-state]: /azure/bot-service/bot-builder-concept-state?view=azure-bot-service-4.0&preserve-view=true -[concept-dialogs]: /azure/bot-service/bot-builder-concept-dialog?view=azure-bot-service-4.0&preserve-view=true -[simple-dialog]: /azure/bot-service/bot-builder-dialog-manage-conversation-flow?view=azure-bot-service-4.0&preserve-view=true - [teams-auth-bot-cs]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/dotnet/bot-auth-quickstart [teams-auth-bot-py]: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-auth-quickstart/python/bot-auth-quickstart From 664073d2ba4ae60e8abc07d9a89a10cd67f38d36 Mon Sep 17 00:00:00 2001 From: Pranjal-MSFT Date: Mon, 30 Mar 2026 15:28:06 +0530 Subject: [PATCH 03/11] Update add-authentication.md --- .../authentication/add-authentication.md | 83 +++++++------------ 1 file changed, 30 insertions(+), 53 deletions(-) diff --git a/msteams-platform/bots/how-to/authentication/add-authentication.md b/msteams-platform/bots/how-to/authentication/add-authentication.md index da820194361..07a9e1d5cc0 100644 --- a/msteams-platform/bots/how-to/authentication/add-authentication.md +++ b/msteams-platform/bots/how-to/authentication/add-authentication.md @@ -1,6 +1,6 @@ --- title: OAuth 2.0 Bot Authentication with Azure -author: surbhigupta +author: vikasalmal description: Learn how to enable authentication using third-party provider to a bot app in Teams using Entra ID. Learn to create and register bot resource group and service plan. ms.topic: how-to ms.localizationpriority: high @@ -19,7 +19,7 @@ See [OAuth 2 Simplified](https://aka.ms/oauth2-simplified) for a basic understan In this article you'll learn: - **How to create an authentication-enabled bot**. Use [cs-auth-sample][teams-auth-bot-cs] to handle user sign-in credentials and the generating the authentication token. -- **How to deploy the bot to Azure and associate it with an identity provider**. The provider issues a token based on user sign-in credentials. The bot can use the token to access resources, such as a mail service, which require authentication. For more information, see [Microsoft Teams authentication flow for bots](auth-flow-bot.md). +- **How to deploy the bot to Azure and associate it with an identity provider**. The provider issues a token based on user sign-in credentials. The bot can use the token to access resources, such as a mail service, which require authentication. - **How to integrate the bot within Microsoft Teams**. Once the bot is integrated, you can sign in and exchange messages with it in a chat. ## Prerequisites @@ -296,9 +296,17 @@ With the preliminary settings done, let's focus on the creation of the bot to us Depending on the characters in your bot secret, you might need to XML escape the password. For example, any ampersands (&) must be encoded as `&`. - [!code-json[appsettings](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/csharp/appsettings.json?range=1-5)] + ```JSON + "Teams": { + "ClientId": "", + "ClientSecret": "", + "TenantId": "", + "ConnectionName": "" -1. In the Solution Explorer, go to the `TeamsAppManifest` folder, open `manifest.json` and set `id` and `botId` to the **bot App ID** you saved at the time of the bot registration. For more information, see [app manifest](/microsoft-365/extensibility/schema/root-bots#botid). + } + ``` + +1. In the Solution Explorer, go to the `appPackage` folder, open `manifest.json` and set `id` and `botId` to the **bot App ID** you saved at the time of the bot registration. For more information, see [app manifest](/microsoft-365/extensibility/schema/root-bots#botid). > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+the+bot+sample+code+using+C%23%2F.NET&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Dnode-js%252Cdotnet-sample%23test-the-connection&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -307,7 +315,7 @@ With the preliminary settings done, let's focus on the creation of the bot to us 1. Clone [node-auth-sample][teams-auth-bot-js]. 1. In a console, go to the project:

-`cd samples/bot-teams-authentication/nodejs` +`cd samples/TeamsSDK/bot-auth-quickstart/nodejs/bot-auth-quickstart` 1. Install modules

`npm install` 1. Update the **.env** configuration as follows: @@ -317,9 +325,14 @@ With the preliminary settings done, let's focus on the creation of the bot to us - Set the `CONNECTION_NAME` to the name of the identity provider connection. Depending on the characters in your bot secret, you might need to XML escape the password. For example, any ampersands (&) must be encoded as `&`. - [!code-javascript[settings](~/../Microsoft-Teams-Samples/samples/bot-conversation-sso-quickstart/js/.env)] + ```Javascript + TENANT_ID= + CLIENT_ID= + CLIENT_SECRET= + CONNECTION_NAME= + ``` -1. In the `teamsAppManifest` folder, open `manifest.json` and set `id` to your **Microsoft App ID** and `botId` to the **bot App ID** you saved at the time of the bot registration. +1. In the `appPackage` folder, open `manifest.json` and set `id` to your **Microsoft App ID** and `botId` to the **bot App ID** you saved at the time of the bot registration. > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+the+bot+sample+code+using+JavaScript&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Dnode-js%252Cdotnet-sample%23prepare-the-bot-sample-code&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -334,7 +347,12 @@ With the preliminary settings done, let's focus on the creation of the bot to us Depending on the characters in your bot secret, you might need to XML escape the password. For example, any ampersands (&) must be encoded as `&`. - [!code-python[config](~/../Microsoft-Teams-Samples/samples/bot-teams-authentication/python/config.py?range=14-16)] + ```Python + TENANT_ID= + CLIENT_ID= + CLIENT_SECRET= + CONNECTION_NAME= + ``` > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+the+bot+sample+code+using+Python&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Dpython%252Cdotnet-sample%23prepare-the-bot-sample-code&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -373,46 +391,6 @@ Alternatively, while in Visual Studio, you can follow these steps: > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Deploy+the+bot+to+Azure&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cpython-sample%23deploy-the-bot-to-azure&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) -## Test the bot locally - -After you configure the authentication mechanism, you can perform the actual bot testing. - -1. Run the bot sample locally on your machine, via Visual Studio for example. -1. Start the Emulator. -1. Select the **Open bot** button. -1. In the **Bot URL**, enter the bot's local URL. Usually, `http://localhost:3978/api/messages`. -1. In the **Microsoft App ID**, enter the bot's app ID from `appsettings.json`. -1. In the **Microsoft App password**, enter the bot's app password from the `appsettings.json`. -1. Select **Connect**. -1. After the bot is up and running, enter any text to display the sign-in card. -1. Select the **Sign in** button. -1. A pop-up dialog appears to **Confirm Open URL** to authenticate the bot's user (you). -1. Select **Confirm**. -1. If asked, select the applicable user's account. -1. Depending which configuration you used for the Emulator, you get one of the following options: - 1. **Using sign-in verification code** - ✓ A window opens displaying the validation code. - ✓ Copy and enter the validation code into the chat box to complete the sign-in. - 1. **Using authentication tokens**. - ✓ You're signed in based on your credentials. - - The following image is an example of the bot UI after you sign in: - - :::image type="content" source="../../../assets/images/authentication/auth-bot-login-emulator.PNG" alt-text="Screenshot shows an example of the bot UI after you sign in."::: - -1. If you select **Yes** when the bot asks *Would you like to view your token?*, you get the following response: - - :::image type="content" source="../../../assets/images/authentication/auth-bot-login-emulator-token.png" alt-text="Screenshot shows how to select the consent."::: - -1. Enter **logout** in the input chat box to sign out. -It releases the user token, and the bot won't be able to act on your behalf until you sign in again. - -> [!NOTE] -> Bot authentication requires use of the **Azure Bot Service**. The service accesses the bot registration information for your bot. - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Test+the+bot+locally&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication%3Ftabs%3Ddotnet%252Cdotnet-sample%23test-the-bot-locally&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fauthentication%2Fadd-authentication.md&documentVersionIndependentId=70952f91-56e9-ff08-59f6-e237d4aaeca9&platformId=cc53b20b-69e0-cb70-1ca7-9b939c969c92&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - ## Test the deployed bot