Skip to main content

Microsoft Teams

This Integration is part of the Microsoft Teams Pack.#

Use the Microsoft Teams integration to send messages and notifications to your team members and create meetings. This integration was integrated and tested with version 1.0 of Microsoft Teams.

Note:

  • This integration is supported in Cortex XSOAR 8 and up and Cortex XSIAM without using an engine.
  • The integration has the ability to run built-in Cortex XSOAR commands, through a mirrored channel. Make sure to pass the command in the chat exactly as typed in the CORTEX XSOAR CLI. For example: !DeleteContext all=yes. Use the command mirror-investigation to mirror/create a mirrored channel.
  • For use cases where it is only needed to send messages to a specific channel, we recommend checking the Microsoft Teams via Webhook Integration, which has a simpler setup.

Integration Architecture#

Data is passed between Microsoft Teams and Cortex XSOAR through the bot that you will configure in Microsoft Teams. A webhook (that you will configure) receives the data from Teams and passes it to the messaging endpoint. The web server on which the integration runs in Cortex XSOAR listens to the messaging endpoint and processes the data from Teams. You can use an engine for communication between Teams and the Cortex XSOAR server. In order to mirror messages from Teams to Cortex XSOAR, the bot must be mentioned, using the @ symbol, in the message.

The web server for the integration runs within a long-running Docker container. Cortex XSOAR maps the Docker port to which the server listens, to the host port (to which Teams posts messages). For more information, see our documentation and Docker documentation.

Protocol Diagram#

image

Important Information#

  • The messaging endpoint must be one of the following:
    • the URL of the Cortex XSOAR server, including the configured port
    • the Cortex XSOAR rerouting URL that you've defined for your Microsoft Teams instance (see the Using Cortex XSOAR or Cortex XSIAM rerouting section for more details)
    • a proxy that redirects the messages received from Teams to the Cortex XSOAR or Cortex XSIAM server (see the Using NGINX as reverse proxy section for more details)
  • Microsoft Teams will send events to the messaging endpoints via HTTPS request, which means the messaging endpoint must be accessible for Microsoft Teams to reach to it. As follows, the messaging endpoint can not contain private IP address or any DNS that will block the request from Microsoft Teams. In order to verify that the messaging endpoint is open as expected, you can surf to the messaging endpoint from a browser in an environment which is disconnected from the Cortex XSOAR environment.
  • It's important that the port is opened for outside communication and that the port is not being used, meaning that no service is listening on it. Therefore, the default port, 443, should not be used.
  • For additional security, we recommend placing the Teams integration web server behind a reverse proxy (such as NGINX).
  • By default, the web server that the integration starts provides services in HTTP. For communication to be in HTTPS you need to provide a certificate and private key in the following format:
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----
  • You must not set a certificate and/or private key if you are using the Cortex XSOAR rerouting setup.
  • Microsoft does not support self-signed certificates and requires a chain-trusted certificate issued by a trusted CA. In order to verify which certificate is used, run the following (replace {MESSAGING-ENDPOINT} with the messaging endpoint):
    curl {MESSAGING-ENDPOINT} -vI
    Make sure the output does not contain the following:
    curl: (60) SSL certificate problem: self signed certificate
  • The following domains are used by this integration:
    - microsoft.com
    - botframework.com
    - microsoftonline.com
    When installing the bot in Microsoft Teams, according to Microsoft, it usually takes up to 3-5 business days for the app to reflect in the "built for your org" section.

Migration from Cortex XSOAR 6 to Cortex XSOAR 8 and Cortex XSIAM.#

Using Cortex XSOAR or Cortex XSIAM rerouting#

  1. For Cortex XSOAR 8, set the messaging endpoint in the Azure bot to be https://ext-<CORTEXT-XSOAR-SERVER-ADDRESSS>/xsoar/instance/execute/<INTEGRATION-INSTANCE-NAME>, e.g., https://ext-my.demisto.live/xsoar/instance/execute/teams.
  2. For Cortex XSIAM, set the messaging endpoint in the Azure bot to be https://ext-<CORTEXT-XSIAM-SERVER-ADDRESSS>/xsoar/instance/execute/<INTEGRATION-INSTANCE-NAME>, and replace the xdr in the url to crtx.
  3. Check the long running instance parameter in the integration instance configuration.
  4. Set the port parameter. It's under the Connect section in the integration instance configuration.
  5. If using the same bot from the XSOAR 6 instance, make sure to remove the bot from the team and to add it back: a. Go to the Microsoft Teams app. b. Go to your team, and click the three dots next to the name. c. Go to manage team > apps. d. Find your bot, and click the three dots in the same row. e. Click remove. f. Add the bot to the team.

Setup Examples#

1. Using Cortex XSOAR or Cortex XSIAM rerouting#

In this configuration, we will use Cortex XSOAR/Cortex XSIAM functionality, which reroutes HTTPS requests that hit the default port (443) to the web server that the integration spins up.

The messaging endpoint needs to be:

For Cortex XSOAR version 6.x: <CORTEX-XSOAR-URL>/instance/execute/<INTEGRATION-INSTANCE-NAME>, e.g., https://my.demisto.live/instance/execute/teams.

For Cortex XSOAR version 8 and Cortex XSIAM: https://ext-<CORTEXT-XSOAR-SERVER-ADDRESSS>/xsoar/instance/execute/<INTEGRATION-INSTANCE-NAME>, e.g., https://ext-my.demisto.live/xsoar/instance/execute/teams.

The integration instance name, teams in this example, needs to be configured in the Configure Microsoft Teams on Cortex XSOAR step. Make sure to set the instance name in all lowercase letters and as one word.

The port to be configured in Configure Microsoft Teams on Cortex XSOAR step should be any available port that is not used by another service.

In addition, make sure Instance execute external is enabled (for Cortex XSOAR 6.x).

  1. In Cortex XSOAR, go to Settings > About > Troubleshooting.
  2. In the Server Configuration section, verify that the instance.execute.external.\<INTEGRATION-INSTANCE-NAME> (instance.execute.external.teams in this example) key is set to true. If this key does not exist, click + Add Server Configuration and add the instance.execute.external.\<INTEGRATION-INSTANCE-NAME> and set the value to true. See the following reference article for further information.

