InsightConnect Marketplace

Microsoft Teams

Back to Marketplace

Microsoft Teams

v2.0.3

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

Tags: microsoft, teams, office 365, chat

Triggers
  • New Message Received

Actions
  • Add Channel to Team
  • Add Member to Team
  • Create Teams Enabled Group
  • Delete Team
  • Get Channels for Team
  • Get Teams
  • Remove Channel from Team
  • Remove Member from Team
  • Send HTML Message
  • Send Message
  • Send Message by GUID

Description

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.

This plugin uses the Microsoft Teams API to interact with Microsoft Teams.

Key Features

  • Communication Management for all microsoft products

Requirements

  • Username and Password
  • Secret Key, similar to API Key

Documentation

Setup

The connection configuration accepts the following parameters:

Name Type Default Required Description Enum Example
application_id string None True Application (client) ID None None
application_secret credential_secret_key None True Application secret None None
directory_id string None True Directory (tenant) ID None None
username_password credential_username_password None True Username and password None None

Example input:

{
  "application_id": "xxxxxxx-xxxxxx-xxxxx-xxxx",
  "application_secret": {
    "secretKey": "xxxxxxx"
  },
  "directory_id": "xxxx-xxxx-xxxx-xxxx-xxx",
  "username_password": {
    "password": "password",
    "username": "user@example.com"
}

Technical Details

Actions

Send Message

This action is used to send a message.

Regular expressions used by this action are Python specific.

Input
Name Type Default Required Description Enum Example
channel_name string None True Channel None None
message string None True Message to send None None
team_name string None True Team name None None

Example input:

{
  "channel_name": "ICON Test Channel",
  "message": "Hello!",
  "team_name": "ICON-Test-Everyone"
}
Output
Name Type Required Description
message message False The message object that was created

Example output:

{
  "message": {
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('xxxx')/channels('xxxxxxx')/messages/$entity",
    "id": "1571769574238",
    "etag": "1571769574238",
    "messageType": "message",
    "createdDateTime": "2019-10-22T18:39:34.238Z",
    "importance": "normal",
    "locale": "en-us",
    "webUrl": "https://teams.microsoft.com/l/message/xxxxxxxxxxxxxx/xxxxxx?groupId=xxxxx",
    "from": {
      "user": {
        "id": "xxxxxxx",
        "displayName": "Test User",
        "userIdentityType": "aadUser"
      }
    },
    "body": {
      "contentType": "text",
      "content": "Hello from InsightConnect!"
    },
    "attachments": [],
    "mentions": [],
    "reactions": []
  }
}

Send HTML Message

This action is used to send HTML as a message.

Input
Name Type Default Required Description Enum Example
channel_name string None True Channel name None None
message_content string None True HTML content to send None None
team_name string None True Team name None None

Example input:

{
  "channel_name": "ICON Test Channel",
  "message_content": "<b>Hello!</b>",
  "team_name": "ICON-Test-Everyone"
}
Output
Name Type Required Description
message message False The message object that was created

Example output:

{
  "message": {
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('xxxx')/channels('xxxxxxx')/messages/$entity",
    "id": "1571769574238",
    "etag": "1571769574238",
    "messageType": "message",
    "createdDateTime": "2019-10-22T18:39:34.238Z",
    "importance": "normal",
    "locale": "en-us",
    "webUrl": "https://teams.microsoft.com/l/message/xxxxxxxxxxxxxx/xxxxxx?groupId=xxxxx",
    "from": {
      "user": {
        "id": "xxxxxxx",
        "displayName": "Test User",
        "userIdentityType": "aadUser"
      }
    },
    "body": {
      "contentType": "text",
      "content": "Hello from InsightConnect!"
    },
    "attachments": [],
    "mentions": [],
    "reactions": []
  }
}

Send Message by GUID

This action sends a message using the GUID for the team and channel. This is more performant than send message.

Input
Name Type Default Required Description Enum Example
channel_guid string None True Channel GUID None None
is_html boolean None True Is the message HTML None None
message string None True Message to send None None
team_guid string None True Team GUID None None
Output
Name Type Required Description
message message False The message object that was created

Example input:

{
  "channel_guid": "xxxxx-xxxxx-xxxx-xxxx",
  "is_html": false,
  "message": "Hello!",
  "team_guid": "xxxxx-xxxxx-xxxx-xxxx"
}
Output
Name Type Default Required Description Enum
message message False The message object that was created None

Example output:

{
  "message": {
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('xxxx')/channels('xxxxxxx')/messages/$entity",
    "id": "1571769574238",
    "etag": "1571769574238",
    "messageType": "message",
    "createdDateTime": "2019-10-22T18:39:34.238Z",
    "importance": "normal",
    "locale": "en-us",
    "webUrl": "https://teams.microsoft.com/l/message/xxxxxxxxxxxxxx/xxxxxx?groupId=xxxxx",
    "from": {
      "user": {
        "id": "xxxxxxx",
        "displayName": "Test User",
        "userIdentityType": "aadUser"
      }
    },
    "body": {
      "contentType": "text",
      "content": "Hello from InsightConnect!"
    },
    "attachments": [],
    "mentions": [],
    "reactions": []
  }
}

Get Teams

This action returns all the teams the configured user is allowed to see.

This will only return Teams-provisioned teams.

Regular expressions used by this action are Python specific.

Input
Name Type Default Required Description Enum Example
team_name string None False Optional regex-capable team name to look for None None

Example input:

{
  "team_name": "Komand-Test-Everyone"
}
Output
Name Type Required Description
teams []team False Array of team objects

Example output:

{
  "teams": [
    {
      "id": "7af08a76-01fe-4a1d-bfa1-84d2b5509cdd",
      "createdDateTime": "2019-10-14T17:18:55Z",
      "description": "A test team of everyone",
      "displayName": "ICON-Test-Everyone",
      "externalGroupIds": [],
      "groupTypes": [
        "Unified"
      ],
      "mail": "user@example.com",
      "mailEnabled": true,
      "mailNickname": "Test Nickname",
      "membershipTypes": [],
      "proxyAddresses": [
        "SPO:xxxxxx",
        "SMTP:user@example.com"
      ],
      "renewedDateTime": "2019-10-14T17:18:55Z",
      "resourceBehaviorOptions": [
        "HideGroupInOutlook",
        "SubscribeMembersToCalendarEventsDisabled",
        "WelcomeEmailDisabled"
      ],
      "resourceProvisioningOptions": [
        "Team"
      ],
      "securityEnabled": false,
      "securityIdentifier": "S-1-12-1-2062584438-1243415038-3531907519-3718009013",
      "visibility": "Public",
      "onPremisesProvisioningErrors": []
    }
  ]
}

Get Channels for Team

This action returns all the channels associated with a team.

Regular expressions used by this action are Python specific.

Input
Name Type Default Required Description Enum Example
channel_name string None False Optional regex-capable channel to look for None None
team_name string None True Team name to look for None None

Example input:

{
  "channel_name": "Komand Test Channel",
  "team_name": "Komand-Test-Everyone"
}
Output
Name Type Required Description
channels []channel False Array of channels

Example output:

{
  "channels": [
    {
      "id": "XXXXXXXXXXX",
      "displayName": "test123",
      "description": "komand rocks!",
      "webUrl": "https://teams.microsoft.com/l/channel/19%3a0a48f53ea9484091aba13271dc418c2a%40thread.skype/test123?groupId=d2cc6aa2-8071-44d9-a97a-0a758da420a8&tenantId=5c824599-dc8c-4d31-96fb-3b886d4f8f10",
      "membershipType": "standard"
    }
  ]
}

Add Member to Team

This action is used to add a member to a team.

Input
Name Type Default Required Description Enum Example
member_login string None True Member login e.g. user@example.com None None
team_name string None True Team name None None

Example input:

{
  "member_login": "user@example.com",
  "team_name": "ICON-Test-Everyone"
}
Output
Name Type Required Description
success boolean True Boolean indicating if this action was successful

Example output:

{
  "success": true
}

Add Channel to Team

This action is used to add a channel to a team.

Input
Name Type Default Required Description Enum Example
channel_description string None True Channel description None None
channel_name string None True Channel name None None
team_name string None True Team name None None

Example input:

{
  "channel_description": "This is a test channel.",
  "channel_name": "test_channel",
  "team_name": "ICON-Test-Everyone"
}
Output
Name Type Required Description
success boolean True Boolean indicating if this action was successful

Example output:

{
  "success": true
}

Remove Channel from Team

This action is used to remove a channel from a team.

Input
Name Type Default Required Description Enum Example
channel_name string None True Channel name None None
team_name string None True Team name None None

Example input:

{
  "channel_name": "test_channel",
  "team_name": "ICON-Test-Everyone"
}
Output
Name Type Required Description
success boolean True Boolean indicating if this action was successful

Example output:

{
  "success": true
}

Remove Member from Team

This action is used to remove a member from a team.

Input
Name Type Default Required Description Enum Example
member_login string None True Member Login e.g. user@example.com None None
team_name string None True Team name None None

Example input:

{
  "member_login": "user@example.com",
  "team_name": "Komand-Test-Everyone"
}
Output
Name Type Required Description
success boolean True Boolean indicating if this action was successful

Example output:

{
  "success": true
}

Create Teams Enabled Group

This action is used to create a group in Azure and enable it for Microsoft Teams.

Input
Name Type Default Required Description Enum Example
group_description string None True Group description None None
group_name string None True Team name None None
mail_enabled boolean None True Should e-mail should be enabled for this group None None
mail_nickname string None True The nickname for the email address of this group in Outlook None None
members string[] None False A list of usernames to set as members None None
owners string[] None False A list of usernames to set as owners None None

Example input:

  "group_description": "A test group",
  "group_name": "test_group",
  "mail_enabled": false,
  "mail_nickname": "TestGroup",
  "members": "['user@example.com']",
  "owners": "['user@example.com']"
Output
Name Type Required Description
group group False Information about the group that was created

Example output:

{
  "group": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "xxxxx-xxxx-xxx-xxxxx",
    "createdDateTime": "2019-11-05T19:34:21Z",
    "creationOptions": [],
    "description": "Superheros",
    "displayName": "Avengers",
    "groupTypes": [
      "Unified"
    ],
    "mail": "user@example.com",
    "mailEnabled": true,
    "mailNickname": "CMDTestDeleteMe",
    "proxyAddresses": [
      "SMTP:XXXXXXXXX"
    ],
    "renewedDateTime": "2019-11-05T19:34:21Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "xxxx-xxxx-xxxx-xxxx",
    "visibility": "Public",
    "onPremisesProvisioningErrors": []
  }
}

