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 a 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 as a service account for 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 the following:

    • Name: InsightConnect
    • Redirect URL: The platform type is Web app/API, and the URL is https://login.microsoftonline.com.

Register Application

  1. Click Register.
  2. Copy and save the Application ID.
  3. Within the newly registered application, select Certificates & Secrets.

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 its duration. Take note of the expiration date you provide, as this app registration will no longer function within InsightConnect upon expiration.
  4. Click on Add.
  5. Azure will generate a value for your new key. In Azure, this secret key will be labeled as Value. Copy and save this value, as it will be used later to establish a Microsoft Teams connection within InsightConnect.

New Secret Key

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 in InsightConnect.

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

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:

Users will need elevated permissions in the following scenarios to perform administrative actions within Microsoft Teams:

  • To “Create Team Enabled Group”—the user must be in the Global Administrators Group. Since team enablement requires changing the properties on a group, the user must be a Global Admin.
  • To add/remove users from a group, create channels, or remove users from channels—the user must be in the User Administrators Group.

No elevated permissions are required to use the New Message Received trigger from Microsoft Teams or to send messages to users or channels.

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. Select the Microsoft Teams plugin from the drop-down menu and complete the following steps:

  1. Under Application Secret, enter the Secret Key that was previously created. Note that the Secret Key is labeled as Value in Azure.
  2. Under Username Password, enter the credentials used for the service account that was previously created.
  3. Enter the Application ID. This is labeled as Application (client) ID in Azure and can be found on the Overview tab for the application.
  4. Enter the Directory ID. This is labeled as Directory (tenant) ID in Azure and can be found on the Overview tab for the application.

Connections in InsightConnect

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 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.