2. Using NGINX as reverse proxy#

In this configuration, the inbound connection, from Microsoft Teams to Cortex XSOAR/Cortex XSIAM, goes through a reverse proxy (e.g., NGINX) which relays the HTTPS requests posted from Microsoft Teams to the Cortex XSOAR/Cortex XSIAM server on HTTP.

On NGINX, configure the following:

  • SSL certificate under ssl_certificate and ssl_certificate_key
  • The Cortex XSOAR server (including the port) under proxy_pass, e.g. http://mydemistoinstance.com:7000

Follow Configuring Upstream Servers NGINX guide for more details.

The port (7000 in this example), to which the reverse proxy should forward the traffic on HTTP, should be the same port you specify in the integration instance configuration, as the web server the integration spins up, listens on that port.

image

image

3. Using Apache reverse proxy and Cortex XSOAR engine#

In this configuration, the inbound connection, from Microsoft Teams to Cortex XSOAR/Cortex XSIAM, goes through a reverse proxy (e.g., Apache) and possibly a load balancer, which relays the HTTPS requests posted from Microsoft Teams to a Cortex XSOAR/Cortex XSIAM engine, which can be put in a DMZ, on HTTP.

The port (7000 in this example), to which the reverse proxy should forward the traffic on HTTP, should be the same port you specify in the integration instance configuration, as the web server the integration spins up, listens on that port.

image

image

4. Using Cloudflare#

In this configuration, we will use Cloudflare proxy.

The messaging endpoint should be the Cortex XSOAR/Cortex XSIAM URL, which needs to be hosted on Cloudflare, with the port to which Cloudflare proxy directs the HTTPS traffic, e.g., https://mysite.com:8443

In the Configure Microsoft Teams on Cortex XSOAR step, the following need to be configured:

  • The port selected above.
  • A certificate and key for configuring HTTPS web server. This certificate can be self-signed.

The proxy intercepts HTTPS traffic, presents a public CA certificate, then proxies it to the web server.

All HTTPS traffic that will hit the selected messaging endpoint will be directed to the HTTPS web server the integration spins up, and will then be processed.

Setup Video#

The information in this video is for Cortex XSOAR 6 only.

Old Setup Video (Use the above video)#

Prerequisites#

Before you can create an instance of the Microsoft Teams integration in Cortex XSOAR/Cortex XSIAM, you need to complete the following procedures.

  1. Create the Demisto Bot in Microsoft Teams
  2. Grant the Demisto Bot Permissions in Microsoft Graph
  3. Configure Microsoft Teams on Cortex XSOAR or Cortex XSIAM
  4. Add the Demisto Bot to a Team

Create the Demisto Bot in Microsoft Teams#

Creating the Demisto Bot using Microsoft Azure Portal#

  1. Navigate to the Create an Azure Bot page.
  2. In the Bot Handle field, type Demisto Bot.
  3. Fill in the required Subscription and Resource Group, relevant links: Subscription, Resource Groups.
  4. For Type of App, select Multi Tenant.
  5. For Creation type, select Create new Microsoft App ID for Creation Type if you don't already have an app registration, otherwise, select Use existing app registration, and fill in you App ID.
  6. Click Review + Create, and wait for the validation to pass.
  7. Click create if the validation has passed, and wait for the deployment to finish.
  8. Under Next Steps, click Go to resource.
  9. Navigate to Configuration on the left bar, and fill in the Messaging Endpoint.
  10. Store the Microsoft App ID value for the next steps, and navigate to Manage next to it.
  11. Click New Client Secret, fill in the Description and Expires fields as desired. Then click Add.
  12. Copy the client secret from the value field and store it for the next steps.
  13. Go back to the previous page, and navigate to Channels in the left bar.
  14. Click Microsoft Teams under Available Channels, click the checkbox, click Agree, then click Apply.

Note: in step 5, if you choose Use existing app registration, make sure to delete the previous created bot with the same app id, remove it from the team it was added to as well.

Grant the Demisto Bot Permissions in Microsoft Graph#

In order to connect to Microsoft Teams use one of the following authentication methods:

  1. Client Credentials Flow
  2. Authorization Code Flow
Client Credentials Flow#

Note: The chat commands are only supported when using the Authorization Code flow.

  1. Go to your Microsoft Azure portal, and from the left navigation pane select Azure Active Directory > App registrations.
  2. Search for and click Demisto Bot.
  3. Click API permissions > Add a permission > Microsoft Graph > Application permissions.
  4. For the following permissions, search for the permission, select the checkbox, and click Add permissions.
  • User.Read.All
  • Group.ReadWrite.All
  • Calls.Initiate.All
  • Calls.InitiateGroupCall.All
  • OnlineMeetings.ReadWrite.All
  • ChannelMember.ReadWrite.All
  • Channel.Create
  1. Verify that all permissions were added, and click Grant admin consent for Demisto.
  2. When prompted to verify granting permissions, click Yes, and verify that permissions were successfully added.

Authorization Code Flow#

Note: The microsoft-teams-ring-user command is only supported when using the Client Credentials flow due to a limitation in Microsoft's permissions system.

  1. Go to your Microsoft Azure portal, and from the left navigation pane select Azure Active Directory > App registrations.

  2. Search for and click Demisto Bot.

  3. Click API permissions > Add a permission > Microsoft Graph > Application permissions.

  4. For the following permissions, search for the permission, select the checkbox and click Add permissions.

    Required Application Permissions:#
    • User.Read.All
    • Group.ReadWrite.All
    • OnlineMeetings.ReadWrite.All
    • ChannelMember.ReadWrite.All
    • Channel.Create
    • Chat.Create
    • TeamsAppInstallation.ReadWriteSelfForChat.All
    • TeamsAppInstallation.ReadWriteForChat.All
    • AppCatalog.Read.All
    Required Delegated Permissions:#
    • OnlineMeetings.ReadWrite
    • ChannelMessage.Send
    • Chat.ReadWrite
    • ChatMessage.Send
    • Group.ReadWrite.All
    • Channel.Create
    • ChannelSettings.ReadWrite.All
    • ChatMember.ReadWrite
    • Chat.Create
    • TeamsAppInstallation.ReadWriteForChat
    • TeamsAppInstallation.ReadWriteSelfForChat
    • User.Read.All
    • AppCatalog.Read.All
  5. Verify that all permissions were added, and click Grant admin consent for Demisto.

  6. When prompted to verify granting permissions, click Yes, and verify that permissions were successfully added.

  7. Click Expose an API and add Application ID URI

  8. Click Expose an API > Add a scope >

    • Chat.ReadWrite
    • ChatMessage.Send
    • ChannelSettings.ReadWrite.All
    • ChannelMember.Read.All
  9. Click Authentication > Platform configurations > Add a platform. Choose Web and add Redirect URIs: https://login.microsoftonline.com/common/oauth2/nativeclient

