Fortinet Document Library

Version:


Table of Contents

Microsoft Teams

1.0.0
Copy Link

About the connector

Microsoft Teams is a chat-based workspace in Office 365 that provides global, remote, and dispersed teams with the ability to work together and share information using a common space.

This document provides information about the Microsoft Teams connector, which facilitates automated interactions, using the Microsoft Graph API using FortiSOAR™ playbooks. Add the Microsoft Teams connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically creating teams, adding users to teams or groups, retrieving details about users and teams, etc.

Version information

Connector Version: 1.0.0

Authored By: Community

Certified: No

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-microsoft-teams

Prerequisites to configuring the connector

  • You must have the URL of the Microsoft Graph server to which you will connect and perform automated operations and information for all the parameters mentioned in the "Configuration Parameters" section. Also, refer to the following "Permissions required" section to understand the permissions required to call the Microsoft Graph API for performing various operations.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Permissions required

To call the Microsoft Graph API, to perform any action, you must be assigned specific permissions as defined in this section. To learn more, including how to choose permissions, see Microsoft Graph permissions reference.

Action Name Permission Type Permissions (from least to most privileged)
Create user Delegated (work or school account) User.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application User.ReadWrite.All, Directory.ReadWrite.All
Get Users Delegated (work or school account) User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All,User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application User.ReadWrite.All, Directory.ReadWrite.All
Update User Delegated (work or school account) User.ReadWrite, User.ReadWrite.All, User.ManageIdentities.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) User.ReadWrite
Application User.ReadWrite.All, User.ManageIdentities.All, Directory.ReadWrite.All
Delete User Delegated (work or school account) User.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application User.ReadWrite.All
Create group Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.Create, Group.ReadWrite.All, Directory.ReadWrite.All
Delete Group/Team Delegated (work or school account) Group.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All
Get Group/Team Delegated (work or school account) Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
Add Group Owner Delegated (work or school account) GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Add Group Member Delegated (work or school account) GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Get Group Members Delegated (work or school account) GroupMember.Read.All, Group.Read.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.Read.All, Group.Read.All, Directory.Read.All, Directory.ReadWrite.All
Get Group Owner Delegated (work or school account) Group.Read.All and User.ReadBasic.All, Group.Read.All and User.Read.All, Group.Read.All and User.ReadWrite.All, Group.Read.All and User.Read.All and Application.Read.All
Delegated (personal Microsoft account) Not Supported.
Application Group.Read.All and User.Read.All, Group.Read.All and User.ReadWrite.All, Group.Read.All and User.Read.All and Application.Read.All
Remove Group Owner Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All
Remove Group Member Delegated (work or school account) GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Create Channel Delegated (work or school account) Channel.Create, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Channel.Create.Group*, Channel.Create, Group.ReadWrite.All, Directory.ReadWrite.All
Get Channel Delegated (work or school account) Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All, ChannelSettings.Read.Group*, ChannelSettings.Edit.Group*, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Send Message Delegated (work or school account) ChannelMessage.Send, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Not Supported.
Reply Message Delegated (work or school account) ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application ChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Messages Mention Delegated (work or school account) ChannelMessage.Send, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Not Supported.
Get Channel Messages Delegated (work or school account) ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application ChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
List User Joined Teams Delegated (work or school account) Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Get Team Delegated (work or school account) Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Read.Group*, Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, TeamSettings.Edit.Group*, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Archive Team Delegated (work or school account) TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Edit.Group*, TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Create Team Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All
Clone Team Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All
Update Team Delegated (work or school account) TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Edit.Group*, TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Unarchive Team Delegated (work or school account) TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Edit.Group*, TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Microsoft Teams connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Microsoft Graph URL URL of the Microsoft Graph server to which you will connect and perform automated operations.
Token URL Token URL that is required to generate an OAuth token.
Directory (Tenant) ID Tenant ID of the application registered on the Microsoft Azure portal.
Application (Client) ID Unique ID of the application that is used to create the authentication token required to access the Microsoft Graph API.
Application (Client) Secret Unique Secret of the application that is used to create an authentication token required to access the Microsoft Graph API.
Username Username of the Microsoft Teams account you will use to perform automated operations.
Password Password of the Microsoft Teams account you will use to perform automated operations.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 onwards:

Function Description Annotation and Category
Create User Creates a new user in Microsoft Teams based on the display name, mail nickname, password, and other input parameters you have specified. create_user
Investigation
Get Users Retrieves details for users from Microsoft Teams based on the user ID or the user principal name you have specified.
Note: If no parameter is specified, then this operation returns details of all the users.
get_users
Investigation
Update User Updates the details of an existing Microsoft Teams user based on the user ID or the user principal name, and other input parameters you have specified. update_user
Investigation
Delete User Deletes an existing Microsoft Teams user based on the user ID or the user principal name you have specified.
Important: Once a user is deleted, the resources of the user are moved to a temporary container from which they can be restored within 30 days. After that time, they are permanently deleted.
delete_user
Investigation
Create Group Creates a new group in Microsoft Teams based on the display name, mail nickname, and other input parameters you have specified.
Note: You can create one of the following groups: Office 365 Group (Unified Group) or a Security Group.
create_group
Investigation
Delete Group/Team Deletes an existing Microsoft Teams group or team based on the team ID you have specified.
Important: Once a group or team is deleted, the Office 365 groups or teams are moved to a temporary container from which they can be restored within 30 days. After that time, they are permanently deleted.
delete_group
Investigation
Get Groups/Teams

Retrieves details for teams or groups from Microsoft Teams based on the group or team ID you have specified.
Note: If no parameter is specified, then this operation returns details of all the groups or teams.

