Repository: mattermost/mattermost-plugin-msteams-devsecops
Pull request #47: Consolidate product docs & README
Author: login: cwarnermm
Labels: name: 2: Dev Review
description: Requires review by a core committer
Created: 2025-05-06T13:24:55Z | Merged: 2025-05-12T20:51:12Z

Consolidating setup and installation details into the product documentation.


Diff:
diff --git a/README.md b/README.md
index c30ef94..d8b0381 100644
--- a/README.md
+++ b/README.md
@@ -7,15 +7,7 @@
 > [!NOTE]  
 > This product is currently in **Beta**. We're excited to share it with you and welcome your feedback to help us improve. While the core features are ready for use, you may encounter minor issues as we continue to refine the experience. Please share your thoughts and suggestions in the [~user-feedback](https://community.mattermost.com/core/channels/user-feedback) channel or submit an issue on [GitHub](https://github.com/mattermost/mattermost-plugin-msteams-devsecops/issues).
 
-This repository provides the foundation for multiple Microsoft app offerings that integrate with the Mattermost platform. 
-
-
-- **Mattermost Mission Collaboration for Microsoft**: Extend Enterprise communications to the Tactical Edge by accessing Mattermost from your Microsoft Office365, Teams, and Outlook user experiences. 
-- **Community Mattermost for Microsoft 365 & MS Teams**: Free offering to explore Mattermost capabilities and meet with fellow end users, customers and evaluators, along with Mattermost staff. 
-
-## Mattermost Mission Collaboration for Microsoft 365 & MS Teams
-
-The **Mattermost Mission Collaboration for Microsoft** application extends Enterprise communications with secure external collaboration controlled by IT by accessing Mattermost from your Microsoft Office365, Teams, and Outlook user experiences.
+## Mattermost Mission Collaboration for Microsoft 365 and MS Teams
 
 ![image](./docs/External-Collaboration-with-Enterprise-Control-Microsoft.png)
 
@@ -41,71 +33,10 @@ This app is designed to work with Microsoft 365, Outlook, and Microsoft Teams.
 
 ### Admin Setup
 