Configure Microsoft Teams on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for Microsoft Teams.

  3. Click Add instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    NameThe integration instance name.
    If using Cortex XSOAR rerouting configuration, insert here the instance name you configured in the messaging endpoint.
    True
    Bot IDBot ID.True
    Bot PasswordBot Password.True
    Authentication TypeTrue
    Application redirect URI (for Authorization Code mode)False
    Authorization codeFor Authorization Code flow mode. Received from the authorization step. See the Detailed Instructions (?) sectionFalse
    Default teamThe team to which messages and notifications are sent. If a team is specified as a command argument, it overrides this parameter.True
    Notifications channelTrue
    Certificate (Required for HTTPS)False
    Private Key (Required for HTTPS)False
    Minimum incident severity to send notifications to Teams byFalse
    Disable Automatic NotificationsWhether to disable automatic notifications to the configured notifications channel.False
    Allow external users to create incidents via direct messageFalse
    The header of an external form hyperlink.False
    Trust any certificate (not secure)Do not check for Cortex XSOAR version 8 and Cortex XSIAM.False
    Use system proxy settingsFalse
    Long running instanceTrue
    Listen port, e.g., 7000 (Required for investigation mirroring and direct messages)longRunningPortFalse
    Incident typeIncident type.False
  4. Click Test to validate the URLs, token, and connection.

  5. Click the Save & exit button.

Configuring the instance with the chosen authentication flow#

Authentication Using the Client Credentials Flow#
  1. Choose the 'Client Credentials' option in the Authentication Type parameter.
  2. Enter your Client/Application ID in the Bot ID parameter.
  3. Enter your Client Secret in the Bot Password parameter.
  4. Save the instance.
  5. Click Test to validate the URLs, token, and connection.
  6. Add the Demisto Bot to a Team
Authentication Using the Authorization Code Flow#
  1. Choose the 'Authorization Code' option in the Authentication Type parameter.
  2. Enter your Client/Application ID in the Bot ID parameter.
  3. Enter your Client Secret in the Bot Password parameter.
  4. Enter your Application redirect URI in the Application redirect URI parameter.
  5. Save the instance.
  6. Add the Demisto Bot to a Team
  7. Run the !microsoft-teams-generate-login-url command in the War Room and follow the instructions.
  8. Save the instance.
  9. Run the !microsoft-teams-auth-test command. A 'Success' message should be printed to the War Room.

Add the Demisto Bot to a Team#

Notes:

  • The following needs to be done after configuring the integration on Cortex XSOAR/Cortex XSIAM (the previous step).
  • According to Microsoft it usually takes up to 3-5 business days for the app to reflect in the "built for your org" section.
  1. Download the ZIP file located at the bottom of this article.
  2. Uncompress the ZIP file. You should see 3 files (manifest.json, color.png and outline.png).
  3. Open the manifest.json file that was extracted from the ZIP file.
  4. In the id, replace the value of the attribute with the value of the Bot ID from step 5 of the Create the Demisto Bot in Microsoft Teams section.
  5. In the bots list, replace the value of the botId attribute with the value of the Bot ID from step 5 of the Create the Demisto Bot in Microsoft Teams section.
  6. In the webApplicationInfo, replace the value of id attribute with the value of the Bot ID from step 5 of the Create the Demisto Bot in Microsoft Teams section.
  7. Compress the 3 files (the modified manifest.json file, color.png and outline.png).
  8. Navigate to Manage Apps in the Microsoft Teams admin center.
  9. Click the +Upload button.
  10. In the pop-up window, click the Upload button.
  11. Browse for the ZIP file you created in step 5, open it, and wait a few seconds until it loads.
  12. Search for Demisto Bot.
  13. In the line where Demisto Bot shows under Name, tick the V on the left.
  14. Click the Add to team button.
  15. In the search box, type the name of the team to which you want to add the bot.
  16. Click the Add button on the wanted team and then click the Apply button.

Known Limitations#


  • In some cases, you might encounter a problem, where no communication is created between Teams and the messaging endpoint, when adding a bot to the team. You can work around this problem by adding any member to the team the bot was added to. It will trigger a communication and solve the issue.
  • The microsoft-teams-ring-user command is only supported when using the Client Credentials flow due to a limitation in Microsoft's permissions system.
  • In addition, the chat commands are only supported when using the Authorization Code flow.
  • Posting a message or adaptive card to a private/shared channel is currently not supported in the send-notification command. Thus, also the mirror_investigation command does not support private/shared channels. For more information, see Microsoft General known issues and limitations.
  • In case of multiple chats/users sharing the same name, the first one will be taken.
  • See Microsoft documentation for Limits and specifications for Microsoft Teams.
  • If a non-Cortex XSOAR user ran the new incident command in the chat with the bot, the owner of the created incident would be the logged in Cortex XSOAR user, not the external user who ran the command.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

send-notification#


Sends a message to the specified teams. To mention a user in the message, add a semicolon ";" at the end of the user mention. For example: @Bruce Willis;

Base Command#

send-notification

Required Permissions#

Group.ReadWrite.All