get_groups
Investigation
Add Group Owner Adds a user as an owner of a specific Office 365 or Security Group in Microsoft Teams based on the group ID and user ID you have specified. add_owner
Investigation
Add Group Member Adds a user as a member of a specific Office 365 or Security Group in Microsoft Teams based on the group ID and user ID you have specified. add_member
Investigation
Get Group Members Retrieves a list of the direct members of a group from Microsoft Teams based on the group ID and user ID you have specified. A group can have users, contacts, devices, service principals, and other groups as its members. get_group_member
Investigation
Get Group Owner Retrieve a list of the owners of the specified group from Microsoft Teams based on the group ID you have specified get_group_owner
Investigation
Remove Group Owner Removes the specified owner for the specified group from Microsoft Teams based on the group ID and owner ID you have specified. remove_group_owner
Investigation
Remove Group Member Removes the specified user from the specified group in Microsoft Teams based on the group ID and user ID you have specified. remove_group_member
Investigation
Create Channel Creates a new channel in Microsoft Teams based on the team or group name, channel name, membership type, and other input parameters you have specified. create_channel
Investigation
Get Channel Retrieves information for a specified channel from Microsoft Teams based on the team or group ID and channel name you have specified. get_channel
Investigation
Send Message Sends chat messages to a specified channel in the specified group in Microsoft Teams based on the team or group ID, channel ID, and message you have specified. send_message
Investigation
Reply Message Replies to a specified chat message of a specified channel in the specified group in Microsoft Teams based on the group ID, channel ID, message ID, and message you have specified. reply_messages
Investigation
Messages Mention Adds a mention of a specific user to a specific message and channel in Microsoft Teams based on the team or group ID, channel ID, user ID, user display name, and message you have specified. messages_mention
Investigation
Get Channel Messages Retrieves a list of messages (without the replies) from a specific channel of a specific group in Microsoft Teams based on the team or group ID, channel ID, and optionally the message ID you have specified.
Note: If you specify the message ID then details of the specific message will be retrieved from Microsoft Teams.
get_channel_messages
Investigation
List User Joined Teams Retrieves the teams in which the specified user is a direct member from Microsoft Teams based on the user ID you have specified. list_user_joined_teams
Investigation
Get Team Retrieves detailed information about a team from Microsoft Teams based on the team or group ID you have specified. get_team
Investigation
Archive Team Archives the specified team in Microsoft Teams based on the team ID you have specified.
Note: When a team is archived, users can no longer send or like messages on any channel that is part of the archived team.
archive_team
Investigation
Create Team Creates a new team in Microsoft Teams based on the display name, description, and other input parameters you have specified. create_team
Investigation
Clone Team Creates a copy of a specified team in Microsoft Teams based on the team ID, display name, mail nick name, and other input parameters you have specified. This operation also creates a copy of the team's corresponding group. clone_team
Investigation
Update Team Updates the properties for an existing team in Microsoft Teams based on the team ID and properties you have specified. update_team
Investigation
Unarchive Team Restores an archived team in Microsoft Teams based on the team ID you have specified. Unarchiving a team restores the user's ability to send messages to the team and to edit the properties of the team. unarchive_team
Investigation

operation: Create User

Input parameters

Parameter Description
Display Name Name to display in the address book for the user that you want to create in Microsoft Teams.
Note: Maximum length for the user's display name is 256 characters.
Mail Nick Name Mail alias for the user that you want to create in Microsoft Teams.
Account Enabled Select this checkbox, i.e, set it to "true", to enable the newly created account in Microsoft Teams. By default, this is set as "false".
User Principal Name Principal name of the user, for example, someuser@contoso.com, that you want to create in Microsoft Teams.
Force Change Password Next SignIn Select this checkbox, i.e, set it to "true",  to force users to change their password when they sign in to Microsoft Teams the next time. Once the user has changed their password, this parameter automatically resets to false. By default, this is set as "false".
Password Password to be set for the user that you want to create in Microsoft Teams. You must set this password when you are creating a user in Microsoft Teams.
Passwords can be updated. However, the user will be required to change the password on their next login. The password must satisfy minimum requirements as specified by the "passwordPolicies" parameters of the user.
By default, a strong password is required.
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the user you want to create in Microsoft Team. The additional properties signify additional fields associated with the user.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "businessPhones": [],
     "displayName": "",
     "givenName": "",
     "jobTitle": "",
     "mail": "",
     "mobilePhone": "",
     "officeLocation": "",
     "preferredLanguage": "",
     "surname": "",
     "userPrincipalName": ""
}

operation: Get Users

Input parameters

Parameter Description
Based On

Parameter using which you want to retrieve details for a user from Microsoft Teams. You can choose between User ID or User Principal Name.

  • If you choose "User ID", then in the User ID field, you must specify the ID of the user whose details you want to retrieve from Microsoft Teams.
  • If you choose "User Principal Name", then in the User Principal Name field, you must specify the principal name of the user whose details you want to retrieve from Microsoft Teams. 

Note: If you do not specify this parameter, then details of all the users are returned.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "businessPhones": [],
             "displayName": "",
             "givenName": "",
             "jobTitle": "",
             "mail": "",
             "mobilePhone": null,
             "officeLocation": null,
             "preferredLanguage": null,
             "surname": "",
             "userPrincipalName": "",
             "id": ""
         }
     ]
}

operation: Update User

Input parameters

Parameter Description
Based On

Parameter using which you want to update the details of an existing Microsoft Teams user. You can choose between User ID or User Principal Name.

  • If you choose "User ID", then in the User ID field, you must specify the ID of the user whose details you want to update in Microsoft Teams.
  • If you choose "User Principal Name", then in the User Principal Name field, you must specify the principal name of the user whose details you want to update in Microsoft Teams. 
Display Name Display name that you want to update in the address book for the Microsoft Teams user.
Given Name Given name (first name) that you want to update for the Microsoft Teams user.
Surname Surname that you want to update for the Microsoft Teams user.
Job Title Job title that you want to update for the Microsoft Teams user.
Office Location Office location, i.e., the user's place of business that you want to update for the Microsoft Teams user.
Custom Properties (Optional) Additional properties, in the JSON format, that you want to update for the Microsoft Teams user. The additional properties signify additional fields associated with the user.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "id": "",
         "mail": "",
         "surname": "",
         "jobTitle": "",
         "givenName": "",
         "displayName": "",
         "mobilePhone": "",
         "@odata.context": "",
         "businessPhones": [],
         "officeLocation": "",
         "preferredLanguage": null,
         "userPrincipalName": ""
     },
     "status": "",
     "message": ""
}

operation: Delete User

Input parameters

Parameter Description
Based On

Parameter using which you want to delete an existing Microsoft Teams user. You can choose between User ID or User Principal Name.

  • If you choose "User ID", then in the User ID field, you must specify the ID of the user that you want to delete from Microsoft Teams.
  • If you choose "User Principal Name", then in the User Principal Name field, you must specify the principal name of the user that you want to delete from Microsoft Teams. 

Output

The output contains the following populated JSON schema:
{
     "result": {},
     "status": "",
     "message": ""
}

operation: Create Group

Input parameters

