Self-managed Microsoft Teams

This guide explains how to configure the Microsoft Teams integration for a Cortex self-managed account. This integration requires a Teams app, which needs to be configured in your own Teams workspace when using Cortex Self-Managed.

If you are looking for instructions on configuring a Microsoft Teams integration for your Cortex cloud workspace, please see Integrations > Microsoft Teams.

Setup instructions​

Create the app​

1. Use existing OAuth credentials or create a new Enterprise application in Azure. The following environment variables are referred to later on.

   MICROSOFT_TEAMS_CLIENT_ID - the Application ID

   MICROSOFT_TEAMS_CLIENT_SECRET - the Client Secret

   MICROSOFT_TEAMS_REDIRECT_URI - the Redirect URI, "[Cortex Frontend URL]/oauth/internal/microsoft_teams"

2. Create a Bot Service in Azure. The following environment variables are referred to later on.

   MICROSOFT_TEAMS_BOT_APP_ID - the Microsoft App ID for the bot

   MICROSOFT_TEAMS_BOT_APP_PASSWORD - the Bot Password

3. Create/Upload the Teams App

   Use the following manifest to create a new Teams app in your workspace.

   Make sure to replace the URLs found in [] with the URLs you set up for your self-managed Cortex instance.

   {
     "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
     "manifestVersion": "1.16",
     "version": "1.0.0",
     "id": "[MICROSOFT_TEAMS_BOT_APP_ID]",
     "developer": {
       "name": "Cortex",
       "websiteUrl": "https://www.cortex.io",
       "privacyUrl": "https://www.cortex.io/legal/privacy-policy",
       "termsOfUseUrl": "https://www.cortex.io/legal/terms-of-service",
       "mpnId": "6762083"
     },
     "name": {
       "short": "Cortex",
       "full": "Cortex | Internal Developer Portal"
     },
     "description": {
       "short": "Stay on top of your Cortex Scorecard scores & Initiatives",
       "full": "Cortex Scorecards and Initiatives help your team establish best practices and improve quality. We’ll send you a weekly notification to let you know what’s on your plate for the week as well as notifications for any new Initiatives, upcoming Initiative deadlines, and score changes for services that you own. Book a demo: https://www.cortex.io/demo?utm_source=docs\nContact sales: https://go.cortex.io/contact-sales-request.html\nSupport hub: https://support.getcortexapp.com/hc/en-us\nSupport email: [email protected]\nGet started: https://docs.cortex.io"
     },
     "icons": {
       "outline": "cortex32x32.png",
       "color": "cortex192x192.png"
     },
     "accentColor": "#25074D",
     "bots": [
       {
         "botId": "[MICROSOFT_TEAMS_BOT_APP_ID]",
         "scopes": [
           "personal"
         ],
         "needsChannelSelector": false,
         "isNotificationOnly": false,
         "supportsFiles": false,
         "supportsCalling": false,
         "supportsVideo": false,
         "commandLists": []
       }
     ],
     "validDomains": [
       "[Cortex Backend URL]"
     ],
     "showLoadingIndicator": false,
     "isFullScreen": false,
     "defaultBlockUntilAdminAction": false,
     "defaultInstallScope": "personal",
     "configurableProperties": [],
     "webApplicationInfo": {
       "id": "[MICROSOFT_TEAMS_CLIENT_ID]"
     }
   }

4. Configure the Messaging endpoint - "[Cortex API URL]/api/v1/microsoft/teams/webhook"

5. Upload a zipped manifest along with the icons to your Teams instance. Note: only Teams admins can do this.

If your Cortex Self-Managed installation is not available from the public internet, the Microsoft Teams notifications will not work, as Microsoft Teams needs to be able to hit the Cortex API when a command is run.

Connect your Cortex instance​

You'll need to configure your on-prem deployment to be able to talk your Teams App.

1. Create a k8s secret and add the secret in your values.yaml file for the Helm chart. You may already have a secret set up if you had configured a persistent store previously, so be sure to verify in your Helm chart.

2. Add the follow key/values to the secret (keeping in mind they need to be base64 encoded in k8s):

   1. MICROSOFT_TEAMS_CLIENT_ID

   2. MICROSOFT_TEAMS_CLIENT_SECRET

   3. MICROSOFT_TEAMS_REDIRECT_URI

   4. MICROSOFT_TEAMS_BOT_APP_ID

   5. MICROSOFT_TEAMS_BOT_APP_PASSWORD

3. Restart your Cortex backend deployment