Delete Team

This action is used to delete a team and the associated group from Azure.

Input
Name Type Default Required Description Enum Example
team_name string None True Team Name None None

Example input:

{
  "team_name": "Test Team"
}
Output
Name Type Required Description
success boolean True Boolean indicating if this action was successful

Example output:

{
  "success": true
}

Triggers

New Message Received

This trigger is used to poll a channel for new messages.

Regular expressions used by this trigger are Python specific.

Input
Name Type Default Required Description Enum Example
channel_name string None True Channel None None
message_content string None False Regex to match new messages against None None
team_name string None True Team name None None

Example input:

{
  "channel_name": "ICON Test Channel",
  "message_content": "[Tt]est",
  "team_name": "ICON-Test-Everyone"
}
Output
Name Type Required Description
message message False The message object that was created

Example output:

{
  "message": {
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('xxxx')/channels('xxxxxxx')/messages/$entity",
    "id": "1571769574238",
    "etag": "1571769574238",
    "messageType": "message",
    "createdDateTime": "2019-10-22T18:39:34.238Z",
    "importance": "normal",
    "locale": "en-us",
    "webUrl": "https://teams.microsoft.com/l/message/xxxxxxxxxxxxxx/xxxxxx?groupId=xxxxx",
    "from": {
      "user": {
        "id": "xxxxxxx",
        "displayName": "Test User",
        "userIdentityType": "aadUser"
      }
    },
    "body": {
      "contentType": "text",
      "content": "Hello from InsightConnect!"
    },
    "attachments": [],
    "mentions": [],
    "reactions": []
  }
}