Parameter Description
Display Name Name to display in the address book for the group that you want to create in Microsoft Teams.
Note: Maximum length for the group's display name is 256 characters.
Mail Nickname Mail alias for the group that you want to create in Microsoft Teams.
Note: Spaces are not allowed in the mail alias for the group.
Email Enabled Select this checkbox for  "mail-enabled" groups.
Security Enabled Select this checkbox only for "security-enabled" groups, including Office 365 groups.
Description (Optional) Description of the group that you want to create in Microsoft Teams.
Visibility Visibility to be set for the Office 365 group that you want to create in Microsoft Teams. You can choose from the following options: Private, Public, HiddenMembership, or "empty" (which is interpreted as Public).
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the group you want to create in Microsoft Team. The additional properties signify additional fields associated with the group.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "deletedDateTime": "",
     "classification": "",
     "createdDateTime": "",
     "creationOptions": [],
     "description": "",
     "displayName": "",
     "groupTypes": [
         ""
     ],
     "isAssignableToRole": "",
     "mail": "",
     "mailEnabled": "",
     "mailNickname": "",
     "onPremisesDomainName": "",
     "onPremisesLastSyncDateTime": "",
     "onPremisesNetBiosName": "",
     "onPremisesSamAccountName": "",
     "onPremisesSecurityIdentifier": "",
     "onPremisesSyncEnabled": "",
     "preferredDataLocation": "",
     "proxyAddresses": [
         ""
     ],
     "renewedDateTime": "",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": "",
     "securityIdentifier": "",
     "visibility": "",
     "onPremisesProvisioningErrors": []
}

operation: Delete Group/Team

Input parameters

Parameter Description
Team ID ID of the group or team that you want to delete from Microsoft Teams.
Note: Every team is associated with a group and the group has the same ID as the team.

Output

The output contains the following populated JSON schema:
{
     "result": {},
     "status": "",
     "message": ""
}

operation: Get Groups/Teams

Input parameters

Parameter Description
Group ID ID of the group or team whose details you want to retrieve from Microsoft Teams.
Note: If you do not specify this parameter, then details of all the users are returned.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "id": "",
             "deletedDateTime": "",
             "classification": "",
             "createdDateTime": "",
             "creationOptions": [],
             "description": "",
             "displayName": "",
             "expirationDateTime": "",
             "groupTypes": [],
             "isAssignableToRole": "",
             "mail": "",
             "mailEnabled": "",
             "mailNickname": "",
             "membershipRule": "",
             "membershipRuleProcessingState": "",
             "onPremisesDomainName": "",
             "onPremisesLastSyncDateTime": "",
             "onPremisesNetBiosName": "",
             "onPremisesSamAccountName": "",
             "onPremisesSecurityIdentifier": "",
             "onPremisesSyncEnabled": "",
             "preferredDataLocation": "",
             "preferredLanguage": "",
             "proxyAddresses": [],
             "renewedDateTime": "",
             "resourceBehaviorOptions": [],
             "resourceProvisioningOptions": [],
             "securityEnabled": "",
             "securityIdentifier": "",
             "theme": null,
             "visibility": "",
             "onPremisesProvisioningErrors": []
         }
     ]
}

operation: Add Group Owner

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams to which you want to add the specific user as a group owner.
User ID ID of the user who you want to add as the group owner of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "user_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Add Group Member

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams to which you want to add the specific user as a member.
User ID ID of the user who you want to add as a member of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "owner_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Get Group Members

Input parameters

Parameter Description
Group ID ID of the group whose direct members you want to retrieve from Microsoft Teams.
User ID ID of the member belonging to the specified group whose details you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "@odata.type": "",
             "id": "",
             "businessPhones": [],
             "displayName": "",
             "givenName": "",
             "jobTitle": "",
             "mail": "",
             "mobilePhone": "",
             "officeLocation": "",
             "preferredLanguage": "",
             "surname": "",
             "userPrincipalName": ""
         }
     ]
}

operation: Get Group Owner

Input parameters

Parameter Description
Group ID ID of the group whose group owner details you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "@odata.type": "",
             "id": "",
             "businessPhones": [],
             "displayName": "",
             "givenName": "",
             "jobTitle": "",
             "mail": "",
             "mobilePhone": "",
             "officeLocation": "",
             "preferredLanguage": "",
             "surname": "",
             "userPrincipalName": ""
         }
     ]
}

operation: Remove Group Owner

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams from which you want to remove the specific user as a group owner.
Owner ID ID of the owner who you want to remove as the group owner of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
         "result": {
         "user_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Remove Group Member

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams from which you want to remove the specific user as a group member.
User ID ID of the user who you want to remove as the group member of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "user_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Create Channel

Input parameters

Parameter Description
Team/Group ID ID of team or group in that you want to create a new channel in Microsoft Teams.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel Name Name of the channel that you want to create in Microsoft Teams.
Description Description of the channel that you want to create in Microsoft Teams.
Membership Type Select the type of membership that would be allowed for the channel that you want to create in Microsoft Teams.
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the channel you want to create in Microsoft Team. The additional properties signify additional fields associated with the channel.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "displayName": "",
     "description": "",
     "email": "",
     "webUrl": ""
}

operation: Get Channel

Input parameters

Parameter Description
Team/Group ID ID of team or group that contains the channel whose information you want to retrieve from Microsoft Teams.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel whose information you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "@odata.count": "",
     "value": [
         {
             "id": "",
             "displayName": "",
             "description": "",
             "email": "",
             "webUrl": ""
         }
     ]
}

operation: Send Message

Input parameters

Parameter Description
Team/Group ID ID of team or group in Microsoft Teams to whom you want to send the group message.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel in Microsoft Teams on which you want to send the message.
Message Content of the group message that you want to send to a specific channel on a specific group or team in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "replyToId": "",
     "etag": "",
     "messageType": "",
     "createdDateTime": "",
     "lastModifiedDateTime": "",
     "deletedDateTime": "",
     "subject": "",
     "summary": "",
     "importance": "",
     "locale": "",
     "webUrl": "",
     "policyViolation": "",
     "from": {
         "application": "",
         "device": "",
         "conversation": "",
         "user": {
             "id": "",
             "displayName": "",
             "userIdentityType": ""
         }
     },
     "body": {
         "contentType": "",
         "content": ""
     },
     "attachments": [],
     "mentions": [
         {
             "id": 0,
             "mentionText": "",
             "mentioned": {
                 "application": "",
                 "device": "",
                 "conversation": "",
                 "user": {
                     "id": "",
                     "displayName": "",
                     "userIdentityType": ""
                 }
             }
         }
     ],
     "reactions": []
}

operation: Reply Message

Input parameters

Parameter Description
Group ID ID of Group in Microsoft Teams whose conversation information you want to retrieve and to which you want to reply.
Channel ID ID of the channel in Microsoft Teams on which you want to send the reply to the specific message.
Message ID ID of the message in Microsoft Teams to which you want to send a reply.
Message Content of the message that you want to send as a reply to the specified message.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "replyToId": "",
     "etag": "",
     "messageType": "",
     "createdDateTime": "",
     "lastModifiedDateTime": "",
     "deletedDateTime": "",
     "subject": "",
     "summary": "",
     "importance": "",
     "locale": "",
     "webUrl": "",
     "policyViolation": "",
     "from": {
         "application": "",
         "device": "",
         "conversation": "",
         "user": {
             "id": "",
             "displayName": "",
             "userIdentityType": ""
         }
     },
     "body": {
         "contentType": "",
         "content": ""
     },
     "attachments": [],
     "mentions": [],
     "reactions": []
}

