Microsoft Teams Bot Framework
Overview
Microsoft Teams Bot Framework REST API enables your bot to exchange messages with users on channels.
D3 SOAR is providing REST operations to function with Microsoft Teams Bot Framework.
Microsoft Teams Bot Framework is available for use in:
Connection
To connect to Microsoft Teams Bot Framework from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
Server URL (domain level) | The server URL of the Microsoft Teams Bot Framework API. By default, it is set to https://smba.trafficmanager.net/teams. The alternate server URLs include: | https://smba.trafficmanager.net/teams |
Client ID | The client ID to authenticate the API connection. | *** |
Client Secret | The client secret to authenticate the API connection. | *** |
Bot GUID | The Bot ID to authenticate the API connection. | *** |
API Version | The version of the API to use for the connection. | v3 |
Integration API Note
For more information about the Microsoft Teams Bot Framework API, please refer to the Microsoft Teams Bot Framework API reference.
Configuring Microsoft Teams Bot Framework to work with D3 SOAR
Navigate to the Create an Azure Bot page: https://portal.azure.com/#create/Microsoft.AzureBot.
Create an Azure Bot named D3 Bot.
Input the required parameters. For Type of App, select Multi Tenant. For Creation type, select Create new Microsoft App ID if you don't already have an app registration. Otherwise, select Use existing app registration and fill in your App ID.
Click Review + Create, and wait for the validation to pass.
Click Create if the validation has passed, and wait for the deployment to finish.
Under Next Steps, click Go to resource.
Navigate to Configuration on the left sidebar, and fill in the Messaging Endpoint. The format is: "<your url>api/Teams/Message". A URL example: "https://ctm.d3securityonline.net/MainApp/VSOC/", so the Messaging endpoint should input "https://ctm.d3securityonline.net/MainApp/VSOC/api/Teams/Message". Click Apply to finish the changes.
Store the Microsoft App ID value for the next steps, and navigate to Manage Password next to it.
Click New Client Secret, fill in the Description and Expires fields as desired, then click Add. Copy the Client Secret from the value field and store it for the next steps.
Click Overview, then copy and save the Client ID. Please note that the Bot ID is the same as Client ID, which will be used later in this guide.
Navigate to API Permissions, then grant the Channel.Create(application), ChannelMember.ReadWrite.All(application), ChannelMessage.Send(delegated), Group.ReadWrite.All(application) and User.Read.All(application) permissions under Microsoft Graph.
Grant admin consent.
Go back to the Azure Bot page, and navigate to Channels in the left sidebar.
Click Microsoft Teams under Available Channels, click the checkbox, click Agree, then click Apply.
Download the ZIP file here.
Extract the ZIP file. You should see three files (manifest.json, color.png and outline.png).
Open the manifest.json file that was extracted from the ZIP file.
At the path $.id, replace the value of the attribute with the value of the Bot ID from step 7.
In the bots list, replace the value of the botId attribute with the value of the Bot ID (at the path $.bots[*].botId) from step 7.
At the path $.webApplicationInfo, replace the value of id attribute with the value of the Bot ID from step 7.
Compress the three files (the modified manifest.json file, color.png and outline.png) as a .zip file.
In the Microsoft Teams admin center, locate your desired team. Click on the three-dot button and select Manage team. Select the Apps tab, then Upload a custom app. Upload the previous saved .zip file on your local drive.
Click Add to assign the bot to the team.
You will be able to see the custom app you just added on the Apps list.
Configuring D3 SOAR to Work with Microsoft Teams Bot Framework
Log in to D3 SOAR.
Find the Microsoft Teams Bot Framework integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Microsoft Teams Bot Framework in the search box to find the integration, then click it to select it.
Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft Teams Bot Framework.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
Allow messages to also be sent to Microsoft Teams Bot Framework through this connection
The Allow messages to also be sent to Microsoft Teams Bot Framework through this connection check box will bring up a dropdown to select a global list for site and channel mapping. Refer to Setting up a Global List to Send Messages via the Microsoft Teams Bot Framework for more information on setting up the global list.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input the Server URL. The default value is https://smba.trafficmanager.net/teams.
2. Input the saved Client ID. Refer to step 7 of Configuring Microsoft Teams Bot Framework to Work with D3 SOAR.
3. Input the saved Client Secret. Refer to step 6 of Configuring Microsoft Teams Bot Framework to Work with D3 SOAR.
4. Input the saved Bot GUID. Refer to step 4 of Configuring Microsoft Teams Bot Framework to Work with D3 SOAR.
5. Input the API Version. The default value is v3.Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Setting up a Global List to Send Messages via the Microsoft Teams Bot Framework
In D3 SOAR, you can configure a connection via Microsoft Bot Framework to broadcast messages to multiple sites, each associated with a different team and respective channels. Here's a step-by-step guide to setting it up:
Reader Note
For optimal efficiency, we recommend utilizing a single connection that is set to "Share to client site" or "Shared to internal sites." This global list should include only either client or internal sites. Using multiple connectors may lead to misused connectors, resulting in errors.
In D3 SOAR, navigate to Configuration > Global List > New Global List. Provide a name for the global list, then define the global list JSON array using the format below.
[
{
"{{Site_Name}}": {
"MSTeamConnectionName": "{{connection_name}}",
"TeamIdentifier": "{{team_identifier}}",
"ChannelIdentifier": "{{channel_identifier}}",
"ChannelsToMention": [
"{{channel_to_mention_1}}",
"{{channel_to_mention_2}}"
]
},
"{{D3 SOAR Site 2}}": {
"ChannelIdentifier": "{{channel_identifier}}"
}
}
]Fields Descriptions:
Site Name: Specify the target D3 SOAR site along with the connection name, team, and channels to auto-mention. Ensure that all sites listed are either client or internal to prevent mixing categories, which could trigger multiple Microsoft Bot Framework connections and potentially result in issues.
MSTeamConnectionName (Optional): Name of the connector created for Microsoft Teams integration. The grant type for the connection must be authorization code. To use the @channel function, ensure to create a connector with identical credentials for the MS Teams Bot Framework integration.
Team Identifier (Optional): The ID of the target team to send messages (multiple teams per site are not allowed). To obtain your Teams ID, establish a Microsoft Teams integration connection, run the List Teams command.
ChannelIdentifier: The ID of the channel for message delivery (one site corresponds to one channel; private channels are excluded). To obtain your Teams Channel ID, establish a Microsoft Teams integration connection and run the List Channels command.
Reader Note
The input Channel ID must be under the specified Team ID.
If only the "ChannelIdentifier" key is defined in the JSON array, no channels will be automatically mentioned in the sent message.
ChannelsToMention (Optional): The channels to mention in the message. Channels can be specified by either IDs or names.
Here is an example of a defined global list:
[
{
"Client Testing Site 1": {
"MSTeamConnectionName": "teams_authorization_code",
"TeamIdentifier": "*****",
"ChannelIdentifier": "*****",
"ChannelsToMention": [
"*****",
"test1"
]
},
"Client Testing Site 2": {
"ChannelIdentifier": "*****"
}
}
]Reader Note
Ensure a separate JSON object in the array defines each designated site.
Each message you send will be accompanied by a card, as shown in the screenshot below, indicating the channels you have selected.
Enable the global list for the desired sites by selecting them from the Available Sites box and using the arrow buttons to move them to the shared sites list. The following steps won't work correctly unless the client sites listed in the global list are also included in the shared sites list.
After you create the global list, refresh your web browser to ensure it appears in the global list dropdown when configuring the Microsoft Teams Bot Framework integration connection.
Using the "Send Message" Utility Command with the Microsoft Bot Framework in a Playbook
With the global list set up, you can use the Send Message utility command to send messages to the configured specified Microsoft Teams channels in a playbook.
Follow the instructions in Configuring Microsoft Teams Bot Framework to work with D3 SOAR to create a connection shared to your desired sites. For the Site and Channel Mapping Global List parameter, select the global list you have created. Refer to the previous section for more details.
In a playbook, add a new command task with the Send Message utility command.
Configure the Send Message utility command. Set the Recipient parameter to External Messaging Integrations.
Let's examine the input parameters of the Send Message utility command in detail.
Input Parameter | Required/Optional | Description | Example |
Recipient | Optional | The recipient(s) of this message. To send messages to Microsoft Teams, select the External Messaging Integrations (That are set up) option. | External Messaging Integrations (That are set up) |
Content | Required | The contents of the message. If the reply mode is set to No Action, only simple text is supported. If it is Reply Mode, refer to the reader note below to format messages with custom HTML content. | Test message |
Reply Mode | Required | The mode to determine if this message requires a response or approval. When it is specified as No Action, any external user actions will not be responded to. | Require Approval |
Reply Due Time | Optional | The number of minutes before the message is overdue, if the Reply Mode has been set to Require Approval. This parameter is only used if the message content has card actions. | 100 |
Reader Note
Drafting Card Messages with Interactive Options
When the Reply Mode is set to 'No Action', only plain text can be entered into the Content parameter. However, if the Reply Mode is switched to 'Require Approval', you can draft messages with interactive response cards with custom HTML content. Refer to the example data below to understand how to define the Content parameter for creating a card message. Text between "//" denotes annotations.
SAMPLE DATA
{
"type": "message",
"text": "this line will be removed", // The main content of the message goes here. HTML is supported. For @ mentions like "<at>d3support</at>", define details in the "entities" JSON object. Ensure names match those in the entity JSON objects. This text appears in a separate text box; to keep content in the same box, remove this field and define messages in the sections below. //
"attachments": [{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"type": "AdaptiveCard",
"version": "1.3",
"body": [{
"type": "TextBlock",
"text": "Your card text message goes here. You can mention a user or group here, like: Hi <at>d3support</at>!", // Text for the response options card. HTML and @ mentions are supported. //
"size": "Medium",
"wrap": true
}, {
"type": "Input.ChoiceSet",
"id": "*****", // Format: "responsexxx". "response" prefix is mandatory, and "xxx" can be any string. Each id must be unique. //
"style": "expanded",
"isMultiSelect": "false", // "true" for multiple choices, "false" for single choice. //
"isRequired": "true", // Mandatory field: "true" or "false". //
"isEnabled": "false", // Field enabled: "true" or "false". //
"label": "Response Option:",
"choices": [{
"title": "Activity Confirmed",
"value": "1",
"isEnabled": "false",
}, {
"title": "Add User to Watchlist",
"value": "2"
}, {
"title": "Block IP Address on Firewall",
"value": "3"
}, {
"title": "Lock The User's Account",
"value": "4"
}
]
}, {
"type": "Input.ChoiceSet",
"id": "*****",
"style": "expanded",
"isMultiSelect": "true", // "true" for multiple choices, "false" for single choice. //
"isRequired": "true",
"label": "Response Options:",
"choices": [{
"title": "Activity Confirmed",
"value": "1"
}, {
"title": "Add User to Watchlist",
"value": "2"
}, {
"title": "Block IP Address on Firewall",
"value": "3"
}, {
"title": "Lock The User's Account",
"value": "4"
}
]
}, {
"type": "Input.Text", // Template for comment box. //
"style": "text",
"isMultiline": true,
"label": "Put your comment or custom action value below:", // Description for the comment box. //
"id": "responseComment"
}
],
"msteams": {
"entities": [{ // Example entity object for mentioned tag (e.g., d3support). Follow this template for defining group entities. //
"type": "mention",
"text": "<at>d3support</at>",
"mentioned": {
"id": "*****",
"name": "d3support",
"type": "tag"
}
}
]
},
"actions": [{ // Template for reply actions. //
"type": "Action.Submit",
"title": "Approve",
"data": {
"msteams": {
"type": "invoke",
"displayText": "Approve",
"text": "text to bots approve",
"value": {
"respUrl": "<<UserActionRequiredURL>>",
"action": 1
}
}
}
}, {
"type": "Action.Submit",
"title": "Reject",
"data": {
"msteams": {
"type": "invoke",
"displayText": "Reject",
"text": "text to bots decline ",
"value": {
"respUrl": "<<UserActionRequiredURL>>",
"action": 2
}
}
}
}, {
"type": "Action.Submit",
"title": "Custom Action Button",
"data": {
"msteams": {
"type": "invoke",
"displayText": "Custom Action",
"text": "text to bots custom action ",
"value": {
"respUrl": "<<UserActionRequiredURL>>",
"customizedAction": "2000",
"action": 3
}
}
}
}
]
}
}
]
}Before running the Send Message command in the playbook, use the Test Command feature in the Send Activity integration command to verify your inputs.
Navigate to Configuration > Integrations > Microsoft Teams Bot Framework. Select the Send Activity command. This command dispatches an activity in the specified Microsoft Teams channel. Activities can be messages or cards. This will provide relevant error messages if there are issues. The Send Message utility command has limited error handling, especially when detecting incorrect content or cards.
Provide the Channel ID where you want to send the activity.
Set the Message Type parameter to Message.
Fill out the Action Objects parameter with the information intended for the Send Message utility command.
Overlook other parameters and click Test Command.
Carefully review any error messages. Adjust and test until the message is successfully sent. Once confirmed, the JSON object used in the Action Objects parameter will be ready for use in the Send Message Utility command.
Click the blue play button to test the playbook. You will be prompted to select a site and incident to test the playbook on.
Ensure the selected site has been previously added to the global list. Otherwise, your message will not be sent to your Microsoft Teams channel. If you don't see your site, check that your D3 SOAR user account has access to the site in Organization Management.
Reader Note
After running the command, verify that the command has run successfully. This is indicated by a green check mark on the Send Message command task.
In Microsoft Teams, your message should be received in the corresponding channel.
Retrieving Reply Actions and Comments in a Playbook
After using a Send Message utility command in a playbook to send a Microsoft Teams message with, you can use subsequent playbook tasks to retrieve the values of the customized actions and reply to comments. In this playbook, the Send Message command has been configured to send a message to a Teams channel to request approval.
Configure the Send Message command as illustrated in the previous example. The Contents parameter is populated with the provided sample data in the reader note above.
Add a conditional task to obtain the custom action of the message. Each condition retrieves the action data from specific reply actions. In this example, the custom action of the Approve and Reject buttons is "Reply by me", and the Custom Action Button's custom action is 2000. As such, the conditions are set to "Reply by Me" and 2000.
Add command tasks to each condition with the Get Value from JSON Object String by JSON Path utility command to obtain the custom action values and replied comments.
Test run the playbook.
In Microsoft Teams, the message will be displayed in the channel.
Respond to the message within the designated reply due time. You have the option to add a comment. Select a reply action. If you opt for Approve or Reject, the process will follow the "Reply by me" path in the conditional task. Alternatively, if you select the Custom Action Button, the playbook will proceed along the "2000" path in the conditional task.
Your input will be reflected in the updated message card.
If autorun is enabled, the subsequent playbook tasks will execute. You can then retrieve the output data from the respective commands.