Custom Output Types

This plugin does not contain any custom output types.

Troubleshooting

This plugin does not contain any troubleshooting information.

Version History

  • 2.0.3 - Add docs_url to plugin spec with link to plugin setup guide
  • 2.0.2 - Fix issue where unexpected HTML messages would not trigger workflows
  • 2.0.1 - Update to Get Teams action to support more than 20 teams
  • 2.0.0 - Fix issue where send message would not work if there were too many teams | Removed regex capability for team and channel inputs which will speed up Send Message and Send HTML Message actions
  • 1.3.0 - New action Send Message by GUID
  • 1.2.3 - New spec and help.md format for the Extension Library
  • 1.2.2 - Fix issue where regular expressions would only match at the beginning of a string
  • 1.2.1 - Fix issue where New Message Received trigger could receive an unauthorized error after sustained use
  • 1.2.0 - New actions Add Member to Team, Remove Member from Team, Create Teams Enabled Group, Delete Team, Add Channel to Team, and Remove Channel from Team
  • 1.1.0 - New trigger New Message Received | New action Send HTML Message
  • 1.0.1 - Fix issue where improper exception could be raised
  • 1.0.0 - Initial plugin

Links

References

plugin_spec_version: v2
extension: plugin
products: [insightconnect]
name: microsoft_teams
title: Microsoft Teams
description: 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
version: 2.0.3
vendor: rapid7
support: community
status: []
resources:
  source_url: https://github.com/rapid7/insightconnect-plugins/tree/master/microsoft_teams
  license_url: https://github.com/rapid7/insightconnect-plugins/blob/master/LICENSE
  vendor_url: https://www.microsoft.com
  docs_url: https://insightconnect.help.rapid7.com/docs/microsoft-teams
