Add Microsoft Teams integration #6410

brant-livefront · 2025-10-03T19:59:42Z

📔 Objective

This PR adds an integration with Microsoft Teams.

This is a multi-step process that we will need to take into account when building the UI for this.

The organization owner kicks off an OAuth flow via the redirect
Microsoft authenticates the user and our request
Microsoft sends the user back to our create url, passing along a code and our state
We verify the state and use the code provided via OAuth to fetch (via Microsoft's Graph API) the TenantId and list of Teams for the owner who kicked off the OAtuh flow. We store these into an Initiated record in OrganizationIntegration
The owner installs our official app into their Teams instance and picks the channel in which to receive messages from the bot
Microsoft sends us an incoming bot event about the app installation
We parse the information from that incoming installation event, pulling out the tenant id, team id, conversation id, and serviceUrl
We lookup in our OrganizationIntegration table to see if there was a previously stored Initiated record with a matching tenant id and team id. If it is present, we update that record to include the serviceUrl and conversation id of the channel, thus moving the Teams integration to Completed. If there is not a matching record, we disregard the request
At this point the Teams integration is ready to send event information. The only renaming piece is to setup OrganizationIntegrationConfiguration records for the desired event types and template strings. These records will all contain null for the Configuration at this level because all of the necessary configuration is provided in the OrganizationIntegration configuration object.

Setup tasks

I'm currently using a minimalist app containing a minimal bot just as a POC. We will need an official app to be made in order to launch this.
- I'll write up more notes on the specific steps but overall we need to register an app, register a bot, put together a manifest/package, and submit it to Microsoft's store
- It is possible to side load it directly in a Team, which is what I'm doing to test currently
This PR adds a new integration, which will need new Subscriptions to be created in ASB
- If it launches before we turn the feature flag on, then we can create these subscriptions ahead of time
- If it launches after, we'll need to follow the process outlined in the docs (i.e. create the subscription with a false filter before deploying the code, then remove the filter after the code is live).
- The subscriptions / defaults are:
  - globalSettings.EventLogging.AzureServiceBus.TeamsEventSubscriptionName with a default name of events-teams-subscription
  - globalSettings.EventLogging.AzureServiceBus.TeamsIntegrationSubscriptionName with a default name of integration-teams-subscription

Notes

This PR builds on Refactor Slack Callback Mechanism #6388 and specifically the IntegrationOAuthState to do the OAuth validation piece. This helps validate the information coming back on the create method was actually generated by a legitimate actor and for the correct organization. As the API is public and not behind auth, we need to make sure that the requests received are valid
Additionally, the bot callback that we receive on app install is not behind our auth. However, Microsoft does send their own JWT which is validated by the TeamsBotCredentialProvider. It will validate that the requests are issued by Microsoft and contain our client id as the audience. Additionally, this API can only add information to an existing, matching Initiated record - you must have a matching tenant id and teams id. and t can't modify a Completed record
Microsoft does not allow bots to post to private channels. This is a known limitation for which I couldn't find a workaround.

⏰ Reminders before review

Contributor guidelines followed
All formatters and local linters executed and passed
Written new unit and / or integration tests where applicable
Protected functional changes with optionality (feature flags)
Used internationalization (i18n) for all UI strings
CI builds passed
Communicated to DevOps any deployment requirements
Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

👍 (:+1:) or similar for great changes
📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
❓ (:question:) for questions
🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
🎨 (:art:) for suggestions / improvements
❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
⛏ (:pick:) for minor or nitpick changes

dev/servicebusemulator_config.json

github-actions · 2025-10-03T20:11:59Z

Checkmarx One – Scan Summary & Details – 01447fe9-2e90-4c38-b042-50f0a567b50a

New Issues (2)

Checkmarx found the following issues in this Pull Request

Severity	Issue	Source File / Package	Checkmarx Insight
	CSRF	/src/Api/Vault/Controllers/CiphersController.cs: 1511	details Method at line 1511 of /src/Api/Vault/Controllers/CiphersController.cs gets a parameter from a user request from id. This parameter value flows ... `ID: pN371p7oxzg66CFSL1H%2F7897Dng%3D` Attack Vector
	CSRF	/src/Api/Vault/Controllers/CiphersController.cs: 1392	details Method at line 1392 of /src/Api/Vault/Controllers/CiphersController.cs gets a parameter from a user request from id. This parameter value flows ... `ID: xow1RlTy2gYME4GMTq55sfh%2BBY0%3D` Attack Vector

Fixed Issues (1)

Great job! The following issues were fixed in this Pull Request

Severity	Issue	Source File / Package
	~~CSRF~~	/src/Api/Vault/Controllers/CiphersController.cs: 299

brant-livefront · 2025-10-03T20:12:03Z

...e/Repositories/Queries/OrganizationIntegrationReadByTeamsConfigurationTenantIdTeamIdQuery.cs

+            where oi.Type == IntegrationType.Teams &&
+                  oi.Configuration != null &&
+                  oi.Configuration.Contains($"\"TenantId\":\"{_tenantId}\"") &&
+                  oi.Configuration.Contains($"\"id\":\"{_teamId}\"")


@withinfocus I couldn't find a good way to do a JSON query in EF and keep it generic, so I opted to use this Contains approach instead. I think it's functionally equivalent.

This works, but you could also parse it as JSON and make the checks a bit more cleanly. It doesn't have to all be in the where clause.

codecov · 2025-10-03T20:20:25Z

Codecov Report

❌ Patch coverage is 68.30601% with 116 lines in your changes missing coverage. Please review.
✅ Project coverage is 54.72%. Comparing base (c9970a0) to head (81fd273).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
.../Implementations/EventIntegrations/TeamsService.cs	72.64%	30 Missing and 2 partials ⚠️
...tionReadByTeamsConfigurationTenantIdTeamIdQuery.cs	0.00%	21 Missing ⚠️
...SharedWeb/Utilities/ServiceCollectionExtensions.cs	28.57%	19 Missing and 1 partial ⚠️
...e/Services/NoopImplementations/NoopTeamsService.cs	0.00%	12 Missing ⚠️
.../Repositories/OrganizationIntegrationRepository.cs	0.00%	9 Missing ⚠️
...ta/EventIntegrations/TeamsListenerConfiguration.cs	0.00%	7 Missing ⚠️
.../Repositories/OrganizationIntegrationRepository.cs	0.00%	7 Missing ⚠️
...nConsole/Controllers/TeamsIntegrationController.cs	92.85%	4 Missing and 2 partials ⚠️
...anizations/OrganizationIntegrationResponseModel.cs	90.00%	0 Missing and 1 partial ⚠️
...tions/EventIntegrations/TeamsIntegrationHandler.cs	95.83%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6410      +/-   ##
==========================================
+ Coverage   50.54%   54.72%   +4.17%     
==========================================
  Files        1854     1864      +10     
  Lines       82177    82541     +364     
  Branches     7271     7299      +28     
==========================================
+ Hits        41535    45167    +3632     
+ Misses      39050    35699    -3351     
- Partials     1592     1675      +83

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

eliykat · 2025-10-03T22:01:42Z

I've requested a review from the team as I'm trying to wrap up work before going on leave.

…den/server into brant/microsoft-teams-integration

withinfocus

Few things. This is a complex one.

src/Api/AdminConsole/Controllers/TeamsIntegrationController.cs

src/Core/AdminConsole/Models/Teams/TeamsApiResponse.cs

src/Core/AdminConsole/Models/Teams/TeamsBotCredentialProvider.cs

src/Core/AdminConsole/Repositories/IOrganizationIntegrationRepository.cs

...or/DbScripts/2025-10-3_00_AddOrganizationIntegration_ReadByTenantIdTeamIdStoredProcedure.sql

src/Core/AdminConsole/Services/Implementations/EventIntegrations/TeamsService.cs

withinfocus · 2025-10-06T18:56:47Z

src/Core/Core.csproj

+    <PackageReference Include="Microsoft.Bot.Builder" Version="4.23.0" />
+    <PackageReference Include="Microsoft.Bot.Connector" Version="4.23.0" />


ℹ️ These save a lot of time and code, but I don't love adding dependencies so strongly for an integration.

I agree 100% in general. I did all of the graph api calls natively since they were just normal REST. But the incoming bot stuff seemed to push heavily in the dependency direction.

withinfocus · 2025-10-06T18:58:02Z

...e/Repositories/Queries/OrganizationIntegrationReadByTeamsConfigurationTenantIdTeamIdQuery.cs

+            where oi.Type == IntegrationType.Teams &&
+                  oi.Configuration != null &&
+                  oi.Configuration.Contains($"\"TenantId\":\"{_tenantId}\"") &&
+                  oi.Configuration.Contains($"\"id\":\"{_teamId}\"")


This works, but you could also parse it as JSON and make the checks a bit more cleanly. It doesn't have to all be in the where clause.

src/Sql/dbo/Stored Procedures/OrganizationIntegration_ReadByTenantIdTeamId.sql

withinfocus · 2025-10-06T19:02:12Z

Oh, and do you also want to update the docs?

brant-livefront · 2025-10-07T17:25:53Z

@withinfocus Looking at what needs to change in the docs now, but wanted to push up the code changes I have. I think I've addressed all your comments. 👍

withinfocus

Documentation can be added here in another commit and I'll re-review but this all works. I still have one open comment about the EF query getting cleaned up, but what you have works.

withinfocus

Left two comments on the commit (that often gets me when I click on email notifications) with one being a ⛏️ you can quickly fix, but this is good to go at this point.

jrmccannon · 2025-10-08T20:51:34Z

src/Api/AdminConsole/Controllers/TeamsIntegrationController.cs

+            throw new BadRequestException("No teams were found.");
+        }
+
+        var teamsIntegration = new TeamsIntegration(TenantId: teams.First().TenantId, Teams: teams);


