Microsoft Teams Connection Guide

Microsoft Teams Connection Guide

Microsoft Teams is a unified communications platform that combines persistent workplace chat, video meetings, file storage and application integration. The Microsoft Teams plugin allows you to send and trigger workflows on new messages. The plugin will also allow for teams management with the ability to add and remove teams, channels, and users.

There are few things you need to do before you get started:

  • To collect configuration information log into your Azure Portal.
  • Create a new user within Azure for use by the integration.
  • Typically, Microsoft will require a user to change their password upon first login, so log into the new user account and change the password. Note that the user must be non-federated and must have MFA disabled.

Application ID:

Note

These steps may require additional team members outside of security. Creating App Registrations within Azure requires higher levels of permissions, which some organizations reserve for their IT or Infrastructure teams.

In case the Application already exists, please contact an Azure Admin to grant access to the Application.

  1. In the side navigation of the Azure portal, click Azure Active Directory, then select App Registrations in the secondary navigation menu.

  2. Click New Registration.

    New App Registration

  3. Complete the form with InsightConnect for the name, Web app/API for the application type and https://login.microsoftonline.com for the sign in URL. Then click Create.

  4. Save the application registration to Azure, copy and save Application ID.

  5. Click on the newly registered application, then select Certificates & Secrets.

Register Application

Application Secret Key:

Azure uses asymmetric keys to authenticate and secure communications with other applications. You will need to create a new key in Azure to use for configuring InsightConnect connections.

  1. Click on Certificates & secrets.
  2. Select New client secret.
  3. Give the key a description and set the duration of key. It will expire when the duration you set ends. Then click on Add.
  4. Azure will generate a value for your new key. Copy and save this string now, as you will not be able to see and retrieve it after you leave this page in the Azure Portal.

New Secret Key

Configure the connection in InsightConnect:

Login to InsightConnect, expand the Settings drop-down and navigate to Plugins & Tools. Click "Add Plugin" and import the "Microsoft Teams" plugin. If already imported, please ensure you update plugin to the newest version.

Now go to the Connections tab and create a new Connection. Choose your Orchestrator, and select the Microsoft Teams plugin from the drop-down menu. Supply it with Application ID and Secret Key.

Connections in InsightConnect

Tenant ID:

  1. Your Tenant ID can be found in the side navigation of the Azure Active Directory. Click Overview.
  2. If you need to create a new Tenant ID, select Overview then choose Manage Tenants and click Create.

tennant ID

Configure Application Permissions:

After registering a new Application in Azure, you will need to configure permissions needed for Microsoft Teams.

The Microsoft Teams plugin needs the following permissions to work correctly:

  • Delegated Permissions:
    • Chat.ReadWrite
    • Group.ReadWrite.All
  • Application Permissions:
    • Directory.ReadWrite.All
    • Group.ReadWrite.All

Please note that only the Delegated Permissions are necessary for the "New Message Received" trigger and the various Send Message actions to function.

  1. In the "Application" menu within Azure, navigate to API Permissions.
  2. Click on Add Permision, then select Microsoft API's from Microsoft Graph, choose Delegated Permissions.
  3. Check the following options and save: Chat.ReadWrite, Group.ReadWrite.All
  4. Click on Add Permission, then select Microsoft API's from Microsoft Graph, then choose Application Permissions.
  5. Check the following options and save: Directory.ReadWrite.All, Group.ReadWrite.All

Select Permissions

Grant Access For Users:

Grant access to users must be enabled. This can be done in the same menu where you have created Application permissions. Select and click Grant Admin Consent For Users.

Grant Access for User

User Permissions for Teams Management:

The user used in this instance will need to have elevated permissions as well, as the application is working on their behalf. To enable the following actions for your user, include them in the specified administrative group in Azure.

  • To enable the "Create Team Enabled Group" action, the user must be in the Global Administrators group. Team enablement requires changing the properties on a group, which can only be done by a Global Admin.
  • To enable all other Teams Management actions, such as adding and removing users from a group, creating channels, or removing users from channels—the user must be in the User Administrators group.

Automatically Extract Indicators from a Microsoft Teams Message:

Instead of constantly switching contexts in different tools, you can configure your chat solutions within InsightConnect to listen for message commands that will kick-off workflows.

InsightConnect also support message threading in both Slack and Microsoft Teams so you can conveniently organize your chat communications. Additionally, InsightConnect maintains a growing library of prebuilt workflow templates that trigger functionality from Slack and Microsoft Teams that can be imported with one click.

The Microsoft Teams plugin automatically extracts commands and common network or security indicators from your messages. You can use these variables to configure additional workflow actions without having to worry about configuring potentially complex regex or pattern match steps.

To configure a workflow to kick-off from a Microsoft Teams message, update the Microsoft Teams trigger (the first step in your workflow) with the channel name to monitor your Microsoft Teams environment. Then, to run your workflow, send a message to the specified Microsoft Teams channel.

Each of your Microsoft Teams messages follows the same format: [command] [indicator]. An example command might look like this: !block-host 1.1.1.1. InsightConnect automatically extracts and captures commands, like block-host in this case, in a variable called $first_word.

When your command is followed by a commonly used network or security indicator, our chatbot detects the format of the indicator, extracts it automatically, and stores it in an output variable.

These are the commonly used network and security indicator types we capture and store:

  • IP addresses (IPv4 and IPv6)
  • MD5 hashes
  • SHA1 hashes
  • SHA256 hashes
  • MAC addresses
  • Email addresses
  • Domain names
  • URLs

chatops output

You can use these output variables later in your workflow to easily configure further actions. For example, add a hash to a denylist, enrich a URL or domain with a threat intelligence plugin, delete an email from user inboxes, or block an IP address, all without having to parse these indicators out of your chat messages manually.

Other helpful information:

Troubleshoot the Microsoft Teams Plugin:

Provisioning a Federated User:

If you are in the process of provisioning federated or single-sign-on accounts in your environment. This will not work for our plugin, InsightConnect operates on behalf of through Microsoft Teams needs to be a non-federated user provisioned in their onmicrosoft.com domain.

Error messages to look for:

AADSTS50126: Error validating credentials due to invalid username or password. That specific error code can indicate that the user account is federated - Microsoft article

Forgetting to perform a manual login:

Sometimes, if you do not perform a manual login into your account, this can ultimately result in Connection errors. Microsoft will typically treat the user's initial password as temporary, and require a password change upon first login.

Including unnecessary permissions that cause interference:

Sometimes, adding additional permissions to the app registration in Azure that can cause conflicts.

For example, our plugin requires Chat.ReadWrite (delegated) in order to successfully send and receive messages. There are other delegated Chat permissions available within Azure, such as Chat.Read, which you may instinctively assume they should include as well. Microsoft generally leverages a "least first" mentality with permissions, so if an application is given the Chat.Read permission in addition to Chat.ReadWrite, Chat.Read will take precedence, and potentially cause errors.