tags:
- microsoft
- teams
- office 365
- chat
hub_tags:
  use_cases: [alerting_and_notifications, application_management, threat_detection_and_response, user_management]
  keywords: [microsoft, teams, office 365, chat]
  features: []
types:
  team:
    displayName:
        title: "Display Name"
        type: string
        description: "Display name"
        required: false
    id:
        title: "ID"
        type: string
        description: "ID"
        required: false
    description:
        title: "Description"
        type: string
        description: "Description"
        required: false
  channel:
    displayName:
      title: "Display Name"
      type: string
      description: "Display name"
      required: false
    id:
      title: "ID"
      type: string
      description: "ID"
      required: false
    description:
      title: "Description"
      type: string
      description: "Description"
      required: false
  body:
    content:
      title: "Content"
      type: string
      description: "Content"
      required: false
    contentType:
      title: "Content Type"
      type: string
      description: "Content type"
      required: false
  user:
    displayName:
      title: "Display name"
      type: string
      description: "Display name"
      required: false
    id:
      title: "ID"
      type: string
      description: "ID"
      required: false
  from:
    user:
      title: "User"
      type: user
      description: "User"
      required: false
  message:
     body:
       title: "Body"
       type: body
       description: "Body"
       required: false
     from:
       title: "From"
       type: from
       description: "From"
       required: false
     createdDateTime:
       title: "Created Date Time"
       type: string
       description: "Created date time"
       required: false
     webUrl:
       title: "Web URL"
       type: string
       description: "Web URL"
       required: false
     importance:
       title: "Importance"
       type: string
       description: "Importance"
       required: false
     messageType:
       title: "Message Type"
       type: string
       description: "Message type"
       required: false
     locale:
       title: "Locale"
       type: string
       description: "Locale"
       required: false
     id:
       title: "ID"
       type: string
       description: "ID"
       required: false
  group:
      mailNickname:
        title: "Mail Nickname"
        type: string
        description: "Mail nickname"
        required: false
      id:
        title: "ID"
        type: string
        description: "ID"
        required: false
      mail:
        title: "Mail"
        type: string
        description: "Mail"
        required: false
      description:
        title: "Description"
        type: string
        description: "Description"
        required: false
      securityEnabled:
        title: "Security Enabled"
        type: boolean
        description: "Security enabled"
        required: false
      displayName:
        title: "Display Name"
        type: string
        description: "Display name"
        required: false
      createdDateTime:
        title: "Created Date Time"
        type: string
        description: "Created date time"
        required: false
      mailEnabled:
        title: "Mail Enabled"
        type: boolean
        description: "Mail enabled"
        required: false

connection:
  application_id:
    title: Application ID
    description: Application (client) ID
    type: string
    required: true
  directory_id:
    title: Directory ID
    description: Directory (tenant) ID
    type: string
    required: true
  application_secret:
    title: Application Secret
    description: Application secret
    type: credential_secret_key
    required: true
  username_password:
    type: credential_username_password
    title: "Credentials"
    description: "Username and password"
    required: true

triggers:
  new_message_received:
    title: New Message Received
    description: Poll a channel for new messages
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Channel
        type: string
        required: true
        order: 2
      message_content:
        title: Message Content
        description: Regex to match new messages against
        type: string
        required: false
        order: 3
    output:
      message:
        title: Message
        description: The message object that was created
        type: message
        required: false