operation: Messages Mention

Input parameters

Parameter Description
Team/Group ID ID of team or group in Microsoft Teams in which you want to add a mention of the specific user.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel in Microsoft Teams in which you want to add a mention of the specific user.
Message Content of the message in which you want to add a mention of the specific user.
User ID ID of the user who you want to mention in the message.
User Display Name Display name of the user who you want to mention in the message.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "replyToId": "",
     "etag": "",
     "messageType": "",
     "createdDateTime": "",
     "lastModifiedDateTime": "",
     "deletedDateTime": "",
     "subject": "",
     "summary": "",
     "importance": "",
     "locale": "",
     "webUrl": "",
     "policyViolation": "",
     "from": {
         "application": "",
         "device": "",
         "conversation": "",
         "user": {
             "id": "",
             "displayName": "",
             "userIdentityType": ""
         }
     },
     "body": {
         "contentType": "",
         "content": ""
     },
     "attachments": [],
     "mentions": [],
     "reactions": []
}

operation: Get Channel Messages

Input parameters

Parameter Description
Team/Group ID ID of team or group in Microsoft Teams from which you want to retrieve messages from the specified channel.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel in Microsoft Teams from which you retrieve messages.
Message ID ID of the message whose details you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "@odata.count": "",
     "value": [
         {
             "id": "",
             "replyToId": "",
             "etag": "",
             "messageType": "",
             "createdDateTime": "",
             "lastModifiedDateTime": "",
             "deletedDateTime": "",
             "subject": "",
             "summary": "",
             "importance": "",
             "locale": "",
             "webUrl": "",
             "policyViolation": "",
             "from": {
                 "application": "",
                 "device": "",
                 "conversation": "",
                 "user": {
                     "id": "",
                     "displayName": "",
                     "userIdentityType": ""
                 }
             },
             "body": {
                 "contentType": "",
                 "content": ""
             },
             "attachments": [],
             "mentions": [],
             "reactions": []
         }
     ]
}

operation: List User Joined Teams

Input parameters

Parameter Description
User ID ID of the user whose teams' membership information you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "@odata.count": "",
     "value": [
         {
             "id": "",
             "displayName": "",
             "description": "",
             "internalId": "",
             "classification": "",
             "specialization": "",
             "visibility": "",
             "webUrl": "",
             "isArchived": "",
             "memberSettings": "",
             "guestSettings": "",
             "messagingSettings": "",
             "funSettings": "",
             "discoverySettings": ""
         }
     ]
}

operation: Get Team

Input parameters

Parameter Description
Team/Group ID ID of team or group whose detailed information you want to retrieve from Microsoft Teams. from which you want to retrieve messages from the specified channel.
Note: Every team is associated with a group and the group has the same ID as the team.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "displayName": "",
     "description": "",
     "internalId": "",
     "classification": "",
     "specialization": "",
     "visibility": "",
     "webUrl": "",
     "isArchived": "",
     "discoverySettings": {
         "showInTeamsSearchAndSuggestions": ""
     },
     "memberSettings": {
         "allowCreateUpdateChannels": "",
         "allowDeleteChannels": "",
         "allowAddRemoveApps": "",
         "allowCreateUpdateRemoveTabs": "",
         "allowCreateUpdateRemoveConnectors": ""
     },
     "guestSettings": {
         "allowCreateUpdateChannels": "",
         "allowDeleteChannels": ""
     },
     "messagingSettings": {
         "allowUserEditMessages": "",
         "allowUserDeleteMessages": "",
         "allowOwnerDeleteMessages": "",
         "allowTeamMentions": "",
         "allowChannelMentions": ""
     },
     "funSettings": {
         "allowGiphy": "",
         "giphyContentRating": "",
         "allowStickersAndMemes": "",
         "allowCustomMemes": ""
     }
}

operation: Archive Team

Input parameters

Parameter Description
Team ID ID of an existing team that you want to archive in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

operation: Create Team

Input parameters

Parameter Description
Display Name Display name of the team that you want to create in Microsoft Teams.
Note: Maximum length for the team's display name is 256 characters.
Description (Optional) Description of the team that you want to create in Microsoft Teams.
Owner ID ID of the user who will be assigned as the owner of the team that you want to create in Microsoft Teams.
Bind Team Template Name of the Bind Team Template for the team that you want to create in Microsoft Teams.
Note: If you do not provide any value, the default template will be used.
Visibility Visibility to be set for the Office 365 group that you want to create in Microsoft Teams. You can choose from the following options: Private, Public, HiddenMembership, or "empty" (which is interpreted as Public).
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the team you want to create in Microsoft Team. The additional properties signify additional fields associated with the team.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": "",
     "displayName": ""
}

operation: Clone Team

Input parameters

Parameter Description
Team ID ID of the existing team whose clone you want to create in Microsoft Teams.
Display Name Display name of the team that you have cloned in Microsoft Teams.
Mail Nick Name Mail alias for the team that you have cloned in Microsoft Team, which must be unique in the organization. This parameter must be specified when a group is created or cloned. If this parameter is not specified, it will be computed from the Display Name.
Note: Known issue: This parameter is currently being ignored.
Parts to clone A CSV list of the parts of the team you want to clone. Legal parts are "apps", "tabs", "settings", "channels", and "members".
Visibility Visibility to be set for the team that you want to clone in Microsoft Teams. You can choose from the following options: Private, Public, HiddenMembership, or "empty" (which is interpreted as Public).

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

operation: Update Team

Input parameters

Parameter Description
Team ID ID of an existing team whose properties you want to update in Microsoft Teams.
Custom Properties Additional properties, in the JSON format, that you want to specify for the team you want to update in Microsoft Team. The additional properties signify additional fields associated with the team.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

operation: Unarchive Team

Input parameters

Parameter Description
Team ID ID of an existing team whose archive you want to restore from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

Included playbooks

The Sample - Microsoft Teams - 1.0.0 playbook collection comes bundled with the Microsoft Teams connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Microsoft Teams connector.

  • Add Group Member
  • Add Group Owner
  • Archive Team
  • Clone Team
  • Create Channel
  • Create Group
  • Create Team
  • Create User
  • Delete Group
  • Delete User
  • Get Channel
  • Get Channel Messages
  • Get Group Members
  • Get Group Owner
  • Get Groups
  • Get Team
  • Get Users
  • List User Joined Teams
  • Message Mention
  • Remove Group Member
  • Remove Group Owner
  • Reply Message
  • Send Message
  • Unarchive Team
  • Update Team
  • Update User

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