Input#
Argument NameDescriptionRequired
channelThe channel to which to send messages. Supports only standard channels.Optional
messageThe message to send to the channel or team member.Optional
team_memberDisplay name or email address of the team member to send the message to.Optional
teamThe team in which the specified channel exists. The team must already exist, and this value will override the default channel configured in the integration parameters.Optional
adaptive_cardThe Microsoft Teams adaptive card to send.Optional
toThe team member to which to send the message.Optional
external_form_url_headerThe header of an external form hyperlink.message.Optional
Context Output#

There is no context output for this command.

Command Example#

!send-notification channel=General message="hello world!" team=DemistoTeam

Human Readable Output#

Message was sent successfully.

mirror-investigation#


Mirrors the Cortex XSOAR/Cortex XSIAM investigation to the specified Microsoft Teams channel. Supports only standard channels.

Note: Mirrored channels could be used to run Cortex XSOAR/Cortex XSIAM built-in commands.

Base Command#

mirror-investigation

Required Permissions#

Group.ReadWrite.All

Input#
Argument NameDescriptionRequired
mirror_typeThe mirroring type. Can be "all", which mirrors everything, "chat", which mirrors only chats (not commands), or "none", which stops all mirroring. Possible values are: all, chat, none. Default is all.Optional
autocloseWhether to auto-close the channel when the incident is closed in Cortex XSOAR. If "true", the channel will be auto-closed. Possible values are: true, false. Default is true.Optional
directionThe mirroring direction. Possible values are: Both, FromDemisto, ToDemisto. Default is both.Optional
teamThe team in which to mirror the Cortex XSOAR investigation. If not specified, the default team configured in the integration parameters will be used.Optional
channel_nameThe name of the channel. The default is "incident-INCIDENTID".Optional
Context Output#

There is no context output for this command.

Command Example#

!mirror-investigation mirror_type=all autoclose=true direction=Both

Human Readable Output#

Investigation mirrored successfully in channel incident-100.

close-channel#


Deletes the specified Microsoft Teams channel.

Base Command#

close-channel

Required Permissions#

Group.ReadWrite.All

Input#
Argument NameDescriptionRequired
channelThe name of the channel to close.Optional
teamThe channel's team.Optional
Context Output#

There is no context output for this command.

Command Example#

!close-channel channel="example channel"

Human Readable Output#

Channel was successfully closed.

microsoft-teams-integration-health#


Returns real-time and historical data on the integration status.

Base Command#

microsoft-teams-integration-health

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-integration-health

Human Readable Output#

Microsoft API Health#

Bot Framework API HealthGraph API Health
OperationalOperational

No mirrored channels.

microsoft-teams-ring-user#


Rings a user's Teams account. Note: This is a ring only! no media will play in case the generated call is answered. To use this make sure your Bot has the following permissions - Calls.Initiate.All and Calls.InitiateGroupCall.All

Base Command#

microsoft-teams-ring-user

Required Permissions#

Calls.Initiate.All Calls.InitiateGroupCall.All

Input#
Argument NameDescriptionRequired
usernameThe display name of the member to call.Required
Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-ring-user username="Avishai Brandeis"

Human Readable Output#

Calling Avishai Brandeis

microsoft-teams-add-user-to-channel#


Adds a member (user) to a private/shared channel. For a comparison of Teams features for each channel type, see the Microsoft documentation: Channel feature comparison.

Base Command#

microsoft-teams-add-user-to-channel

Required Permissions#

User.Read.All ChannelMember.ReadWrite.All

Input#
Argument NameDescriptionRequired
channelThe channel to which to add the member.Required
teamThe channel's team.Required
memberThe display name of the member to add to the channel.Required
ownerWhether to add the member with the owner role. Default is 'false'Optional
Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-add-user-to-channel channel="example channel" member=itayadmin team=DemistoTeam

Human Readable Output#

The User "itayadmin" has been added to channel "example channel" successfully.

microsoft-teams-create-channel#


Creates a new channel in a Microsoft Teams team. For more information about the channels types, see the Microsoft documentation: standard, private, or shared channels See also Channel feature comparison.

Base Command#

microsoft-teams-create-channel

Required Permissions#

Group.ReadWrite.All Channel.Create

Input#
Argument NameDescriptionRequired
channel_nameThe name of the channel.Required
descriptionThe description of the channel.Optional
teamThe team in which to create the channel.Required
membership_typeThe type of the channel. Possible values are: private, standard, shared. Default is standard.Optional
owner_userThe channel owner (Display name/mail/UPN)Optional
Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-create-channel channel_name="example channel" team=DemistoTeam description="this is my new channel"

Human Readable Output#

The channel "example channel" was created successfully

microsoft-teams-create-meeting#


Creates a new meeting in Microsoft Teams.

Base Command#

microsoft-teams-create-meeting

Required Permissions#

OnlineMeetings.ReadWrite.All - Application OnlineMeetings.ReadWrite - Delegated

When using Client Credentials Flow: Besides setting up this permission, in order to create a meeting, the Azure admin needs to configure application access policy and grant users permissions to create meetings. The script ConfigureAzureApplicationAccessPolicy was created to support the needed commands. For more information: Allow applications to access online meetings on behalf of a user

When using Authorization Code Flow: The authentication process is conducted on behalf of the specific user who initiated the login request. Therefore, the given member must be the same user.

Input#
Argument NameDescriptionRequired
start_timeThe meeting start time in ISO 8601 format e.g., "2019-07-12T14:30:34.2444915-07:00".Optional
end_timeThe meeting end time in ISO 8601 format e.g., "2019-07-12T14:30:34.2444915-07:00".Optional
subjectThe meeting subject.Required
memberDisplay name/mail/UPN of user who created the meeting, e.g., Adam Smith.Required
Context Output#
PathTypeDescription
MicrosoftTeams.CreateMeeting.creationDateTimeDateMeeting creation time.
MicrosoftTeams.CreateMeeting.threadIdStringMeeting thread ID.
MicrosoftTeams.CreateMeeting.messageIdStringMeeting message ID.
MicrosoftTeams.CreateMeeting.idStringMeeting ID.
MicrosoftTeams.CreateMeeting.joinWebUrlStringThe URL to join the meeting.
MicrosoftTeams.CreateMeeting.participantIdStringThe meeting participants.
MicrosoftTeams.CreateMeeting.participantDisplayNameStringThe display name of the participants.
Command Example#

