240db4e2a7
Some checks failed
Server CI / Postgres (shard 0) (push) Has been skipped
Server CI / Postgres (shard 3) (push) Has been skipped
BuildEnv Docker Image / build-image (push) Failing after 4s
BuildEnv Docker Image / build-image-fips (push) Failing after 4s
Migration Review & Release Notes / Generate migration review & release notes (push) Failing after 3s
Server CI / Build Environment (push) Failing after 3s
Server CI / Postgres (shard 1) (push) Has been skipped
Tools CI / check-style (mattermost-govet) (push) Failing after 4s
Server CI / Postgres (shard 2) (push) Has been skipped
Tools CI / check-style (mmgotool) (push) Failing after 3s
Server CI / Elasticsearch v8 Compatibility (push) Has been skipped
Server CI / OpenSearch v2 Compatibility (push) Has been skipped
Server CI / Postgres FIPS (shard 0) (push) Has been skipped
Tools CI / Test (mattermost-govet) (push) Failing after 3s
Server CI / Postgres FIPS (shard 1) (push) Has been skipped
Server CI / Postgres FIPS (shard 2) (push) Has been skipped
Tools CI / Test (mmgotool) (push) Failing after 3s
Server CI / Postgres FIPS (shard 3) (push) Has been skipped
Server CI / Run mmctl tests (push) Has been skipped
Server CI / Run mmctl tests (FIPS) (push) Has been skipped
Server CI / Merge Postgres Test Results (push) Has been skipped
Server CI / Merge Postgres FIPS Test Results (push) Has been skipped
Server CI / Check backport migrations (push) Has been skipped
Server CI / Check generated files (push) Has been skipped
Server CI / check-style (push) Has been skipped
Server CI / Vet API (push) Has been skipped
Server CI / Build mattermost server app (push) Has been skipped
Server CI / Server CI Complete (push) Failing after 2s
Server CI / Server CI Artifacts (push) Has been skipped
Server CI / Sentry Upload (push) Has been skipped
Server CI / Server CI Report (push) Failing after 5m1s
Server CI Nightly Race / Race Detector (push) Has been skipped
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (javascript) (push) Has been cancelled
Webapp CI Cache Warm / Warm Webapp node_modules Cache (push) Has been cancelled
E2E CI Cache Warm / Warm E2E npm Registry Cache (push) Has been cancelled
API / build (push) Has been cancelled
Web App CI / check-types (push) Has been cancelled
Web App CI / check-lint (push) Has been cancelled
Web App CI / check-i18n (push) Has been cancelled
Web App CI / check-external-links (push) Has been cancelled
Web App CI / test (platform) (push) Has been cancelled
Web App CI / test (mattermost-redux) (push) Has been cancelled
Web App CI / test (channels shard 1/4) (push) Has been cancelled
Web App CI / test (channels shard 2/4) (push) Has been cancelled
Web App CI / test (channels shard 3/4) (push) Has been cancelled
Web App CI / test (channels shard 4/4) (push) Has been cancelled
Web App CI / upload-coverage (push) Has been cancelled
Web App CI / build (push) Has been cancelled
YAML Lint / yamllint (push) Has been cancelled
Push mirrored docker images / cd/Push mirrored docker images (push) Has been cancelled
docs-cd / Build and deploy docs (push) Has been cancelled
Docs CI / build (push) Has been cancelled
E2E Cache Warm: Cypress deps / Warm Cypress deps cache (push) Has been cancelled
Scorecards supply-chain security / Scorecard analysis (push) Has been cancelled
Server CI Weekly / Postgres FIPS (push) Has been skipped
Server CI Weekly / Run mmctl tests (FIPS) (push) Has been skipped
Server CI Weekly / Postgres with binary parameters (push) Has been skipped
Server CI Weekly / Build Environment (push) Failing after 1s
Server CI Cache Warm / Warm Go Module and Build Cache (push) Failing after 2s
Server CI Nightly Race / Build Environment (push) Failing after 1s
170 lines
12 KiB
Plaintext
170 lines
12 KiB
Plaintext
---
|
|
title: "Connect Microsoft 365, Teams, and Outlook with Mattermost"
|
|
sidebar_label: "Microsoft 365 and Outlook"
|
|
---
|
|
<PlanAvailability slug="entry-ent" />
|
|
|
|
Mattermost Mission Collaboration for Microsoft extends Microsoft for mission-critical coordination, command and control, incident response, and DevSecOps workflows in demanding environments, including air-gapped and classified networks by embedding Mattermost inside Teams. Use data-sovereign tools like secure chat, Playbooks, and Calls directly within M365, Teams, and Outlook.
|
|
|
|
This app is designed to work with Microsoft 365, Teams, and Outlook and is currently in [Beta](/administration-guide/manage/feature-labels#beta). From Mattermost v10.7.1, this integration supports Entra ID-based Single Sign-On (SSO) for automatic authentication. Users must exist in both Mattermost and Microsoft with matching email addresses; the integration handles authentication but does not automatically provision new users. See the [single sign-on](/administration-guide/onboard/corporate-directory-integration) product documentation for details on setting up SSO.
|
|
|
|
|
|
|
|
## Deploy
|
|
|
|
Before starting the setup, review this section to familiarize yourself with the 3 components needed to integrate Mattermost with M365, including [Azure App registration](#register-an-ms-teams-app-in-azure), [Microsoft Teams App installation](#install-mattermost-in-microsoft-teams), and [Mattermost plugin configuration](#configure-the-mattermost-plugin). Each component plays a crucial role in ensuring seamless communication and collaboration between Mattermost and Microsoft 365 services. Then complete the following integration setup steps in the order listed below.
|
|
|
|
### Register an MS Teams app in Azure
|
|
|
|
An application must be registered in Microsoft Azure to enable secure authentication and authorization between Mattermost and M365 services. This app registration acts as the bridge for permissions and connectivity. The **Azure App** is responsible for authentication and managing permissions.
|
|
|
|
1. Sign in to the [Azure portal](https://portal.azure.com/) using an admin Azure account.
|
|
2. Go to your **Azure Portal \> Microsoft Entra ID**.
|
|
3. Create a new app registration by selecting the **Add application registration** "Quick Action":
|
|
|
|
> 
|
|
>
|
|
> - Give it a name.
|
|
> - Choose the "Accounts in this organizational directory only (single tenant)" option.
|
|
> - Leave the Redirect URI empty.
|
|
>
|
|
> 
|
|
|
|
4. Go to your newly created application and copy the **Application (client) ID** and **Directory (tenant) ID** values. You'll need those later to configure the plugin.
|
|
|
|
> 
|
|
|
|
5. Go to **Certificates and secrets** to generate a new client secret. Make a copy of the secret value, as it will only be shown once. You'll need this value to configure the plugin.
|
|
|
|
> 
|
|
|
|
6. Go to **API Permissions** to complete the following steps:
|
|
|
|
> - Ensure the `User.Read` **delegated** permission is added. See the [Microsoft SSO documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#enable-sso-in-microsoft-entra-id) for details.
|
|
> - Add the **Microsoft Graph API** `TeamsActivity.Send` **application** permission for notifications. See the [Microsoft notifications documentation](https://learn.microsoft.com/en-us/graph/teams-send-activityfeednotifications?tabs=desktop%2Chttp) for details.
|
|
> - Add the **Microsoft Graph API** `AppCatalog.Read.All` **application** permission for notifications. See the [Microsoft List teamsApp documentation](https://learn.microsoft.com/en-us/graph/api/appcatalogs-list-teamsapps?view=graph-rest-1.0&tabs=http) for details.
|
|
> - Grant admin consent for the default directory to prevent users from seeing the consent prompt.
|
|
|
|
7. Go to **Expose an API** to complete the following steps:
|
|
|
|
> - Add/edit a **Application ID URI** and set the value to `api://{{Mattermost Site URL Hostname}}/{{Application (client) ID}}`.
|
|
>
|
|
> - Add the `access_as_user` scope by selecting **Add a scope** and setting the following values:
|
|
>
|
|
> - **Scope name**: `access_as_user`.
|
|
> - **Who can consent?** Admins and users
|
|
> - Provide a display name and description, as well as a user consent display name and description. These will be shown to end users on the consent screen. For example:
|
|
> - **Display name**: Log in to Mattermost
|
|
> - **Description**: Used to allow O365 users to log in to the Mattermost application
|
|
> - **User consent display name**: Log in to Mattermost
|
|
> - **User consent description**: This permission is required to automatically log you in into Mattermost from Microsoft applications.
|
|
>
|
|
> See the [Microsoft API scope documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#to-configure-api-scope) for details.
|
|
>
|
|
> - Add authorised client applications for the scope. See the [Microsoft authorized client documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#to-configure-authorized-client-application) for details.
|
|
> - Select `_Add a client application_`. **You must add a client application for each target Microsoft application**:
|
|
> - **Authorised scopes**: The one we just created
|
|
> - **Client ID**:
|
|
> - **Teams web**: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
|
|
> - **Teams app**: 1fec8e78-bce4-4aaf-ab1b-5451cc387264
|
|
> - **Outlook desktop** : d3590ed6-52b3-4102-aeff-aad2292ab01c
|
|
> - **Outlook web** : bc59ab01-8403-45c6-8796-ac3ef710b3e3
|
|
> - If you want to make your application available in more Microsoft applications, keep adding client applications from [the following table](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#to-configure-authorized-client-application:~:text=Select%20one%20of%20the%20following%20client%20IDs%3A).
|
|
|
|
|
|
|
|
### Configure the Mattermost plugin
|
|
|
|
A Microsoft Teams app is installed into Microsoft Teams. This app facilitates collaboration between Mattermost and Teams, providing a tab containing Mattermost within the Teams client. The **Teams App** is installed within Microsoft Teams to enable collaboration via a tab.
|
|
|
|
1. Download the [latest release of the plugin](https://github.com/mattermost/mattermost-plugin-msteams-devsecops/releases).
|
|
|
|
2. Go to **System Console \> Plugins \> Plugin Management \> Upload Plugin**, and upload the plugin binary you downloaded in the previous step.
|
|
|
|
3. Go to **System Console \> Plugins \> Plugin Management**. In the **Installed Plugins** section, scroll to **Mattermost Mission Collaboration for Microsoft**.
|
|
|
|
4. Enter an **Application Version**. You can start with `1.0.0`.
|
|
|
|
5. Generate an Application ID in [version 4 UUID format](https://www.uuidgenerator.net/) and enter it in the **Application ID** field.
|
|
|
|
6. Enter the values you noted earlier in the appropriate fields, including **Directory (tenant) ID**, **Application (client) ID**, and **Client Secret**.
|
|
|
|
> 
|
|
|
|
7. Enter an **Application Display Name** to define how your application is named in the MS Teams App Store. Make it company specific for easy discovery.
|
|
|
|
8. Save the changes and enable the plugin.
|
|
|
|
9. Select the **Download Manifest** button to generate the MS Teams application as a ZIP file, containing the app manifest. Save this file as it will be used in the next steps.
|
|
|
|
### Install Mattermost in Microsoft Teams
|
|
|
|
Within Mattermost, the Mattermost Mission Collaboration for Microsoft plugin needs to be installed and configured. This plugin acts as the integration hub on the Mattermost side, connecting to both the Azure App and the Teams App. The **Mattermost Plugin** is the configuration point within Mattermost that unifies the integration.
|
|
|
|
1. Go to the [Microsoft Teams admin center](https://admin.teams.microsoft.com/dashboard).
|
|
|
|
2. Go to **Teams apps \> Manage apps**.
|
|
|
|
> 
|
|
|
|
3. Go to **Actions \> Upload new app** located in the upper-right corner of the Manage apps page.
|
|
|
|
4. Select **Upload** and select the ZIP file saved previously.
|
|
|
|
5. Done! Your application is now available to users.
|
|
|
|
## Use
|
|
|
|
### Add the app
|
|
|
|
Once the application is deployed, your users can add the Mattermost app to their Microsoft Teams environment. Inform your users to:
|
|
|
|
1. Open Microsoft Teams and go to **Apps** in the left sidebar.
|
|
2. Search for the **Application Display Name** you configured in the plugin settings (step 7 of the [Configure the Mattermost plugin](#configure-the-mattermost-plugin) section).
|
|
3. The app will display a **Built for your org** tag, indicating it's a custom application approved for your organization.
|
|
4. Select the app and then select **Add** to install it in their Teams environment.
|
|
|
|
Once added, users can access Mattermost directly within Microsoft Teams through the app tab.
|
|
|
|
|
|
|
|
### Authentication
|
|
|
|
This plugin supports automatic authentication when logged into Microsoft Teams. Teams authentication automatically logs users into Mattermost if the email addresses in both platforms match exactly. Regular authentication methods (LDAP, SAML, email/password, OpenID) can additionally be used for Mattermost.
|
|
|
|
The integration automatically configures Content Security Policy (CSP) and Frame Ancestors settings to ensure secure embedding of Mattermost within Microsoft Teams, Outlook, and other Microsoft 365 applications. Deep linking is supported, allowing users to select links in Teams notifications and navigate directly to specific Mattermost posts or conversations.
|
|
|
|
In air-gapped environments or during business continuity disruptions, users who can't join Microsoft Teams, can continue to access Mattermost using their Mattermost credentials by opening Mattermost in a separate app (e.g., in a new browser window). Alternatively, a Mattermost admin can pre-distribute the Mattermost desktop app using Windows MSI or the mobile app via EMM.
|
|
|
|
|
|
|
|
### Activity Feed notifications
|
|
|
|
When you're mentioned in Mattermost while working in Microsoft Teams, you'll receive notifications directly in your Teams Activity Feed. This keeps you connected to important Mattermost conversations without switching applications.
|
|
|
|
**What triggers notifications:**
|
|
|
|
- Direct mentions using @username
|
|
- Channel-wide mentions using @channel, @all, or @here
|
|
- Direct messages sent to you
|
|
|
|
**How it works:**
|
|
|
|
When someone mentions you in Mattermost, a notification appears in your Microsoft Teams Activity Feed. Select the notification to open Mattermost and view the full context of the message. This feature uses the `TeamsActivity.Send` permission configured during the Azure app registration setup.
|
|
|
|
**Disable notifications:**
|
|
|
|
System admins can disable Activity Feed notifications for specific users or across your organization by configuring the `disable_user_activity_notifications` setting in the plugin configuration. This setting is useful if you want to reduce notification noise or if users prefer to check Mattermost manually.
|
|
|
|
<Note>
|
|
|
|
Activity Feed notifications require the `TeamsActivity.Send` application permission to be configured in Azure (step 6 of the [Register an MS Teams app in Azure](#register-an-ms-teams-app-in-azure) section).
|
|
|
|
</Note>
|
|
|
|
## Get Help
|
|
|
|
Customers with a Mattermost subscription can open a [Mattermost support case](https://support.mattermost.com/hc/en-us/requests/new).
|
|
|
|
For questions, feedback, and assistance, join our pubic [Integrations and Apps channel](https://community.mattermost.com/core/channels/integrations) on the [Mattermost Community Server](https://community.mattermost.com/) for assistance.
|