About the connector

Microsoft Teams is a chat-based workspace in Office 365 that provides global, remote, and dispersed teams with the ability to work together and share information using a common space.

This document provides information about the Microsoft Teams connector, which facilitates automated interactions, using the Microsoft Graph API using FortiSOAR™ playbooks. Add the Microsoft Teams connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically creating teams, adding users to teams or groups, retrieving details about users and teams, etc.

Version information

Connector Version: 1.0.0

Authored By: Community

Certified: No

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-microsoft-teams

Prerequisites to configuring the connector

Permissions required

To call the Microsoft Graph API, to perform any action, you must be assigned specific permissions as defined in this section. To learn more, including how to choose permissions, see Microsoft Graph permissions reference.

Action Name Permission Type Permissions (from least to most privileged)
Create user Delegated (work or school account) User.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application User.ReadWrite.All, Directory.ReadWrite.All
Get Users Delegated (work or school account) User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All,User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application User.ReadWrite.All, Directory.ReadWrite.All
Update User Delegated (work or school account) User.ReadWrite, User.ReadWrite.All, User.ManageIdentities.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) User.ReadWrite
Application User.ReadWrite.All, User.ManageIdentities.All, Directory.ReadWrite.All
Delete User Delegated (work or school account) User.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application User.ReadWrite.All
Create group Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.Create, Group.ReadWrite.All, Directory.ReadWrite.All
Delete Group/Team Delegated (work or school account) Group.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All
Get Group/Team Delegated (work or school account) Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
Add Group Owner Delegated (work or school account) GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Add Group Member Delegated (work or school account) GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Get Group Members Delegated (work or school account) GroupMember.Read.All, Group.Read.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.Read.All, Group.Read.All, Directory.Read.All, Directory.ReadWrite.All
Get Group Owner Delegated (work or school account) Group.Read.All and User.ReadBasic.All, Group.Read.All and User.Read.All, Group.Read.All and User.ReadWrite.All, Group.Read.All and User.Read.All and Application.Read.All
Delegated (personal Microsoft account) Not Supported.
Application Group.Read.All and User.Read.All, Group.Read.All and User.ReadWrite.All, Group.Read.All and User.Read.All and Application.Read.All
Remove Group Owner Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All
Remove Group Member Delegated (work or school account) GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegated (personal Microsoft account) Not Supported.
Application GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Create Channel Delegated (work or school account) Channel.Create, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Channel.Create.Group*, Channel.Create, Group.ReadWrite.All, Directory.ReadWrite.All
Get Channel Delegated (work or school account) Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All, ChannelSettings.Read.Group*, ChannelSettings.Edit.Group*, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Send Message Delegated (work or school account) ChannelMessage.Send, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Not Supported.
Reply Message Delegated (work or school account) ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application ChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Messages Mention Delegated (work or school account) ChannelMessage.Send, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Not Supported.
Get Channel Messages Delegated (work or school account) ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application ChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
List User Joined Teams Delegated (work or school account) Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Get Team Delegated (work or school account) Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Read.Group*, Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, TeamSettings.Edit.Group*, Group.Read.All, Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Archive Team Delegated (work or school account) TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Edit.Group*, TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Create Team Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All
Clone Team Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All
Update Team Delegated (work or school account) TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Edit.Group*, TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Unarchive Team Delegated (work or school account) TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not Supported.
Application TeamSettings.Edit.Group*, TeamSettings.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Microsoft Teams connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Microsoft Graph URL URL of the Microsoft Graph server to which you will connect and perform automated operations.
Token URL Token URL that is required to generate an OAuth token.
Directory (Tenant) ID Tenant ID of the application registered on the Microsoft Azure portal.
Application (Client) ID Unique ID of the application that is used to create the authentication token required to access the Microsoft Graph API.
Application (Client) Secret Unique Secret of the application that is used to create an authentication token required to access the Microsoft Graph API.
Username Username of the Microsoft Teams account you will use to perform automated operations.
Password Password of the Microsoft Teams account you will use to perform automated operations.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 onwards:

Function Description Annotation and Category
Create User Creates a new user in Microsoft Teams based on the display name, mail nickname, password, and other input parameters you have specified. create_user
Investigation
Get Users Retrieves details for users from Microsoft Teams based on the user ID or the user principal name you have specified.
Note: If no parameter is specified, then this operation returns details of all the users.
get_users
Investigation
Update User Updates the details of an existing Microsoft Teams user based on the user ID or the user principal name, and other input parameters you have specified. update_user
Investigation
Delete User Deletes an existing Microsoft Teams user based on the user ID or the user principal name you have specified.
Important: Once a user is deleted, the resources of the user are moved to a temporary container from which they can be restored within 30 days. After that time, they are permanently deleted.
delete_user
Investigation
Create Group Creates a new group in Microsoft Teams based on the display name, mail nickname, and other input parameters you have specified.
Note: You can create one of the following groups: Office 365 Group (Unified Group) or a Security Group.
create_group
Investigation
Delete Group/Team Deletes an existing Microsoft Teams group or team based on the team ID you have specified.
Important: Once a group or team is deleted, the Office 365 groups or teams are moved to a temporary container from which they can be restored within 30 days. After that time, they are permanently deleted.
delete_group
Investigation
Get Groups/Teams

Retrieves details for teams or groups from Microsoft Teams based on the group or team ID you have specified.
Note: If no parameter is specified, then this operation returns details of all the groups or teams.