-For detailed setup instructions, see the [Setup Guide](./docs/admin_setup.md), which provides step-by-step instructions for creating and configuring a Microsoft Teams application in Azure.
+For detailed setup instructions, see the [Setup Guide](https://docs.mattermost.com/integrate/mattermost-mission-collaboration-for-m365.html#setup), which provides step-by-step instructions for creating and configuring a Microsoft Teams application in Azure, setting up the Mattermost plugin, and installing Mattermost in Microsoft Teams.
 
 ### FAQ
 
 #### Where can I get support?
 
 You can browse existing open issues or submit a new issue for support in GitHub: https://github.com/mattermost/mattermost-teams-tab/issues
-
-## Community Mattermost for Microsoft 365 & MS Teams
-
-The *Community Mattermost for Microsoft 365* application provides a showcase and peer-to-peer discussion environment for Mattermost customers, open source users, and system evaluators.
-
-Community Mattermost runs as an online service at https://community.mattermost.com and is made available in Microsoft Teams, Microsoft Outlook, and the Microsoft Application hosting environment with this offering.
-
-**Capabilities:**
-- Connect to the Mattermost Community environment as a Microsoft application from within Microsoft Teams and Outlook web and desktop environments.
-
-**Benefits:**
-- Seamlessly communicate with the Mattermost Community from Microsoft Teams and Outlook using application tabs.
-- Evaluate a showcase deployment of Mattermost capabilities in consideration of self-hosting the platform within your Azure or on-prem environments.  
-- Share input with Mattermost staff and developers on future improvements to the platform.
-
-The following future capabilities are being considered for addition in upcoming releases:
-
-- Integrated notifications across Mattermost and Microsoft Teams.
-- Optional Single-Sign-On with integrated authentication.
-
-**Key Features:**  
-- **Direct Access**: Access the Mattermost Customer Community directly from a tab without switching applications or opening a browser.  
-- **Seamless Integration**: Experience the full functionality of the Mattermost Customer Community within a familiar interface.  
-- **Real-time Collaboration**: Engage with the Mattermost community in real-time discussions on product features, technical questions, and best practices.  
-- **Professional Support**: Licensed customers can get help from Mattermost staff.
-- **Peer-to-Peer Q&A**: All customers and users of Mattermost free and open source editions can get peer-to-peer help and input at no cost.
-- **Contribute to Development**: Participate in discussions that shape the future direction of Mattermost products.  
-- **Knowledge Sharing**: Learn implementation strategies and best practices from a diverse community of users.  
-- **Stay Updated**: Keep up with the latest Mattermost announcements, updates, and roadmap information.  
-
-This app is designed to work with Microsoft 365, Outlook, and Microsoft Teams. A free account is required to use the Mattermost Customer Community.  
-
-**About Mattermost:**  
-Mattermost is a purpose-built platform for technical and operational teams in organizations vital to national security, public safety, and critical infrastructure. [https://mattermost.com/](https://mattermost.com/)   
-
-### End User Setup
-
-Any Microsoft 365 user can complete the steps below to access Mattermost for Microsoft 365 within their Microsoft environment, provided their organization allows users to install apps from the App Store:
-1. Sign in to your Microsoft Teams account [from a web browser](https://teams.microsoft.com/v2/?clientexperience=t2) or the desktop application.
-2. Select the [+] Apps button in the Teams sidebar.
-3. Search for Mattermost for Microsoft 365 and then select Add to install the application.
-4. (Optional) Pin the Mattermost app to your Teams sidebar by right-clicking on it and selecting Pin.
-5. Once the Mattermost app is installed, you’ll be connected to the public Mattermost Community instance.
-
-### Getting started
-
-Once you’ve installed the app, here are some ways to get started:
-
-- **Ask questions**: Use the [~ask-anything](https://community.mattermost.com/core/channels/ask-anything) channel to ask technical questions or get support from the community.
-- **Contribute**: If you’re interested in contributing to Mattermost, join the [~developers](https://community.mattermost.com/core/channels/developers) channel to connect with other contributors.
-- **Share feedback**: Your ideas and feedback are valuable. Share your thoughts in the [~user-feedback](https://community.mattermost.com/core/channels/user-feedback) channel.
-
-### FAQ
-
-#### Where can I get support?
-
-You can browse existing open issues or submit a new issue for support in GitHub: https://github.com/mattermost/mattermost-teams-tab/issues
-
-#### Do I need a Mattermost account to use this application?
-Yes, you’ll need to create a free account on the Mattermost Community server when you first access it through the app.
-
diff --git a/docs/Enterprise-to-Tactical-Edge-with-Mattermost-and-Microsoft.png b/docs/Enterprise-to-Tactical-Edge-with-Mattermost-and-Microsoft.png
deleted file mode 100644
index 6975ab7..0000000
Binary files a/docs/Enterprise-to-Tactical-Edge-with-Mattermost-and-Microsoft.png and /dev/null differ
diff --git a/docs/External-Collaboration-with-Enterprise-Control-Microsoft.png b/docs/External-Collaboration-with-Enterprise-Control-Microsoft.png
deleted file mode 100644
index c704a90..0000000
Binary files a/docs/External-Collaboration-with-Enterprise-Control-Microsoft.png and /dev/null differ
diff --git a/docs/admin_setup.md b/docs/admin_setup.md
deleted file mode 100644
index aa0206e..0000000
--- a/docs/admin_setup.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# Administrator Setup
-
-## Create and setup a Teams application in Azure
-
-1. Go to your **Azure Portal > Microsoft Entra ID**
-
-2. Go to **App registrations**
-
-3. Create a new app registration by clicking **Add > App registration**
-    - Give it a name
-    - Accounts in this organizational directory only (single tenant)
-    - No redirect URIs
-
-4. Go to your newly created application
-    - Make note of these values as you'll need those later:
-        - Application (client) ID → _Required in the plugin configuration_
-        - Directory (tenant) ID → _Required for the plugin configuration_
-        ![System Console Configuration](./remember-tenant-client.png)    
-
-5. Go to **Certificates and secrets**
-    - Generate a new Client secret
-    - Make note of the secret value → _Required in the plugin configuration_
-    ![System Console Configuration](./remember-client-secret.png)    
-
-6. Go to **API Permissions**
-    - Ensure `User.Read` **delegated** permission is added ([Microsoft documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#enable-sso-in-microsoft-entra-id))
-    - Add `TeamsActivity.Send` **application** permission for notifications ([Microsoft documentation](https://learn.microsoft.com/en-us/graph/teams-send-activityfeednotifications?tabs=desktop%2Chttp))
-    - Add `AppCatalog.Read.All` **application** permission for notifications ([Microsoft documentation](https://learn.microsoft.com/en-us/graph/api/appcatalogs-list-teamsapps?view=graph-rest-1.0&tabs=http))
-    - Grant admin consent for the default directory to prevent users from seeing the consent prompt.
-
-7. Go to **Expose an API**
-    - Edit the "_Application ID URI_" as such: `api://{{Mattermost Site URL Hostname}}/{{Application (client) ID}}`
-    - Add the `access_as_user` scope by clicking the "Add a scope" button. ([Microsoft documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#to-configure-api-scope))
-        - **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.
-        - Add authorised client applications for the scope we just created ([Microsoft documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#to-configure-authorized-client-application))
-            - Click on "_Add a client application_". **You need to add a client application per target Microsoft application you want**:
-                - **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 application, you need to 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).
-
-## Setup the plugin in Mattermost
-
-1. Download the latest release of the plugin from [here](https://github.com/mattermost/mattermost-plugin-msteams-devsecops/releases).
-
-2. Install the plugin by following the normal plugin installation process. For detailed instructions, refer to steps 1 through 5 of [this guide](./install_plugin.md).
-
-3. Go to your **Mattermost server's system console > Plugins > MSTeams DevSecOps**
-
-4. Enter an Application Version. You can start with "1.0.0".
-
-5. Generate an Application ID in version 4 UUID format and enter it in the Application ID field. [UUID Generator](https://www.uuidgenerator.net/) will create a random ID in the correct format.
-
-6. Enter the values you noted earlier in the appropriate fields:
-    ![System Console Configuration](./tenant-client-secret-sysconsole.png)
-
-    - **Directory (tenant) ID**: The Directory (tenant) ID you noted from step 4
-    - **Application (client) ID**: The Application (client) ID you noted from step 4
-    - **Client Secret**: The secret value you generated in step 5
-
-7. Enter an Application Display Name. This can be any name you choose, and will be how your application is named in the MS Teams app store.
-
-8. Save the changes and enable the plugin.
-
-9. Click the "Download Manifest" button. This will 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 the application in MS Teams
-
-1. Go to the [Microsoft Teams admin center](https://admin.teams.microsoft.com/dashboard).
-
-2. Go to **Teams apps > Manage apps**.
-
-![Manage Apps in Microsoft Teams](./select-manage-apps.png)
-
-3. Go to **Actions > Upload new app** (upper right corner of the Manage apps page).
-
-4. Click **Upload** and select the ZIP file saved previously.
-
-5. **Done!** 🎉 Your application is now available to users.
diff --git a/docs/install_plugin.md b/docs/install_plugin.md
deleted file mode 100644
index e988af3..0000000
--- a/docs/install_plugin.md
+++ /dev/null
@@ -1,70 +0,0 @@
-
-## **Installing a Plugin to a Mattermost Server**
-
-#### **Prerequisites**
-1. You must have admin access to the Mattermost server.
-2. Ensure that the Mattermost server is running.
-3. Have the plugin binary file ready on your local system or accessible through a server.
-4. The plugin file should match your Mattermost server version and be verified for compatibility.
-
----
-
-### **Step-by-Step Instructions**
-
-#### **Step 1: Login to the Mattermost Admin Console**
-1. Open a web browser and go to your Mattermost server URL. Example: `https://<mattermost_domain>/`.
-2. Log in with an account that has System Admin permissions.
-
-#### **Step 2: Navigate to the Plugin Management Section**
-1. From the sidebar, select the gear icon to access the **System Console**.
-2. In the System Console, go to **Plugins** -> **Management**.
-
----
-
-#### **Step 3: Upload the Plugin**
-1. Under the **Management** section, locate the **Upload Plugin** button.
-2. Click **Upload Plugin** to open a file selection dialog.
-3. Select the `.tar.gz` or `.zip` file of the plugin from your local system.
-
----
-
-#### **Step 4: Wait for the Upload to Complete**
-1. Once uploaded, Mattermost will automatically unpack the plugin and check its validity.
-2. If the upload is successful, the plugin will appear in the list of installed plugins.
-   - If an error occurs (e.g., version incompatibility), it's displayed immediately. Address the error and retry the upload.
-
----
-
-#### **Step 5: Enable the Plugin**
-1. Locate the plugin in the **Installed Plugins** list.
-2. Click the **Enable** button next to the plugin name to activate it.
-
----
-
-#### **Step 6: Configure the Plugin**
-1. Once enabled, click the **Settings** or **Configure** button next to the plugin name if custom settings are needed.
-2. Fill out any required configurations such as API keys, service URLs, or other parameters.
-3. Save the settings.
-
----
-
-#### **Step 7: Verify Plugin Functionality**
-1. Inform your team or test the plugin functionality yourself.
-2. Depending on the plugin, it may add options in the user interface, commands in message boxes, or integrations with external services.
-
----
-
-### **Troubleshooting**
-- **Plugin Fails to Upload:** Ensure the plugin file is compatible with the Mattermost server version.
-- **Plugin Fails to Enable:** Check server logs via the **System Console** -> **Logs** section for error messages.
-- **Performance Issues:** Disable the plugin temporarily and contact the plugin developer.
-
----
-
-### **Automated Plugin Installation (Optional)**
-If you prefer command-line tools, upload the plugin using Mattermost’s API or CLI:
-```bash
-# Example for CLI
-mattermost plugin install <path_to_plugin_file>
-```
-
diff --git a/docs/remember-client-secret.png b/docs/remember-client-secret.png
deleted file mode 100644
index 2a77cb3..0000000
Binary files a/docs/remember-client-secret.png and /dev/null differ
diff --git a/docs/remember-tenant-client.png b/docs/remember-tenant-client.png
deleted file mode 100644
index 161084f..0000000
Binary files a/docs/remember-tenant-client.png and /dev/null differ
diff --git a/docs/select-manage-apps.png b/docs/select-manage-apps.png
deleted file mode 100644
index 0223328..0000000
Binary files a/docs/select-manage-apps.png and /dev/null differ
diff --git a/docs/tenant-client-secret-sysconsole.png b/docs/tenant-client-secret-sysconsole.png
deleted file mode 100644
index 9402024..0000000
Binary files a/docs/tenant-client-secret-sysconsole.png and /dev/null differ


Reviews:
user: login: wiggin77
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-10T01:33:15Z
user: login: cwarnermm
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T13:26:07Z
user: login: wiggin77
state: APPROVED
author_association: MEMBER
submitted_at: 2025-05-12T20:51:03Z

Review comments:
diff_hunk: @@ -7,13 +7,12 @@
 > [!NOTE]  
 > This product is currently in **Beta**. We're excited to share it with you and welcome your feedback to help us improve. While the core features are ready for use, you may encounter minor issues as we continue to refine the experience. Please share your thoughts and suggestions in the [~user-feedback](https://community.mattermost.com/core/channels/user-feedback) channel or submit an issue on [GitHub](https://github.com/mattermost/mattermost-plugin-msteams-devsecops/issues).
 
-This repository provides the foundation for multiple Microsoft app offerings that integrate with the Mattermost platform. 
-
+This repository provides the foundation for multiple Microsoft app offerings that integrate with the Mattermost platform, including:
 
 - **Mattermost Mission Collaboration for Microsoft**: Extend Enterprise communications to the Tactical Edge by accessing Mattermost from your Microsoft Office365, Teams, and Outlook user experiences. 
-- **Community Mattermost for Microsoft 365 & MS Teams**: Free offering to explore Mattermost capabilities and meet with fellow end users, customers and evaluators, along with Mattermost staff. 
+- **Community Mattermost for Microsoft 365 & MS Teams**: Free offering to explore Mattermost capabilities and meet with fellow end users, customers and evaluators, along with Mattermost staff. [Learn more](#community-mattermost-for-microsoft-365-and-ms-teams)
path: README.md
user: login: wiggin77
body: Community can be removed here as well.  Plus we won't need the "provides the foundation for multiple Microsoft app offerings" line either as this repo is focused on one product.  

I think we've gutted this README to the point that it no longer describes what this product is at a glance.  In a new PR I'll add a separate line near the top that tells the simple story that this product embeds Mattermost in Teams.
created_at: 2025-05-10T01:33:14Z
author_association: MEMBER
diff_hunk: @@ -7,13 +7,12 @@
 > [!NOTE]  
 > This product is currently in **Beta**. We're excited to share it with you and welcome your feedback to help us improve. While the core features are ready for use, you may encounter minor issues as we continue to refine the experience. Please share your thoughts and suggestions in the [~user-feedback](https://community.mattermost.com/core/channels/user-feedback) channel or submit an issue on [GitHub](https://github.com/mattermost/mattermost-plugin-msteams-devsecops/issues).
 
-This repository provides the foundation for multiple Microsoft app offerings that integrate with the Mattermost platform. 
-
+This repository provides the foundation for multiple Microsoft app offerings that integrate with the Mattermost platform, including:
 
 - **Mattermost Mission Collaboration for Microsoft**: Extend Enterprise communications to the Tactical Edge by accessing Mattermost from your Microsoft Office365, Teams, and Outlook user experiences. 
-- **Community Mattermost for Microsoft 365 & MS Teams**: Free offering to explore Mattermost capabilities and meet with fellow end users, customers and evaluators, along with Mattermost staff. 
+- **Community Mattermost for Microsoft 365 & MS Teams**: Free offering to explore Mattermost capabilities and meet with fellow end users, customers and evaluators, along with Mattermost staff. [Learn more](#community-mattermost-for-microsoft-365-and-ms-teams)
path: README.md
user: login: cwarnermm
body: Thanks @wiggin77! My latest commit removes these unnecessary references.
created_at: 2025-05-12T13:26:07Z
author_association: CONTRIBUTOR

PR comments:
user: login: wiggin77
created_at: 2025-05-09T13:34:06Z
body: @cwarnermm can we lose the Community for Mattermost section as well?  It probably does not belong here.  Someone on this readme is not looking for Community.
author_association: MEMBER
user: login: cwarnermm
created_at: 2025-05-09T14:40:31Z
body: Thanks, @wiggin77 - I agree on removing and will do so in a new commit. I found it odd it was here. What's the repo for the community plugin? I'll review what's there and consolidate as needed.
author_association: CONTRIBUTOR