diff --git a/source/collaborate/collaborate-within-connected-microsoft-teams.rst b/source/collaborate/collaborate-within-connected-microsoft-teams.rst index 881f3aec15b..ac1c9ed4277 100644 --- a/source/collaborate/collaborate-within-connected-microsoft-teams.rst +++ b/source/collaborate/collaborate-within-connected-microsoft-teams.rst @@ -32,18 +32,6 @@ Once you've connected your Mattermost account to your Microsoft Teams account, M .. image:: ../images/microsoft-teams-chat-notifications.png :alt: An example of a chat message notification. -Link one or more channels (Beta) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to receiving notifications for chats and group chats, you can also link a channel in Mattermost to a channel in Microsoft Teams. Messages sent from one platform will be sent to the other using the connected bot account. - -.. note:: - - Your system administrator must :ref:`enable support for linked channels `. - - This feature remains in beta and may change or be deprecated in the future. - -.. image:: ../images/microsoft-teams-linked-channel.png - :alt: An example of a linked channel. - Mattermost Slash commands ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -53,6 +41,3 @@ You can run the following Mattermost slash commands by typing the commands into - ``/msteams disconnect``: Disconnect your Mattermost account from Microsoft Teams account. - ``/msteams status``: Show your current connection status. - ``/msteams notifications``: Manage and show your current notifications settings. -- ``/msteams link``: Link the currently active Mattermost channel with an Microsoft Teams channel. You must be a Mattermost channel admins to use this slash command, and you must have your Mattermost account connected with Microsoft Teams. This command takes two arguments: ``Microsoft Teams team ID`` and ``channel ID``, which you can get from command autocomplete. -- ``/msteams unlink``: Unlink the currently active Mattermost channel with the Microsoft Teams channel. You must be a Mattermost channel admin to run this slash command, but you don't need to have your Mattermost account connected to Microsoft Teams. -- ``/msteams show``: Show the link of the currently active Mattermost channel, including the team and channel name in Microsoft Teams to which the Mattermost channel is linked. diff --git a/source/configure/install-mattermost-for-microsoft-teams-plugin.rst b/source/configure/install-mattermost-for-microsoft-teams-plugin.rst deleted file mode 100644 index c1358707d3c..00000000000 --- a/source/configure/install-mattermost-for-microsoft-teams-plugin.rst +++ /dev/null @@ -1,141 +0,0 @@ -:orphan: :nosearch: - -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, :doc:`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. - - .. image:: ../images/new-azure-registration.png - :alt: In Azure, create a new app registration. - -4. 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. - - .. image:: ../images/register-azure-app.png - :alt: In Azure, register the new Mattermost app. - -5. Navigate to **Certificates & secrets** in the left pane. - -6. 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. - - .. image:: ../images/azure-certs-secrets.png - :alt: In Azure, enter client secret details. - -7. Navigate to **API permissions** in the left pane. - -8. Select **Add a permission**, then **Microsoft Graph** in the right pane. - - .. image:: ../images/azure-configured-permissions.png - :alt: In Azure, manage API permissions for the Mattermost app. - -9. 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`` - -10. Select **Add permissions** to submit the form. - -11. Next, add application permissions via **Add a permission > Microsoft Graph > Application permissions**. - -12. 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``) - -13. Select **Add permissions** to submit the form. - -14. 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 :ref:`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. - - .. image:: ../images/teams-user-as-bot.png - :alt: 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 :doc:`performance monitoring ` and :doc:`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``. - -.. image:: ../images/grafana-dashboard-msteams.png - :alt: Example of a Grafana monitoring dashboard for a Mattermost instance connected to Microsoft Teams. - -.. note:: - - Modifications will be necessary for self-hosted Mattermost deployments. Talk to a `Mattermost Expert `_ 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. diff --git a/source/configure/plugins-configuration-settings.rst b/source/configure/plugins-configuration-settings.rst index fe0d9cd5122..e225918fe32 100644 --- a/source/configure/plugins-configuration-settings.rst +++ b/source/configure/plugins-configuration-settings.rst @@ -1187,32 +1187,11 @@ Sync notifications | Notify connected users in Mattermost on receipt of a chat or group | - System Config path: **Plugins > MS Teams** | | chat from Microsoft Teams. | - ``config.json`` setting: N/A | | | - Environment variable: N/A | -| - **true**: Sync notifications of chat messages for any connected user | | -| that enables the feature. | | -| - **false**: **(Default)** Do not sync notifications. | | +| - **true**: **(Default)** Sync notifications of chat messages for any | | +| connected user that enables the feature. | | +| - **false**: Do not sync notifications. | | +------------------------------------------------------------------------+----------------------------------------------------+ -.. config:setting:: plugins-msteamssynclinkedchannels - :displayname: Sync linked channels (Plugins - MS Teams) - :systemconsole: Plugins > MS Teams - :configjson: N/A - :environment: N/A - :description: Sync messages from channels linked between Mattermost and MS Teams. - -Sync linked channels -~~~~~~~~~~~~~~~~~~~~ - -+------------------------------------------------------------------------+----------------------------------------------------+ -| Sync messages from channels linked between Mattermost and MS Teams. | - System Config path: **Plugins > MS Teams** | -| | - ``config.json`` setting: N/A | -| | - Environment variable: N/A | -| - **true**: Messages from linked channels are synced, and new channels | | -| can be setup for synchronization. | | -| - **false**: **(Default)** Messages are not synced and new channels | | -| cannot be setup for synchronization. | | -+------------------------------------------------------------------------+----------------------------------------------------+ - - .. config:setting:: plugins-msteamsmaxsizeattachments :displayname: Maximum size of attachments to support complete one time download (Plugins - MS Teams) :systemconsole: Plugins > MS Teams diff --git a/source/images/microsoft-teams-linked-channel.png b/source/images/microsoft-teams-linked-channel.png deleted file mode 100644 index 9aec3e0d6fb..00000000000 Binary files a/source/images/microsoft-teams-linked-channel.png and /dev/null differ diff --git a/source/images/teams-user-as-bot.png b/source/images/teams-user-as-bot.png deleted file mode 100644 index a4bee07ca11..00000000000 Binary files a/source/images/teams-user-as-bot.png and /dev/null differ diff --git a/source/integrate/microsoft-teams-interoperability.rst b/source/integrate/microsoft-teams-interoperability.rst index 7565bf5abb1..65f548b4b1f 100644 --- a/source/integrate/microsoft-teams-interoperability.rst +++ b/source/integrate/microsoft-teams-interoperability.rst @@ -42,7 +42,7 @@ Set up an OAuth application in Azure - **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`` + - **Redirect URI**: ``https://(MM_SITE_URL)/plugins/com.mattermost.msteams-sync/oauth-redirect`` Replace ``(MM_SITE_URL)`` with your Mattermost server's Site URL. Select **Register** to submit the form. @@ -65,18 +65,10 @@ Replace ``(MM_SITE_URL)`` with your Mattermost server's Site URL. Select **Regis 9. 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`` + - ``Chat.Read`` - ``ChatMessage.Read`` - - ``Directory.Read.All`` - ``Files.Read.All`` - - ``Files.ReadWrite.All`` - ``offline_access`` - - ``Team.ReadBasic.All`` - ``User.Read`` 10. Select **Add permissions** to submit the form. @@ -85,14 +77,7 @@ Replace ``(MM_SITE_URL)`` with your Mattermost server's Site URL. Select **Regis 12. 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``) 13. Select **Add permissions** to submit the form. @@ -101,7 +86,7 @@ Replace ``(MM_SITE_URL)`` with your Mattermost server's Site URL. Select **Regis 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 +Follow the steps here to associate your application with a paid subscription: https://learn.microsoft.com/en-us/graph/metered-api-setup .. important:: @@ -114,19 +99,6 @@ Mattermost configuration With the Tenant ID, Client ID, and Client secret noted above, the Mattermost plugin is ready for configuration. See the :ref:`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. - - .. image:: ../images/teams-user-as-bot.png - :alt: 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 -------------------- @@ -144,16 +116,6 @@ Grafana dashboards `are available on GitHub `__ 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 ----- @@ -174,7 +136,7 @@ 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. +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. Are there any database or network security considerations? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -189,7 +151,7 @@ There is nothing specific to the integration that is beyond what would apply to 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. +The integration subscribes to change notifications from the Microsoft Graph API. These change notifications inform Mattermost about new or updated chats within Microsoft Teams. Upon receipt of the change notification, the integration uses 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 represent them appropriately within Mattermost. Get help --------