get_groups
Investigation
Add Group Owner Adds a user as an owner of a specific Office 365 or Security Group in Microsoft Teams based on the group ID and user ID you have specified. add_owner
Investigation
Add Group Member Adds a user as a member of a specific Office 365 or Security Group in Microsoft Teams based on the group ID and user ID you have specified. add_member
Investigation
Get Group Members Retrieves a list of the direct members of a group from Microsoft Teams based on the group ID and user ID you have specified. A group can have users, contacts, devices, service principals, and other groups as its members. get_group_member
Investigation
Get Group Owner Retrieve a list of the owners of the specified group from Microsoft Teams based on the group ID you have specified get_group_owner
Investigation
Remove Group Owner Removes the specified owner for the specified group from Microsoft Teams based on the group ID and owner ID you have specified. remove_group_owner
Investigation
Remove Group Member Removes the specified user from the specified group in Microsoft Teams based on the group ID and user ID you have specified. remove_group_member
Investigation
Create Channel Creates a new channel in Microsoft Teams based on the team or group name, channel name, membership type, and other input parameters you have specified. create_channel
Investigation
Get Channel Retrieves information for a specified channel from Microsoft Teams based on the team or group ID and channel name you have specified. get_channel
Investigation
Send Message Sends chat messages to a specified channel in the specified group in Microsoft Teams based on the team or group ID, channel ID, and message you have specified. send_message
Investigation
Reply Message Replies to a specified chat message of a specified channel in the specified group in Microsoft Teams based on the group ID, channel ID, message ID, and message you have specified. reply_messages
Investigation
Messages Mention Adds a mention of a specific user to a specific message and channel in Microsoft Teams based on the team or group ID, channel ID, user ID, user display name, and message you have specified. messages_mention
Investigation
Get Channel Messages Retrieves a list of messages (without the replies) from a specific channel of a specific group in Microsoft Teams based on the team or group ID, channel ID, and optionally the message ID you have specified.
Note: If you specify the message ID then details of the specific message will be retrieved from Microsoft Teams.
get_channel_messages
Investigation
List User Joined Teams Retrieves the teams in which the specified user is a direct member from Microsoft Teams based on the user ID you have specified. list_user_joined_teams
Investigation
Get Team Retrieves detailed information about a team from Microsoft Teams based on the team or group ID you have specified. get_team
Investigation
Archive Team Archives the specified team in Microsoft Teams based on the team ID you have specified.
Note: When a team is archived, users can no longer send or like messages on any channel that is part of the archived team.
archive_team
Investigation
Create Team Creates a new team in Microsoft Teams based on the display name, description, and other input parameters you have specified. create_team
Investigation
Clone Team Creates a copy of a specified team in Microsoft Teams based on the team ID, display name, mail nick name, and other input parameters you have specified. This operation also creates a copy of the team's corresponding group. clone_team
Investigation
Update Team Updates the properties for an existing team in Microsoft Teams based on the team ID and properties you have specified. update_team
Investigation
Unarchive Team Restores an archived team in Microsoft Teams based on the team ID you have specified. Unarchiving a team restores the user's ability to send messages to the team and to edit the properties of the team. unarchive_team
Investigation

operation: Create User

Input parameters

Parameter Description
Display Name Name to display in the address book for the user that you want to create in Microsoft Teams.
Note: Maximum length for the user's display name is 256 characters.
Mail Nick Name Mail alias for the user that you want to create in Microsoft Teams.
Account Enabled Select this checkbox, i.e, set it to "true", to enable the newly created account in Microsoft Teams. By default, this is set as "false".
User Principal Name Principal name of the user, for example, someuser@contoso.com, that you want to create in Microsoft Teams.
Force Change Password Next SignIn Select this checkbox, i.e, set it to "true",  to force users to change their password when they sign in to Microsoft Teams the next time. Once the user has changed their password, this parameter automatically resets to false. By default, this is set as "false".
Password Password to be set for the user that you want to create in Microsoft Teams. You must set this password when you are creating a user in Microsoft Teams.
Passwords can be updated. However, the user will be required to change the password on their next login. The password must satisfy minimum requirements as specified by the "passwordPolicies" parameters of the user.
By default, a strong password is required.
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the user you want to create in Microsoft Team. The additional properties signify additional fields associated with the user.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "businessPhones": [],
     "displayName": "",
     "givenName": "",
     "jobTitle": "",
     "mail": "",
     "mobilePhone": "",
     "officeLocation": "",
     "preferredLanguage": "",
     "surname": "",
     "userPrincipalName": ""
}

operation: Get Users

Input parameters

Parameter Description
Based On

Parameter using which you want to retrieve details for a user from Microsoft Teams. You can choose between User ID or User Principal Name.

  • If you choose "User ID", then in the User ID field, you must specify the ID of the user whose details you want to retrieve from Microsoft Teams.
  • If you choose "User Principal Name", then in the User Principal Name field, you must specify the principal name of the user whose details you want to retrieve from Microsoft Teams. 

Note: If you do not specify this parameter, then details of all the users are returned.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "businessPhones": [],
             "displayName": "",
             "givenName": "",
             "jobTitle": "",
             "mail": "",
             "mobilePhone": null,
             "officeLocation": null,
             "preferredLanguage": null,
             "surname": "",
             "userPrincipalName": "",
             "id": ""
         }
     ]
}

operation: Update User

Input parameters

Parameter Description
Based On

Parameter using which you want to update the details of an existing Microsoft Teams user. You can choose between User ID or User Principal Name.

  • If you choose "User ID", then in the User ID field, you must specify the ID of the user whose details you want to update in Microsoft Teams.
  • If you choose "User Principal Name", then in the User Principal Name field, you must specify the principal name of the user whose details you want to update in Microsoft Teams. 
Display Name Display name that you want to update in the address book for the Microsoft Teams user.
Given Name Given name (first name) that you want to update for the Microsoft Teams user.
Surname Surname that you want to update for the Microsoft Teams user.
Job Title Job title that you want to update for the Microsoft Teams user.
Office Location Office location, i.e., the user's place of business that you want to update for the Microsoft Teams user.
Custom Properties (Optional) Additional properties, in the JSON format, that you want to update for the Microsoft Teams user. The additional properties signify additional fields associated with the user.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "id": "",
         "mail": "",
         "surname": "",
         "jobTitle": "",
         "givenName": "",
         "displayName": "",
         "mobilePhone": "",
         "@odata.context": "",
         "businessPhones": [],
         "officeLocation": "",
         "preferredLanguage": null,
         "userPrincipalName": ""
     },
     "status": "",
     "message": ""
}

operation: Delete User

Input parameters

Parameter Description
Based On

Parameter using which you want to delete an existing Microsoft Teams user. You can choose between User ID or User Principal Name.

  • If you choose "User ID", then in the User ID field, you must specify the ID of the user that you want to delete from Microsoft Teams.
  • If you choose "User Principal Name", then in the User Principal Name field, you must specify the principal name of the user that you want to delete from Microsoft Teams. 

Output

The output contains the following populated JSON schema:
{
     "result": {},
     "status": "",
     "message": ""
}

operation: Create Group

Input parameters

