Microsoft Teams

Overview

This document will help you set up InsightConnect for use with MicrosoftTeams.

There are a few things you need before you get started:

  1. Have an existing user account. If needed create a new user or service account: https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/add-users-azure-active-directory
  2. Create an Azure Application with the correct permissions: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal

Permissions for each are listed below in two sections, Send / Receive and Teams Management.

The InsightConnect Teams Plugin uses delegated permissions to talk to your Teams instance through Microsoft Graph API. This will require both a user account that’s authorized to send and receive messages on the channel(s) you will be monitoring and an application with the correct permissions to act on behalf of that user.

The application permissions are listed below and must be delegated to act on behalf of a user.

The user must be included in the Teams team or Azure group that this application will monitor.

Permissions

The permissions here are split into two sections. If your workflow only needs to send and receive messages, then the permissions needed are minimal. However, if you’d like to manage your teams through the application, elevated permissions will be needed as the application will be performing administrative tasks.

Send and Receive

Minimum application permissions needed for send/receive:

  • Chat.ReadWrite (Delegated)
  • Group.ReadWrite.All (Delegated)

Reference

User Permissions for send/receive:

The user simply needs to be a part of the Team that the plugin will send and receive messages.

Teams Management

Minimum application permissions needed for Teams management:

  • Directory.ReadWrite.All
  • Group.ReadWrite.All

Reference

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.

  • Create Team Enabled Group: Global Administrators - Team enablement requires changing the properties on a group, that can only be done by a Global Admin.
  • All other actions: User Administrators - Add and remove users from a group, create channel, and remove can be done by a User Administrator

Configure the connection in InsightConnect:

The Teams plugin in InsightConnect will require the following information:

For the Application ID and Directory ID go to your application registration in Azure and check the overview.

For the Application Secret, go to “Certificates and secrets” in the left menu.

The username in InsightConnect must be fully qualified. For example @ or *joey@rapid7.onmicrosoft.com

Create a new secret using the “New client secret” button.

NOTE: The client secret will only be available when you first create the secret. After you leave this screen it will be hidden. Be sure to save it someplace safe.

Appendix

InsightConnect Test App Setup:

Other helpful information:

Get access on behalf of a user

Delegated permissions

Graph Permissions Reference

User Permissions