Connect Microsoft Teams to Mattermost#

plans-img Available on Enterprise plans

deployment-img Cloud and self-hosted deployments

Break through siloes in a mixed Mattermost and Microsoft Teams environment by forwarding real-time chat notifications from Teams to Mattermost.

Setup#

Setup starts in Mattermost, moves to Microsoft Teams, and ends in Mattermost.

Install the Microsoft Teams integration in Mattermost#

Important

These installation instructions assume you already have a Mattermost instance running PostgreSQL. Note that this Mattermost integration doesn’t support MySQL databases.

  1. Log in to your Mattermost workspace as a system administrator.

  2. Download the latest version of the plugin binary release, compatible with Mattermost v9.8.0 and later. If you are using an earlier version of Mattermost, follow our documentation to upgrade to Mattermost v9.8.0 or later.

  3. Go to System Console > Plugins > Plugin Management > Upload Plugin, and upload the plugin binary you downloaded in the previous step.

  4. Go to System Console > Plugins > Plugin Management. In the Installed Plugins section, scroll to MS Teams, and select Enable Plugin.

Set up an OAuth application in Azure#

  1. Sign into portal.azure.com using an admin Azure account.

  2. Navigate to App Registrations.

  3. Select New registration at the top of the page.

In Azure, create a new app registration.

  1. Fill out the form with the following values:

  • Name: Mattermost MS Teams

  • Supported account types: Default value (Single tenant)

  • Platform: Web

  • Redirect URI: https://(MM_SITE_URL)/plugins/com.mattermost.msteams/oauth-redirect

Replace (MM_SITE_URL) with your Mattermost server’s Site URL. Select Register to submit the form.

In Azure, register the new Mattermost app.

  1. Navigate to Certificates & secrets in the left pane.

  2. Select New client secret. Enter the description and select Add. After the creation of the client secret, copy the new secret value, not the secret ID. We’ll use this value later in the Mattermost System Console.

In Azure, enter client secret details.

  1. Navigate to API permissions in the left pane.

  2. Select Add a permission, then Microsoft Graph in the right pane.

In Azure, manage API permissions for the Mattermost app.

  1. Select Delegated permissions, and scroll down to select the following permissions:

  • Channel.ReadBasic.All

  • ChannelMessage.Read.All

  • ChannelMessage.ReadWrite

  • ChannelMessage.Send

  • Chat.Create

  • Chat.ReadWrite

  • ChatMessage.Read

  • Directory.Read.All

  • Files.Read.All

  • Files.ReadWrite.All

  • offline_access

  • Team.ReadBasic.All

  • User.Read

  1. Select Add permissions to submit the form.

  2. Next, add application permissions via Add a permission > Microsoft Graph > Application permissions.

  3. Select the following permissions:

  • Channel.ReadBasic.All

  • ChannelMessage.Read.All

  • Chat.Read.All

  • Files.Read.All

  • Group.Read.All

  • Team.ReadBasic.All

  • User.Read.All

  • Application.ReadWrite.OwnedBy (or Application.Read.All)

  1. Select Add permissions to submit the form.

  2. Select Grant admin consent for… to grant the permissions for the application.

Ensure you have the metered APIs enabled (and the pay subscription associated to it)#

Follow the steps here: https://learn.microsoft.com/en-us/graph/metered-api-setup

Important

If you don’t configure the metered APIs, you must use the Evaluation model (configurable in Mattermost) that is limited to a low rate of changes per month. We strongly recommend that you avoid using the Evaluation model configuration in live production environments because you can stop receiving messages due the rate limit. See this Microsoft documentation for more details.

You’re all set for configuration inside Azure.

Mattermost configuration#

With the Tenant ID, Client ID, and Client secret noted above, the Mattermost plugin is ready for configuration. See the Microsoft Teams plugin configuration settings documentation for support in completing the base configuration.

Create a user account to act as a bot#

A connected bot is required to sync linked channels.

  1. Create a regular user account. We will connect this account later from the Mattermost side.

  2. This account is needed for proxying messages from Mattermost to Microsoft Teams.

    In Microsoft Teams, create a user account to act as a bot.

  3. As a system administrator, run the /msteams connect-bot slash command to connect the bot account, authenticating with the Teams account created above.

Monitor performance#

You can set up performance monitoring and performance alerting for this plugin using Prometheus and Grafana.

  • Monitoring enables you to proactively review the overall health of the plugin, including database calls, HTTP requests, and API latency.

  • Alerting enables you to detect and take action as issues come up, such as the integration being offline.

Grafana dashboards are available on GitHub for Mattermost Cloud deployments as a useful starting point. These dashboards are designed for use in Mattermost Cloud, and filter to a given namespace.

Example of a Grafana monitoring dashboard for a Mattermost instance connected to Microsoft Teams.

Note

Modifications will be necessary for self-hosted Mattermost deployments. See the Get help section below for details on how to contact us for assistance.

System admin slash commands#

Once Microsoft Teams interoperability is enabled, the following slash commands are available for Mattermost system admins by typing the commands into the Mattermost message text box, and selecting Send:

  • /msteams connect-bot: Connect the bot account in Mattermost to an account in Microsoft Teams.

  • /msteams disconnect-bot: Disconnect the bot account in Mattermost from the Microsoft Teams account.

  • /msteams show-links: Show all the currently active links including the Mattermost team, Mattermost channel, Microsoft Teams team, and Microsoft Teams channel.

Usage#

See the collaborate within connected microsoft teams product documentation to get started using Microsoft Teams interoperability.

Frequently asked questions#

My email address in Mattermost doesn’t match my email address in Microsoft Teams: can I still connect?#

No. Currently, only accounts with the same email addresses are allowed to be connected. Specify the email address that matches your Mattermost account.

If connecting a Mattermost account to a Microsoft Teams account with a different email address is something your workspace requires, there is an open GitHub issue for you to share your feedback.

How is encryption handled at rest and in motion?#

The configured client secret, stored in the Mattermost configuration, is used for app-only access to the the Microsoft Graph API. As users connect to Microsoft Teams using the integration, the resulting access tokens are encrypted and stored in the Mattermost database to be used for access on behalf of the connected user. All communication between the integration and the Microsoft Graph API is conducted via TLS.

When notifications are enabled, chats and file attachments received by connected users will be stored as posts in the direct message channel between that user and the bot account created by the integration. When linked channels are enabled, messages and file attachments sent in Microsoft Teams will be stored as posts in the linked Mattermost channel. Similarly, messages and file attachments sent in a linked Mattermost channel will be sent to Microsoft Teams using the Microsoft Graph API.

Are there any database or network security considerations?#

There is nothing specific to the integration that is beyond what would apply to a Mattermost instance.

Are there any compliance considerations (ie. GDPR, PCI)?#

There is nothing specific to the integration that is beyond what would apply to a Mattermost instance.

How is this integration architectured?#

The integration subscribes to change notifications from the Microsoft Graph API. These change notifications inform Mattermost about new or updated chats and channel messages within Microsoft Teams. Upon receipt of the change notification, the integration use a combination of its app-only access (via the client secret) and delegated acess (via connected users) to fetch the contents of these chats and channel messages and represent them appropriately within Mattermost.

Get help#

If you face issues while installing this integration, gather relevant information, including reproduction steps to accelerate troubleshooting. You’re welcome to open a new issue in the Mattermost for Microsoft Teams GitHub repository.