Parameter Description
Display Name Name to display in the address book for the group that you want to create in Microsoft Teams.
Note: Maximum length for the group's display name is 256 characters.
Mail Nickname Mail alias for the group that you want to create in Microsoft Teams.
Note: Spaces are not allowed in the mail alias for the group.
Email Enabled Select this checkbox for  "mail-enabled" groups.
Security Enabled Select this checkbox only for "security-enabled" groups, including Office 365 groups.
Description (Optional) Description of the group that you want to create in Microsoft Teams.
Visibility Visibility to be set for the Office 365 group that you want to create in Microsoft Teams. You can choose from the following options: Private, Public, HiddenMembership, or "empty" (which is interpreted as Public).
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the group you want to create in Microsoft Team. The additional properties signify additional fields associated with the group.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "deletedDateTime": "",
     "classification": "",
     "createdDateTime": "",
     "creationOptions": [],
     "description": "",
     "displayName": "",
     "groupTypes": [
         ""
     ],
     "isAssignableToRole": "",
     "mail": "",
     "mailEnabled": "",
     "mailNickname": "",
     "onPremisesDomainName": "",
     "onPremisesLastSyncDateTime": "",
     "onPremisesNetBiosName": "",
     "onPremisesSamAccountName": "",
     "onPremisesSecurityIdentifier": "",
     "onPremisesSyncEnabled": "",
     "preferredDataLocation": "",
     "proxyAddresses": [
         ""
     ],
     "renewedDateTime": "",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": "",
     "securityIdentifier": "",
     "visibility": "",
     "onPremisesProvisioningErrors": []
}

operation: Delete Group/Team

Input parameters

Parameter Description
Team ID ID of the group or team that you want to delete from Microsoft Teams.
Note: Every team is associated with a group and the group has the same ID as the team.

Output

The output contains the following populated JSON schema:
{
     "result": {},
     "status": "",
     "message": ""
}

operation: Get Groups/Teams

Input parameters

Parameter Description
Group ID ID of the group or team whose details you want to retrieve from Microsoft Teams.
Note: If you do not specify this parameter, then details of all the users are returned.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "id": "",
             "deletedDateTime": "",
             "classification": "",
             "createdDateTime": "",
             "creationOptions": [],
             "description": "",
             "displayName": "",
             "expirationDateTime": "",
             "groupTypes": [],
             "isAssignableToRole": "",
             "mail": "",
             "mailEnabled": "",
             "mailNickname": "",
             "membershipRule": "",
             "membershipRuleProcessingState": "",
             "onPremisesDomainName": "",
             "onPremisesLastSyncDateTime": "",
             "onPremisesNetBiosName": "",
             "onPremisesSamAccountName": "",
             "onPremisesSecurityIdentifier": "",
             "onPremisesSyncEnabled": "",
             "preferredDataLocation": "",
             "preferredLanguage": "",
             "proxyAddresses": [],
             "renewedDateTime": "",
             "resourceBehaviorOptions": [],
             "resourceProvisioningOptions": [],
             "securityEnabled": "",
             "securityIdentifier": "",
             "theme": null,
             "visibility": "",
             "onPremisesProvisioningErrors": []
         }
     ]
}

operation: Add Group Owner

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams to which you want to add the specific user as a group owner.
User ID ID of the user who you want to add as the group owner of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "user_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Add Group Member

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams to which you want to add the specific user as a member.
User ID ID of the user who you want to add as a member of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "owner_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Get Group Members

Input parameters

Parameter Description
Group ID ID of the group whose direct members you want to retrieve from Microsoft Teams.
User ID ID of the member belonging to the specified group whose details you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "@odata.type": "",
             "id": "",
             "businessPhones": [],
             "displayName": "",
             "givenName": "",
             "jobTitle": "",
             "mail": "",
             "mobilePhone": "",
             "officeLocation": "",
             "preferredLanguage": "",
             "surname": "",
             "userPrincipalName": ""
         }
     ]
}

operation: Get Group Owner

Input parameters

Parameter Description
Group ID ID of the group whose group owner details you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "@odata.type": "",
             "id": "",
             "businessPhones": [],
             "displayName": "",
             "givenName": "",
             "jobTitle": "",
             "mail": "",
             "mobilePhone": "",
             "officeLocation": "",
             "preferredLanguage": "",
             "surname": "",
             "userPrincipalName": ""
         }
     ]
}

operation: Remove Group Owner

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams from which you want to remove the specific user as a group owner.
Owner ID ID of the owner who you want to remove as the group owner of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
         "result": {
         "user_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Remove Group Member

Input parameters

Parameter Description
Group ID ID of the group in Microsoft Teams from which you want to remove the specific user as a group member.
User ID ID of the user who you want to remove as the group member of the specified group in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "user_id": "",
         "group_id": ""
     },
     "status": "",
     "message": ""
}

operation: Create Channel

Input parameters

Parameter Description
Team/Group ID ID of team or group in that you want to create a new channel in Microsoft Teams.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel Name Name of the channel that you want to create in Microsoft Teams.
Description Description of the channel that you want to create in Microsoft Teams.
Membership Type Select the type of membership that would be allowed for the channel that you want to create in Microsoft Teams.
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the channel you want to create in Microsoft Team. The additional properties signify additional fields associated with the channel.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "displayName": "",
     "description": "",
     "email": "",
     "webUrl": ""
}

operation: Get Channel

Input parameters

Parameter Description
Team/Group ID ID of team or group that contains the channel whose information you want to retrieve from Microsoft Teams.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel whose information you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "@odata.count": "",
     "value": [
         {
             "id": "",
             "displayName": "",
             "description": "",
             "email": "",
             "webUrl": ""
         }
     ]
}

operation: Send Message

Input parameters

Parameter Description
Team/Group ID ID of team or group in Microsoft Teams to whom you want to send the group message.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel in Microsoft Teams on which you want to send the message.
Message Content of the group message that you want to send to a specific channel on a specific group or team in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "replyToId": "",
     "etag": "",
     "messageType": "",
     "createdDateTime": "",
     "lastModifiedDateTime": "",
     "deletedDateTime": "",
     "subject": "",
     "summary": "",
     "importance": "",
     "locale": "",
     "webUrl": "",
     "policyViolation": "",
     "from": {
         "application": "",
         "device": "",
         "conversation": "",
         "user": {
             "id": "",
             "displayName": "",
             "userIdentityType": ""
         }
     },
     "body": {
         "contentType": "",
         "content": ""
     },
     "attachments": [],
     "mentions": [
         {
             "id": 0,
             "mentionText": "",
             "mentioned": {
                 "application": "",
                 "device": "",
                 "conversation": "",
                 "user": {
                     "id": "",
                     "displayName": "",
                     "userIdentityType": ""
                 }
             }
         }
     ],
     "reactions": []
}

operation: Reply Message

Input parameters

