InsightConnect Marketplace

Microsoft Teams

Back to Marketplace

Microsoft Teams

v1.3.0

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
application_id string None True Application (client) ID None
application_secret credential_secret_key None True Application secret None
directory_id string None True Directory (tenant) ID None
username_password credential_username_password None True Username and password None

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
channel_name string None True Regex-capable channel None
message string None True Message to send None
team_name string None True Regex-capable team name None
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
channel_name string None True Regex-capable channel None
message_content string None True HTML content to send None
team_name string None True Regex-capable team name None
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
channel_guid string None true Channel GUID None
is_html boolean None true Is the message HTML None
message string None true Message to send None
team_guid string None true Team GUID None
Output
Name Type Default Required Description Enum
message message None 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
team_name string None False Optional regex-capable optional team name to look for None
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
channel_name string None False Optional regex-capable optional channel to look for None
team_name string None True Regex-capable team name to look for None
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
member_login string None False Member Login e.g. user@example.com None
team_name string None True Team Name None
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
channel_description string None True Channel description None
channel_name string None True Channel name None
team_name string None True Team name None
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
channel_name string None True Channel name None
team_name string None True Team name None
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
member_login string None False Member Login e.g. user@example.com None
team_name string None True Team Name None
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
group_description string None True Group Description None
group_name string None True Team name None
mail_enabled boolean None False should e-mail should be enabled for this group None
mail_nickname string None True The nickname for the email address of this group in Outlook None
members string[] None False A list of usernames to set as members None
owners string[] None False A list of usernames to set as owners None
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
team_name string None True Team Name None
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
channel_name string None True Regex-capable channel None
message_content string None False Regex to match new messages against None
team_name string None True Regex-capable team name None
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

  • 1.3.0 - New action Send Message by GUID
  • 1.2.3 - New spec and help.md format for the Hub
  • 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: 1.3.0
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
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: Regex-capable team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Regex-capable 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 optional 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: Regex-capable team name to look for
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Optional regex-capable optional 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: Regex-capable team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Regex-capable 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: Regex-capable team name
        type: string
        required: true
        order: 1
      channel_name:
        title: Channel Name
        description: Regex-capable channel
        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
Cisco AMP for Endpoints
Rapid7   |   v2.0.0
Plugin
Get
Mimecast
Rapid7   |   v4.0.0
Plugin
Get
Jamf
Rapid7   |   v1.1.1
Plugin
Get
LastPass Enterprise
Rapid7   |   v1.0.2
Plugin
Get
Komand
Rapid7   |   v1.0.3
Plugin
Get