!microsoft-teams-create-meeting member="example user" subject="Important meeting"

Human Readable Output#

The meeting "Important meeting" was created successfully

microsoft-teams-user-remove-from-channel#


Removes a member (user) from a private/shared channel.

Base Command#

microsoft-teams-user-remove-from-channel

Required Permissions#

ChannelMember.ReadWrite.All - Application

Input#
Argument NameDescriptionRequired
channel_nameThe name of the channel.Required
teamThe name of the channel's team.Required
memberThe display name of the member to remove from the channel.Required
Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-user-remove-from-channel channel_name="example channel" member=itayadmin team=DemistoTeam

Human Readable Output#

The User "itayadmin" has been removed from channel "example channel" successfully.

microsoft-teams-channel-user-list#


Retrieves a list of members from a channel.

Base Command#

microsoft-teams-channel-user-list

Required Permissions#

ChannelMember.Read.All - Application ChannelMember.ReadWrite.All - Application

Input#
Argument NameDescriptionRequired
channel_nameThe name of the channel.Required
teamThe name of the channel's team.Required
Context Output#
PathTypeDescription
MicrosoftTeams.ChannelList.channelIdStringThe channel ID.
MicrosoftTeams.ChannelList.channelNameStringThe name of the channel.
MicrosoftTeams.ChannelList.members.displayNameStringThe display name of the members.
MicrosoftTeams.ChannelList.members.emailStringThe email of the members.
MicrosoftTeams.ChannelList.members.idStringThe ID of the members.
MicrosoftTeams.ChannelList.members.rolesStringThe roles of the members.
MicrosoftTeams.ChannelList.members.tenantIdStringThe tenant ID of the members.
MicrosoftTeams.ChannelList.members.userIdStringThe user ID of the members.
MicrosoftTeams.ChannelList.members.visibleHistoryStartDateTimeStringThe timestamp denoting how far back a conversation's history is shared with the conversation member.
Command Example#

!microsoft-teams-channel-user-list channel_name="example channel" team=DemistoTeam

Human Readable Output#
Channel 'example channel' Members List:#
User IdEmailTenant IdMembership idUser rolesDisplay NameStart DateTime
359d2c3c-162b-414c-b2eq-386461e5l050test@gmail.compbae9ao6-01ql-249o-5me3-4738p3e1m941MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkMTQ=owneritayadmin0001-01-01T00:00:00Z

Chat Commands#

microsoft-teams-chat-create#


Creates a new chat.

Notes:

  • Only one oneOnOne chat can exist between two members. If a oneOnOne chat already exists, it will be returned.
  • This command works with the consent user, not with the bot. Which means, the chat is created between the consent user and the user provided in the command's argument.
Base Command#

microsoft-teams-chat-create

Required Permissions#

Chat.Create - Delegated, Application
Chat.ReadWrite - Delegated
TeamsAppInstallation.ReadWriteForChat - Delegated
TeamsAppInstallation.ReadWriteSelfForChat - Delegated
TeamsAppInstallation.ReadWriteSelfForChat.All - Application

TeamsAppInstallation.ReadWriteForChat.All - Application
AppCatalog.Read.All - Application

Input#
Argument NameDescriptionRequired
chat_typeSpecifies the type of chat. Possible values are: group, oneOnOne. Default is group.Required
memberDisplay name/mail/UPN of user that should be added to the chat. Can be an array.Optional
chat_nameThe title of the chat. The chat title can be provided only if the chat is of group type.Optional
Context Output#
PathTypeDescription
MicrosoftTeams.ChatList.chatIdStringThe chat's unique identifier.
MicrosoftTeams.ChatList.topicStringSubject or topic for the chat. Only available for group chats.
MicrosoftTeams.ChatList.createdDateTimeStringDate and time at which the chat was created.
MicrosoftTeams.ChatList.lastUpdatedDateTimeStringDate and time at which the chat was renamed or list of members were last changed.
MicrosoftTeams.ChatList.chatTypeStringSpecifies the type of chat.
MicrosoftTeams.ChatList.webUrlStringThe URL for the chat in Microsoft Teams. The URL should be treated as an opaque blob, and not parsed.
MicrosoftTeams.ChatList.tenantIdStringThe identifier of the tenant in which the chat was created.
MicrosoftTeams.ChatList.viewpointStringRepresents caller-specific information about the chat, such as last message read date and time.
MicrosoftTeams.ChatList.onlineMeetingInfoStringRepresents details about an online meeting. If the chat isn't associated with an online meeting, the property is empty.
Command Example#

!microsoft-teams-chat-create chat_type=group member="itayadmin, Bruce Willis" chat_name="example chat"

Human Readable Output#
The chat 'example chat' was created successfully#
Chat IdChat nameCreated Date TimeLast Updated Date TimewebUrlTenant Id
19:2da4c29f6d7041eca70b638b43d45437@thread.v2example chat2023-01-08T07:51:53.07Z2023-01-08T07:51:53.07ZwebUrlpbae9ao6-01ql-249o-5me3-4738p3e1m941

microsoft-teams-message-send-to-chat#


Sends a new chat message in the specified chat.

Note:

This command works with the consent user, not with the bot. Which means, the message is sent to the given chat by the consent user, not the bot.

Base Command#

microsoft-teams-message-send-to-chat

Required Permissions#

ChatMessage.Send - Delegated
Chat.ReadWrite - Delegated
TeamsAppInstallation.ReadWriteForChat - Delegated
TeamsAppInstallation.ReadWriteSelfForChat - Delegated
TeamsAppInstallation.ReadWriteSelfForChat.All - Application

TeamsAppInstallation.ReadWriteForChat.All - Application
AppCatalog.Read.All - Application

Input#
Argument NameDescriptionRequired
chatThe chat ID / group chat name (topic) / oneOnOne member (Display name/mail/UPN).Required
contentThe content of the chat message.Required
content_typeThe message content type. Possible values are: text, html. Default is text.Optional
message_typeThe type of chat message. Default is message.Optional