actions:
  get_teams:
    title: Get Teams
    description: Returns all the teams the configured user is allowed to see
    input:
      team_name:
        title: Team Name
        description: Optional regex-capable team name to look for
        type: string
        required: false
    output:
      teams:
        title: Teams
        description: Array of team objects
        type: "[]team"
        required: false
  get_channels_for_team:
    title: Get Channels for Team
    description: Returns all the channels associated with a team
    input:
      team_name:
        title: Team Name
        description: Team name to look for
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Optional regex-capable channel to look for
        type: string
        required: false
        order: 2
    output:
      channels:
        title: Channels
        description: Array of channels
        type: "[]channel"
        required: false
  send_message:
    title: Send Message
    description: Send a message
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Channel
        type: string
        required: true
        order: 2
      message:
        title: Message
        description: Message to send
        type: string
        required: true
        order: 3
    output:
      message:
        title: Message
        description: The message object that was created
        type: message
        required: false
  send_message_by_guid:
    title: Send Message by GUID
    description: Sends a message using the GUID for the team and channel. This is more performant than send message
    input:
      team_guid:
        title: Team GUID
        description: Team GUID
        type: string
        required: true
        order: 1
      channel_guid:
        title: Channel GUID
        description: Channel GUID
        type: string
        required: true
        order: 2
      is_html:
        title: Is HTML
        description: Is the message HTML
        type: boolean
        required: true
        order: 3
      message:
        title: Message
        description: Message to send
        type: string
        required: true
        order: 4
    output:
      message:
        title: Message
        description: The message object that was created
        type: message
        required: false
  send_html_message:
    title: Send HTML Message
    description: Send HTML as a message
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Channel name
        type: string
        required: true
        order: 2
      message_content:
        title: Message Content
        description: HTML content to send
        type: string
        required: true
        order: 3
    output:
      message:
        title: Message
        description: The message object that was created
        type: message
        required: false
  add_member_to_team:
    title: Add Member to Team
    description: Add a member to a team
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      member_login:
        title: Member Login
        description: Member login e.g. user@example.com
        type: string
        required: true
        order: 2
    output:
      success:
        title: Success
        description: Boolean indicating if this action was successful
        type: boolean
        required: true
  remove_member_from_team:
    title: Remove Member from Team
    description: Remove a member from a team
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      member_login:
        title: Member Login
        description: Member Login e.g. user@example.com
        type: string
        required: true
        order: 2
    output:
      success:
        title: Success
        description: Boolean indicating if this action was successful
        type: boolean
        required: true
  add_channel_to_team:
    title: Add Channel to Team
    description: Add a channel to a team
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Channel name
        type: string
        required: true
        order: 2
      channel_description:
        title: Channel Description
        description: Channel description
        type: string
        required: true
        order: 3
    output:
      success:
        title: Success
        description: Boolean indicating if this action was successful
        type: boolean
        required: true
  remove_channel_from_team:
    title: Remove Channel from Team
    description: Remove a channel from a team
    input:
      team_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Channel name
        type: string
        required: true
        order: 2
    output:
      success:
        title: Success
        description: Boolean indicating if this action was successful
        type: boolean
        required: true
  create_teams_enabled_group:
    title: Create Teams Enabled Group
    description: Create a group in Azure and enable it for Microsoft Teams
    input:
      group_name:
        title: Team Name
        description: Team name
        type: string
        required: true
        order: 1
      group_description:
        title: Group Description
        description: Group description
        type: string
        required: true
        order: 2
      mail_nickname:
        title: Mail Nickname
        description: The nickname for the email address of this group in Outlook
        type: string
        required: true
        order: 3
      mail_enabled:
        title: Mail Enabled
        description: Should e-mail should be enabled for this group
        type: boolean
        required: true
        order: 4
      owners:
        title: Owners
        description: A list of usernames to set as owners
        type: "string[]"
        required: false
        order: 5
      members:
        title: Members
        description: A list of usernames to set as members
        type: "string[]"
        required: false
        order: 6
    output:
      group:
        title: Group
        description: Information about the group that was created
        type: group
        required: false
  delete_team:
    title: Delete Team
    description: Delete a team and the associated group from Azure
    input:
      team_name:
        title: Team Name
        description: Team Name
        type: string
        required: true
    output:
      success:
        title: Success
        description: Boolean indicating if this action was successful
        type: boolean
        required: true


Other plugins
Check Point NGFW
Rapid7   |   v2.0.1
Plugin
Get
Cb Response
Rapid7   |   v3.1.9
Plugin
Get
Fortinet FortiGate
Rapid7   |   v4.0.0
Plugin
Get
Palo Alto Firewall
Rapid7   |   v6.0.0
Plugin
Get
SentinelOne
Rapid7   |   v1.2.1
Plugin
Get