Parameter Description
Group ID ID of Group in Microsoft Teams whose conversation information you want to retrieve and to which you want to reply.
Channel ID ID of the channel in Microsoft Teams on which you want to send the reply to the specific message.
Message ID ID of the message in Microsoft Teams to which you want to send a reply.
Message Content of the message that you want to send as a reply to the specified message.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "replyToId": "",
     "etag": "",
     "messageType": "",
     "createdDateTime": "",
     "lastModifiedDateTime": "",
     "deletedDateTime": "",
     "subject": "",
     "summary": "",
     "importance": "",
     "locale": "",
     "webUrl": "",
     "policyViolation": "",
     "from": {
         "application": "",
         "device": "",
         "conversation": "",
         "user": {
             "id": "",
             "displayName": "",
             "userIdentityType": ""
         }
     },
     "body": {
         "contentType": "",
         "content": ""
     },
     "attachments": [],
     "mentions": [],
     "reactions": []
}

operation: Messages Mention

Input parameters

Parameter Description
Team/Group ID ID of team or group in Microsoft Teams in which you want to add a mention of the specific user.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel in Microsoft Teams in which you want to add a mention of the specific user.
Message Content of the message in which you want to add a mention of the specific user.
User ID ID of the user who you want to mention in the message.
User Display Name Display name of the user who you want to mention in the message.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "replyToId": "",
     "etag": "",
     "messageType": "",
     "createdDateTime": "",
     "lastModifiedDateTime": "",
     "deletedDateTime": "",
     "subject": "",
     "summary": "",
     "importance": "",
     "locale": "",
     "webUrl": "",
     "policyViolation": "",
     "from": {
         "application": "",
         "device": "",
         "conversation": "",
         "user": {
             "id": "",
             "displayName": "",
             "userIdentityType": ""
         }
     },
     "body": {
         "contentType": "",
         "content": ""
     },
     "attachments": [],
     "mentions": [],
     "reactions": []
}

operation: Get Channel Messages

Input parameters

Parameter Description
Team/Group ID ID of team or group in Microsoft Teams from which you want to retrieve messages from the specified channel.
Note: Every team is associated with a group and the group has the same ID as the team.
Channel ID ID of the channel in Microsoft Teams from which you retrieve messages.
Message ID ID of the message whose details you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "@odata.count": "",
     "value": [
         {
             "id": "",
             "replyToId": "",
             "etag": "",
             "messageType": "",
             "createdDateTime": "",
             "lastModifiedDateTime": "",
             "deletedDateTime": "",
             "subject": "",
             "summary": "",
             "importance": "",
             "locale": "",
             "webUrl": "",
             "policyViolation": "",
             "from": {
                 "application": "",
                 "device": "",
                 "conversation": "",
                 "user": {
                     "id": "",
                     "displayName": "",
                     "userIdentityType": ""
                 }
             },
             "body": {
                 "contentType": "",
                 "content": ""
             },
             "attachments": [],
             "mentions": [],
             "reactions": []
         }
     ]
}

operation: List User Joined Teams

Input parameters

Parameter Description
User ID ID of the user whose teams' membership information you want to retrieve from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "@odata.count": "",
     "value": [
         {
             "id": "",
             "displayName": "",
             "description": "",
             "internalId": "",
             "classification": "",
             "specialization": "",
             "visibility": "",
             "webUrl": "",
             "isArchived": "",
             "memberSettings": "",
             "guestSettings": "",
             "messagingSettings": "",
             "funSettings": "",
             "discoverySettings": ""
         }
     ]
}

operation: Get Team

Input parameters

Parameter Description
Team/Group ID ID of team or group whose detailed information you want to retrieve from Microsoft Teams. from which you want to retrieve messages from the specified channel.
Note: Every team is associated with a group and the group has the same ID as the team.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "id": "",
     "displayName": "",
     "description": "",
     "internalId": "",
     "classification": "",
     "specialization": "",
     "visibility": "",
     "webUrl": "",
     "isArchived": "",
     "discoverySettings": {
         "showInTeamsSearchAndSuggestions": ""
     },
     "memberSettings": {
         "allowCreateUpdateChannels": "",
         "allowDeleteChannels": "",
         "allowAddRemoveApps": "",
         "allowCreateUpdateRemoveTabs": "",
         "allowCreateUpdateRemoveConnectors": ""
     },
     "guestSettings": {
         "allowCreateUpdateChannels": "",
         "allowDeleteChannels": ""
     },
     "messagingSettings": {
         "allowUserEditMessages": "",
         "allowUserDeleteMessages": "",
         "allowOwnerDeleteMessages": "",
         "allowTeamMentions": "",
         "allowChannelMentions": ""
     },
     "funSettings": {
         "allowGiphy": "",
         "giphyContentRating": "",
         "allowStickersAndMemes": "",
         "allowCustomMemes": ""
     }
}

operation: Archive Team

Input parameters

Parameter Description
Team ID ID of an existing team that you want to archive in Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

operation: Create Team

Input parameters

Parameter Description
Display Name Display name of the team that you want to create in Microsoft Teams.
Note: Maximum length for the team's display name is 256 characters.
Description (Optional) Description of the team that you want to create in Microsoft Teams.
Owner ID ID of the user who will be assigned as the owner of the team that you want to create in Microsoft Teams.
Bind Team Template Name of the Bind Team Template for the team that you want to create in Microsoft Teams.
Note: If you do not provide any value, the default template will be used.
Visibility Visibility to be set for the Office 365 group that you want to create in Microsoft Teams. You can choose from the following options: Private, Public, HiddenMembership, or "empty" (which is interpreted as Public).
Custom Properties (Optional) Additional properties, in the JSON format, that you want to specify for the team you want to create in Microsoft Team. The additional properties signify additional fields associated with the team.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": "",
     "displayName": ""
}

operation: Clone Team

Input parameters

Parameter Description
Team ID ID of the existing team whose clone you want to create in Microsoft Teams.
Display Name Display name of the team that you have cloned in Microsoft Teams.
Mail Nick Name Mail alias for the team that you have cloned in Microsoft Team, which must be unique in the organization. This parameter must be specified when a group is created or cloned. If this parameter is not specified, it will be computed from the Display Name.
Note: Known issue: This parameter is currently being ignored.
Parts to clone A CSV list of the parts of the team you want to clone. Legal parts are "apps", "tabs", "settings", "channels", and "members".
Visibility Visibility to be set for the team that you want to clone in Microsoft Teams. You can choose from the following options: Private, Public, HiddenMembership, or "empty" (which is interpreted as Public).

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

operation: Update Team

Input parameters

Parameter Description
Team ID ID of an existing team whose properties you want to update in Microsoft Teams.
Custom Properties Additional properties, in the JSON format, that you want to specify for the team you want to update in Microsoft Team. The additional properties signify additional fields associated with the team.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

operation: Unarchive Team

Input parameters

Parameter Description
Team ID ID of an existing team whose archive you want to restore from Microsoft Teams.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "message": ""
}

Included playbooks

The Sample - Microsoft Teams - 1.0.0 playbook collection comes bundled with the Microsoft Teams connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Microsoft Teams connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.