Context Output#

PathTypeDescription
MicrosoftTeams.ChatList.chatIdStringThe chat's unique identifier.
MicrosoftTeams.ChatList.messages.idStringUnique ID of the message.
MicrosoftTeams.ChatList.messages.replyToIdStringID of the parent chat message or root chat message of the thread.
MicrosoftTeams.ChatList.messages.etagStringVersion number of the chat message.
MicrosoftTeams.ChatList.messages.messageTypeStringThe type of chat message.
MicrosoftTeams.ChatList.messages.createdDateTimeStringTimestamp of when the chat message was created.
MicrosoftTeams.ChatList.messages.lastModifiedDateTimeStringTimestamp when the chat message is created (initial setting) or modified, including when a reaction is added or removed.
MicrosoftTeams.ChatList.messages.lastEditedDateTimeStringTimestamp when edits to the chat message were made. Triggers an "Edited" flag in the Teams UI. If no edits are made the value is null.
MicrosoftTeams.ChatList.messages.deletedDateTimeStringTimestamp at which the chat message was deleted, or null if not deleted.
MicrosoftTeams.ChatList.messages.subjectStringThe subject of the chat message, in plaintext.
MicrosoftTeams.ChatList.messages.summaryStringSummary text of the chat message that could be used for push notifications and summary views or fall back views.
MicrosoftTeams.ChatList.messages.chatIdStringIf the message was sent in a chat, represents the identity of the chat.
MicrosoftTeams.ChatList.messages.importanceStringThe importance of the chat message.
MicrosoftTeams.ChatList.messages.localeStringLocale of the chat message set by the client.
MicrosoftTeams.ChatList.messages.webUrlStringLink to the message in Microsoft Teams.
MicrosoftTeams.ChatList.messages.channelIdentityStringIf the message was sent in a channel, represents identity of the channel.
MicrosoftTeams.ChatList.messages.policyViolationStringDefines the properties of a policy violation set by a data loss prevention (DLP) application.
MicrosoftTeams.ChatList.messages.eventDetailStringIf present, represents details of an event that happened in a chat, a channel, or a team, for example, adding new members.
MicrosoftTeams.ChatList.messages.fromStringDetails of the sender of the chat message.
MicrosoftTeams.ChatList.messages.bodyStringPlaintext/HTML representation of the content of the chat message. Representation is specified by the contentType inside the body.
MicrosoftTeams.ChatList.messages.attachmentsStringReferences to attached objects like files, tabs, meetings etc.
MicrosoftTeams.ChatList.messages.mentionsStringList of entities mentioned in the chat message.
MicrosoftTeams.ChatList.messages.reactionsStringReactions for this chat message (for example, Like).
Command Example#

!microsoft-teams-message-send-to-chat chat="example chat" content="Hello World"

Human Readable Output#

Message was sent successfully in the 'example chat' chat.#

Chat IdCreated DateTimeEtagFrom userFrom user idFrom user userIdentityTypeImportanceMessage ContentMessage TypeMessage contentTypeMessage idlastModified DateTime
19:2da4c29f6d7041eca70b638b43d45437@thread.v22021-03-29T04:17:43.15Z1616991463150itayadmin8ea0e38b-efb3-4757-924a-5f94061cf8c2aadUsernormalHello Worldmessagetext16169914631502021-03-29T04:17:43.15Z

microsoft-teams-chat-add-user#


Adds a member (user) to a group chat.

Base Command#

microsoft-teams-chat-add-user

Required Permissions#

ChatMember.ReadWrite - Delegated Chat.ReadWrite - Delegated

Input#

Argument NameDescriptionRequired
chatThe chat ID or group chat name (topic) to which to add the member.Required
memberDisplay name/mail/UPN of user that should be added to the chat. Can be an array.Required
share_historyWhether to share the whole history of the chat. Possible values are: true, false. Default is True.Optional

Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-chat-add-user chat="example chat" member="Bruce Willis" share_history=false

Human Readable Output#

The User "Bruce Willis" has been added to chat "example chat" successfully.

microsoft-teams-chat-member-list#


Retrieves a list of members from a chat.

Base Command#

microsoft-teams-chat-member-list

Required Permissions#

Chat.ReadWrite - Delegated ChatMember.ReadWrite - Delegated

Input#

Argument NameDescriptionRequired
chatThe chat ID / group chat name (topic) / oneOnOne Member (Display name/mail/UPN).Required

Context Output#

PathTypeDescription
MicrosoftTeams.ChatList.chatIdStringThe chat's unique identifier.
MicrosoftTeams.ChatList.members.displayNameStringThe display name of the members.
MicrosoftTeams.ChatList.members.emailStringThe email of the members.
MicrosoftTeams.ChatList.members.idStringThe ID of the members.
MicrosoftTeams.ChatList.members.rolesStringThe roles of the members.
MicrosoftTeams.ChatList.members.tenantIdStringThe tenant ID of the members.
MicrosoftTeams.ChatList.members.userIdStringThe user ID of the members.
MicrosoftTeams.ChatList.members.visibleHistoryStartDateTimeStringThe timestamp denoting how far back a conversation's history is shared with the conversation member.
Command Example#

!microsoft-teams-chat-member-list chat="example chat"

Human Readable Output#

Chat "example chat" Members List:#

User IdUser rolesNameEmailTenant Id
359d2c3c-162b-414c-b2eq-386461e5l050owneritayadmintest@gmail.comdcd219dd-bc68-4b9b-bf0b-4a33a796be35
48d31887-5fad-4d73-a9f5-3c356e68a038ownerBruce Willistest@gmail.comdcd219dd-bc68-4b9b-bf0b-4a33a796be35

microsoft-teams-chat-list#


Retrieves a list of chats that the user is part of. If 'chat' is specified - retrieves this chat only.

Base Command#

microsoft-teams-chat-list

Required Permissions#

Chat.ReadWrite - Delegated

Input#