Suggested change

var teamsIntegration = new TeamsIntegration(TenantId: teams.First().TenantId, Teams: teams);

var teamsIntegration = new TeamsIntegration(TenantId: teams[0].TenantId, Teams: teams);

To get rid of warning.

jrmccannon · 2025-10-08T20:53:20Z

src/Api/AdminConsole/Controllers/TeamsIntegrationController.cs

+            throw new NotFoundException();
+        }
+
+        string? callbackUrl = Url.RouteUrl(


Suggested change

string? callbackUrl = Url.RouteUrl(

var callbackUrl = Url.RouteUrl(

To remove warning.

jrmccannon · 2025-10-08T20:54:13Z

src/Api/AdminConsole/Controllers/TeamsIntegrationController.cs

+            throw new NotFoundException();
+        }
+
+        string? callbackUrl = Url.RouteUrl(


Suggested change

string? callbackUrl = Url.RouteUrl(

var callbackUrl = Url.RouteUrl(

To remove warning.

jrmccannon · 2025-10-08T20:55:42Z

src/Core/AdminConsole/Models/Data/EventIntegrations/TeamsIntegration.cs

+    string? ChannelId = null,
+    Uri? ServiceUrl = null)
+{
+    public bool isVerified => (!string.IsNullOrEmpty(ChannelId) && ServiceUrl is not null);


Suggested change

public bool isVerified => (!string.IsNullOrEmpty(ChannelId) && ServiceUrl is not null);

public bool IsVerified => !string.IsNullOrEmpty(ChannelId) && ServiceUrl is not null;

To remove warning

src/Core/AdminConsole/Models/Teams/TeamsApiResponse.cs

src/Core/AdminConsole/Services/ITeamsService.cs

jrmccannon · 2025-10-09T13:52:00Z

src/Core/AdminConsole/Services/Implementations/EventIntegrations/TeamsService.cs

+    GlobalSettings globalSettings,
+    ILogger<TeamsService> logger) : ActivityHandler, ITeamsService
+{
+    private readonly IOrganizationIntegrationRepository _integrationRepository = integrationRepository;


Couldn't we just use the integration repository from the primary constructor?

💯 fixed in next commit

test/Core.Test/AdminConsole/Services/IntegrationTypeTests.cs

jrmccannon

This looks good to me. Thanks for all the updates.

withinfocus

Didn't realize this was waiting on me after AC review.

* Add Microsoft Teams integration * Fix method naming error * Expand and clean up unit test coverage * Update with PR feedback * Add documentation, add In Progress logic/tests for Teams * Fixed lowercase Slack * Added docs; Updated PR suggestions; * Fix broken tests

Add Microsoft Teams integration

512278b

brant-livefront requested a review from withinfocus October 3, 2025 19:59

brant-livefront requested review from a team as code owners October 3, 2025 19:59

brant-livefront requested a review from eliykat October 3, 2025 19:59

Fix method naming error

cdca944

brant-livefront commented Oct 3, 2025

View reviewed changes

dev/servicebusemulator_config.json Show resolved Hide resolved

brant-livefront commented Oct 3, 2025

View reviewed changes

eliykat requested review from a team and removed request for eliykat October 3, 2025 21:58

brant-livefront and others added 4 commits October 6, 2025 09:35

Merge branch 'main' into brant/microsoft-teams-integration

886fe32

Expand and clean up unit test coverage

85a2b7c

Merge branch 'brant/microsoft-teams-integration' of github.com:bitwar…

2589ec4

…den/server into brant/microsoft-teams-integration

Merge branch 'main' into brant/microsoft-teams-integration

f42fd7b

withinfocus requested changes Oct 6, 2025

View reviewed changes

brant-livefront added 3 commits October 7, 2025 09:15

Merge branch 'main' into brant/microsoft-teams-integration

59445c0

Update with PR feedback

752d1d5

Merge branch 'main' into brant/microsoft-teams-integration

5bfcde8

withinfocus previously approved these changes Oct 7, 2025

View reviewed changes

brant-livefront added 2 commits October 8, 2025 10:48

Add documentation, add In Progress logic/tests for Teams

b5376d5

Merge branch 'main' into brant/microsoft-teams-integration

b4024a4

brant-livefront dismissed withinfocus’s stale review via b4024a4 October 8, 2025 14:48

withinfocus previously approved these changes Oct 8, 2025

View reviewed changes

JimmyVo16 requested review from JimmyVo16 and removed request for JimmyVo16 October 8, 2025 15:15

brant-livefront added 2 commits October 8, 2025 11:26

Fixed lowercase Slack

2ce25ed

Merge branch 'main' into brant/microsoft-teams-integration

ca9ec78

brant-livefront dismissed withinfocus’s stale review via ca9ec78 October 8, 2025 15:26

jrmccannon requested changes Oct 9, 2025

View reviewed changes

brant-livefront added 4 commits October 9, 2025 10:43

Merge branch 'main' into brant/microsoft-teams-integration

00bae24

Added docs; Updated PR suggestions;

ca3f6d0

Merge branch 'main' into brant/microsoft-teams-integration

1580da7

Fix broken tests

a812d90

jrmccannon approved these changes Oct 9, 2025

View reviewed changes

Merge branch 'main' into brant/microsoft-teams-integration

81fd273

withinfocus approved these changes Oct 10, 2025

View reviewed changes

brant-livefront merged commit a565fd9 into main Oct 10, 2025
43 checks passed

brant-livefront deleted the brant/microsoft-teams-integration branch October 10, 2025 14:39

		<PackageReference Include="Microsoft.Bot.Builder" Version="4.23.0" />
		<PackageReference Include="Microsoft.Bot.Connector" Version="4.23.0" />

	var teamsIntegration = new TeamsIntegration(TenantId: teams.First().TenantId, Teams: teams);
	var teamsIntegration = new TeamsIntegration(TenantId: teams[0].TenantId, Teams: teams);

	string? callbackUrl = Url.RouteUrl(
	var callbackUrl = Url.RouteUrl(

	public bool isVerified => (!string.IsNullOrEmpty(ChannelId) && ServiceUrl is not null);
	public bool IsVerified => !string.IsNullOrEmpty(ChannelId) && ServiceUrl is not null;

Add Microsoft Teams integration #6410

Add Microsoft Teams integration #6410

Uh oh!

Conversation

brant-livefront commented Oct 3, 2025

📔 Objective

Setup tasks

Notes

⏰ Reminders before review

🦮 Reviewer guidelines

Uh oh!

Uh oh!

github-actions bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

eliykat commented Oct 3, 2025

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

withinfocus commented Oct 6, 2025

Uh oh!

brant-livefront commented Oct 7, 2025

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrmccannon left a comment

Choose a reason for hiding this comment

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

github-actions bot commented Oct 3, 2025 •

edited

Loading

codecov bot commented Oct 3, 2025 •

edited

Loading