Argument NameDescriptionRequired
chatThe chat ID / group chat name (topic) / oneOnOne member (Display name/mail/UPN).Optional
filterFilters results. For example: topic eq 'testing'. For more query examples, see https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=http.Optional
expandExpands the results to include members or lastMessagePreview properties. Possible values are: members, lastMessagePreview.Optional
limitThe number of results to retrieve. Default is 50.Optional
next_linkA link that specifies a starting point to use for subsequent calls.Optional
page_sizeNumber of results to return per page. Default is 50.Optional

Context Output#

PathTypeDescription
MicrosoftTeams.ChatList.chatIdStringThe chat's unique identifier.
MicrosoftTeams.ChatList.topicStringSubject or topic for the chat. Only available for group chats.
MicrosoftTeams.ChatList.createdDateTimeStringDate and time at which the chat was created.
MicrosoftTeams.ChatList.lastUpdatedDateTimeStringDate and time at which the chat was renamed or list of members were last changed.
MicrosoftTeams.ChatList.chatTypeStringSpecifies the type of chat.
MicrosoftTeams.ChatList.webUrlStringThe URL for the chat in Microsoft Teams. The URL should be treated as an opaque blob, and not parsed.
MicrosoftTeams.ChatList.tenantIdStringThe identifier of the tenant in which the chat was created.
MicrosoftTeams.ChatList.viewpointStringRepresents caller-specific information about the chat, such as last message read date and time.
MicrosoftTeams.ChatList.onlineMeetingInfoStringRepresents details about an online meeting. If the chat isn't associated with an online meeting, the property is empty.
MicrosoftTeams.ChatListNextLinkStringUsed if an operation returns partial results. If a response contains a NextLink element, its value specifies a starting point to use for subsequent calls.
Command Example#

!microsoft-teams-chat-list filter="topic eq 'testing'"

Human Readable Output#

Chats List:#

Chat IdChat nameCreated Date TimeLast Updated Date TimeChat TypewebUrlTenant IdLast Message Read Date Time
19:561082c0f3f847a58069deb8eb300807@thread.v2testing2023-01-08T14:15:45.412Z2023-01-08T14:15:45.412ZgroupwebUrltenantId2023-01-08T14:16:48.662Z
19:2da4c29f6d7041eca70b638b43d45437@thread.v2testing2022-12-29T11:10:49.173Z2022-12-29T11:10:49.173ZgroupwebUrltenantId2022-12-29T12:00:07.317Z

microsoft-teams-chat-message-list#


Retrieves a list of messages in a chat.

Base Command#

microsoft-teams-chat-message-list

Required Permissions#

Chat.ReadWrite - Delegated

Input#

Argument NameDescriptionRequired
chatThe chat ID / group chat name (topic) / oneOnOne member (Display name/mail/UPN).Required
limitThe number of results to retrieve. Default is 50.Optional
order_byOrders results by lastModifiedDateTime (default) or createdDateTime in descending order. Possible values are: lastModifiedDateTime, createdDateTime. Default is lastModifiedDateTime.Optional
next_linkA link that specifies a starting point to use for subsequent calls.Optional
page_sizeNumber of results to return per page. Default is 50.Optional

Context Output#

PathTypeDescription
MicrosoftTeams.ChatList.chatIdStringThe chat's unique identifier.
MicrosoftTeams.ChatList.messages.idStringUnique ID of the message.
MicrosoftTeams.ChatList.messages.replyToIdStringID of the parent chat message or root chat message of the thread.
MicrosoftTeams.ChatList.messages.etagStringVersion number of the chat message.
MicrosoftTeams.ChatList.messages.messageTypeStringThe type of chat message.
MicrosoftTeams.ChatList.messages.createdDateTimeStringTimestamp of when the chat message was created.
MicrosoftTeams.ChatList.messages.lastModifiedDateTimeStringTimestamp when the chat message is created (initial setting) or modified, including when a reaction is added or removed.
MicrosoftTeams.ChatList.messages.lastEditedDateTimeStringTimestamp when edits to the chat message were made. Triggers an "Edited" flag in the Teams UI. If no edits are made the value is null.
MicrosoftTeams.ChatList.messages.deletedDateTimeStringTimestamp at which the chat message was deleted, or null if not deleted.
MicrosoftTeams.ChatList.messages.subjectStringThe subject of the chat message, in plaintext.
MicrosoftTeams.ChatList.messages.summaryStringSummary text of the chat message that could be used for push notifications and summary views or fall back views.
MicrosoftTeams.ChatList.messages.chatIdStringIf the message was sent in a chat, represents the identity of the chat.
MicrosoftTeams.ChatList.messages.importanceStringThe importance of the chat message.
MicrosoftTeams.ChatList.messages.localeStringLocale of the chat message set by the client.
MicrosoftTeams.ChatList.messages.webUrlStringLink to the message in Microsoft Teams.
MicrosoftTeams.ChatList.messages.channelIdentityStringIf the message was sent in a channel, represents identity of the channel.
MicrosoftTeams.ChatList.messages.policyViolationStringDefines the properties of a policy violation set by a data loss prevention (DLP) application.
MicrosoftTeams.ChatList.messages.eventDetailStringIf present, represents details of an event that happened in a chat, a channel, or a team, for example, adding new members.
MicrosoftTeams.ChatList.messages.fromStringDetails of the sender of the chat message.
MicrosoftTeams.ChatList.messages.bodyStringPlaintext/HTML representation of the content of the chat message. Representation is specified by the contentType inside the body.
MicrosoftTeams.ChatList.messages.attachmentsStringReferences to attached objects like files, tabs, meetings etc.
MicrosoftTeams.ChatList.messages.mentionsStringList of entities mentioned in the chat message.
MicrosoftTeams.ChatList.messages.reactionsStringReactions for this chat message (for example, Like).
MicrosoftTeams.MessageListNextLinkStringUsed if an operation returns partial results. If a response contains a NextLink element, its value specifies a starting point to use for subsequent calls.
Command Example#

!!microsoft-teams-chat-message-list chat="example chat" order_by=createdDateTime

Human Readable Output#

Messages list in "example chat" chat:#

Chat IdCreated DateTimeEtagFrom userFrom user idFrom user userIdentityTypeImportanceMessage ContentMessage TypeMessage contentTypeMessage idlastModified DateTime
19:2da4c29f6d7041eca70b638b43d45437@thread.v22021-03-29T04:17:43.15Z1616991463150itayadmin8ea0e38b-efb3-4757-924a-5f94061cf8c2aadUsernormalHello Worldmessagetext16169914631502021-03-29T04:17:43.15Z

microsoft-teams-chat-update#


Updates the chat name. It can only be set for group chats.

Base Command#

microsoft-teams-chat-update

Required Permissions#

Chat.ReadWrite - Delegated

Input#

Argument NameDescriptionRequired
chatThe chat ID / group chat name (topic).Required
chat_nameThe new chat name. Maximum length is 250 characters. Use of ':' is not allowed.Required

Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-chat-update chat="example chat" chat_name="update chat_name"

Human Readable Output#

The name of chat 'example chat' has been successfully changed to 'update chat_name'.

microsoft-teams-auth-test#


Tests the connectivity to MicrosoftTeams.

Base Command#

microsoft-teams-auth-test

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!microsoft-teams-auth-test

Human Readable Output#

✅ Success!

microsoft-teams-generate-login-url#


Generate the login url used for Authorization code flow.
Note: Authorization codes are short-lived. Typically, they expire after about 10 minutes.

Base Command#

microsoft-teams-generate-login-url

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command example#

!microsoft-teams-generate-login-url

Human Readable Output#

Authorization instructions#

  1. Click on the login URL to sign in and grant Cortex XSOAR permissions for your Azure Service Management. You will be automatically redirected to a link with the following structure: REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
  2. Copy the AUTH_CODE (without the code= prefix, and the session_state parameter) and paste it in your instance configuration under the Authorization code parameter.

microsoft-teams-auth-reset#


Run this command if for some reason you need to rerun the graph authentication process. Notes:

  • Use this command to switch between authentication flows and ensure the integration uses the appropriate token.
  • After making changes to permissions in the Azure Portal, reset the authentication to ensure that the token reflects the updated permissions.
  • When using the Authorization Code Flow, after executing the command, regenerate the Authorization code parameter, and then run the !microsoft-teams-auth-test command to verify the authentication.

Base Command#

microsoft-teams-auth-reset

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Running commands from Microsoft Teams#

You can run Cortex XSOAR/Cortex XSIAM commands, according to the user permissions, from Microsoft Teams in a mirrored investigation channel.

Direct messages commands#

You can chat with the bot in direct messages in order to retrieve data (list incidents and tasks) and run operations (create incident and mirror an investigation) related to Cortex XSOAR.

You can send the message help in order to see the supported commands:

image

Note: To enrich an incident created via the Demisto BOT (new incident command) with extra information received with the request, as in regular fetch-incidents process users may create custom mappers and map the desired values.

Troubleshooting#

  1. The integration works by spinning up a web server that listens to events and data posted to it from Microsoft Teams.

    If you see the error message Did not receive tenant ID from Microsoft Teams, verify the messaging endpoint is configured correctly., then it means that the tenant ID was never posted to the web server, which should happen for the first time when the bot is added to the configured team.

    This probably means that there is a connection issue, and the web server does not intercept the HTTPS queries from Microsoft Teams.

    To troubleshoot:

    1. Verify that the messaging endpoint is configured correctly according to the method you chose in the Setup Examples step.

    2. Verify the Docker container is up and running and publish the configured port to the outside world:

      From the Cortex XSOAR / Cortex XSOAR engine machine run: docker ps | grep teams

      You should see the following, assuming port 7000 is used:

      988fdf341127 demisto/teams:1.0.0.6483 "python /tmp/pyrunne…" 6 seconds ago Up 4 seconds 0.0.0.0:7000->7000/tcp demistoserver_pyexecLongRunning-b60c04f9-754e-4b68-87ed-8f8113419fdb-demistoteams1.0.0.6483--26

      If the Docker container is up and running, try running cURL queries to verify the web server is up and running and listens on the configured URL:

      • To the messaging endpoint from a separate box.
      • From the Cortex XSOAR machine to localhost.
        • Note: The web server supports only POST method queries.
    3. If the cURL queries were sent successfully, you should see the following line in Cortex XSOAR logs: Finished processing Microsoft Teams activity successfully.

    4. If you're working with secured communication (HTTPS), make sure that you provided a valid certificate. (Not for Cortex XSOAR/Cortex XSIAM Rerouting ).

      1. Run openssl s_client -connect <domain.com>:443 .
      2. Verify that the returned value of the Verify return code field is 0 (ok), otherwise, it's not a valid certificate.
    5. Try inserting your configured message endpoint in a browser and click Enter. If Method Not Allowed is returned, the endpoint is valid and ready to communicate, otherwise, it needs to be handled according to the returned error's message. (Not for Cortex XSOAR 8 OR Cortex XSIAM).

    6. In some cases, a connection is not created between Teams and the messaging endpoint when adding a bot to the team. You can work around this problem by adding any member to the team the bot was added to (the bot should be already added to the team). This will trigger a connection and solve the issue. You can then remove the member that was added.

  2. If you see the following error message: Error in API call to Microsoft Teams: [403] - UnknownError, then it means the AAD application has insufficient permissions.

  3. Since the integration works based on Docker port mapping, it can't function if the Docker is set to run with the host networking (--network=host). For more details, refer to the Docker documentation.

  4. The integration stores in cache metadata about the teams, members and channels. Starting from Cortex XSOAR version 6.1.0, you can clear the integration cache in the integration instance config:

    First, make sure to remove the bot from the team (only via the Teams app), before clearing the integration cache, and add it back after done. If the bot belongs to multiple teams, make sure to remove it from all the teams it was added to, and then clear the cache.

  5. If the previous step did not work, remove the bot from the team, go to the Microsoft Teams admin center > Manage apps and hard refresh the page!(cmd+ shift + R), then add the bot to the team again.

Download Demisto Bot#

Demisto Bot zip